automake-1.16: Local Macros
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/’. Then it’s enough to update
‘configure.ac’ by adding a proper call to ‘AC_CONFIG_MACRO_DIRS’:
AC_CONFIG_MACRO_DIRS([m4])
‘aclocal’ will then take care of automatically adding ‘m4/’ to its
search path for m4 files.
When ‘aclocal’ 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. In fact, 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 (⇒Extending
aclocal). 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 the option ‘--install’ to copy
these system-wide third-party macros in your local macro directory,
helping to solve the above problem.
With this setup, system-wide macros will be copied to ‘m4/’ the first
time you run ‘aclocal’. 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 (⇒Serials) 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.
Info Catalog
automake-1.16: Extending aclocal
automake-1.16: aclocal Invocation
automake-1.16: Serials