Next: Serial Numbers, Previous: Writing your own aclocal macros, Up: Auto-generating aclocal.m4 [Contents][Index]
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 Using autoreconf
to Update configure Scripts in The Autoconf Manual) to run aclocal
with suitable
options, or by autopoint
(see Invoking the autopoint
Program in GNU gettext tools)
and gettextize
(see 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_include
s 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_include
d 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 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 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.
Next: Serial Numbers, Previous: Writing your own aclocal macros, Up: Auto-generating aclocal.m4 [Contents][Index]