6.3.4 Handling Local Macros

Feature tests offered by Autoconf do not cover all needs. People often have to supplement existing tests with their own macros, or with third-party macros.

There are two ways to organize custom macros in a package.

The first possibility (the historical practice) is to list all your macros in ‘acinclude.m4’. This file will be included in ‘aclocal.m4’ when you run aclocal, and its macro(s) will henceforth be visible to autoconf. However if it contains numerous macros, it will rapidly become difficult to maintain, and it will be almost impossible to share macros between packages.

The second possibility, which we do recommend, is to write each macro in its own file and gather all these files in a directory. This directory is usually called ‘m4/’. To build ‘aclocal.m4’, one should therefore instruct aclocal to scan ‘m4/’. From the command line, this is done with ‘aclocal -I m4’. The top-level ‘Makefile.am’ should also be updated to define

ACLOCAL_AMFLAGS = -I m4

ACLOCAL_AMFLAGS contains options to pass to aclocal when ‘aclocal.m4’ is to be rebuilt by make. This line is also used by autoreconf (see (autoconf)autoreconf Invocation section `Using autoreconf to Update ‘configure’ Scripts' in The Autoconf Manual) to run aclocal with suitable options, or by autopoint (see (gettext)autopoint Invocation section `Invoking the autopoint Program' in GNU gettext tools) and gettextize (see (gettext)gettextize Invocation section `Invoking the gettextize Program' in GNU gettext tools) to locate the place where Gettext's macros should be installed. So even if you do not really care about the rebuild rules, you should define ACLOCAL_AMFLAGS.

When ‘aclocal -I m4’ is run, it will build an ‘aclocal.m4’ that m4_includes any file from ‘m4/’ that defines a required macro. Macros not found locally will still be searched in system-wide directories, as explained in Macro Search Path.

Custom macros should be distributed for the same reason that ‘configure.ac’ is: so that other people have all the sources of your package if they want to work on it. Actually, this distribution happens automatically because all m4_included files are distributed.

However there is no consensus on the distribution of third-party macros that your package may use. Many libraries install their own macro in the system-wide aclocal directory (see section Writing your own aclocal macros). For instance, Guile ships with a file called ‘guile.m4’ that contains the macro GUILE_FLAGS that can be used to define setup compiler and linker flags appropriate for using Guile. Using GUILE_FLAGS in ‘configure.ac’ will cause aclocal to copy ‘guile.m4’ into ‘aclocal.m4’, but as ‘guile.m4’ is not part of the project, it will not be distributed. Technically, that means a user who needs to rebuild ‘aclocal.m4’ will have to install Guile first. This is probably OK, if Guile already is a requirement to build the package. However, if Guile is only an optional feature, or if your package might run on architectures where Guile cannot be installed, this requirement will hinder development. An easy solution is to copy such third-party macros in your local ‘m4/’ directory so they get distributed.

Since Automake 1.10, aclocal offers an option to copy these system-wide third-party macros in your local macro directory, solving the above problem. Simply use:

ACLOCAL_AMFLAGS = -I m4 --install

With this setup, system-wide macros will be copied to ‘m4/’ the first time you run autoreconf. Then the locally installed macros will have precedence over the system-wide installed macros each time aclocal is run again.

One reason why you should keep ‘--install’ in the flags even after the first run is that when you later edit ‘configure.ac’ and depend on a new macro, this macro will be installed in your ‘m4/’ automatically. Another one is that serial numbers (see section Serial Numbers) can be used to update the macros in your source tree automatically when new system-wide versions are installed. A serial number should be a single line of the form

#serial NNN

where NNN contains only digits and dots. It should appear in the M4 file before any macro definition. It is a good practice to maintain a serial number for each macro you distribute, even if you do not use the ‘--install’ option of aclocal: this allows other people to use it.