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 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 you can 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_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. In fact, this distribution
happens automatically because all m4_included files are
distributed.
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
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
(see Serial Numbers) can be used to update the macros in your source tree
automatically when new system-wide versions are installed. It is 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.