6.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros that can be used in your package (see section Autoconf macros supplied with Automake); some of them are actually required by Automake in certain situations. These macros must be defined in your ‘aclocal.m4’; otherwise they will not be seen by autoconf.

The aclocal program will automatically generate ‘aclocal.m4’ files based on the contents of ‘configure.ac’. This provides a convenient way to get Automake-provided macros, without having to search around. The aclocal mechanism allows other packages to supply their own macros (see section Writing your own aclocal macros). You can also use it to maintain your own set of custom macros (see section Handling Local Macros).

At startup, aclocal scans all the ‘.m4’ files it can find, looking for macro definitions (see section Macro Search Path). Then it scans ‘configure.ac’. Any mention of one of the macros found in the first step causes that macro, and any macros it in turn requires, to be put into ‘aclocal.m4’.

Putting the file that contains the macro definition into ‘aclocal.m4’ is usually done by copying the entire text of this file, including unused macro definitions as well as both ‘#’ and ‘dnl’ comments. If you want to make a comment that will be completely ignored by aclocal, use ‘##’ as the comment leader.

When a file selected by aclocal is located in a subdirectory specified as a relative search path with aclocal's ‘-I’ argument, aclocal assumes the file belongs to the package and uses m4_include instead of copying it into ‘aclocal.m4’. This makes the package smaller, eases dependency tracking, and cause the file to be distributed automatically. (See section Handling Local Macros, for an example.) Any macro that is found in a system-wide directory, or via an absolute search path will be copied. So use ‘-I `pwd`/reldir’ instead of ‘-I reldir’ whenever some relative directory need to be considered outside the package.

The contents of ‘acinclude.m4’, if this file exists, are also automatically included in ‘aclocal.m4’. We recommend against using ‘acinclude.m4’ in new packages (see section Handling Local Macros).

While computing ‘aclocal.m4’, aclocal runs autom4te (see (autoconf)Using autom4te section `Using Autom4te' in The Autoconf Manual) in order to trace the macros that are really used, and omit from ‘aclocal.m4’ all macros that are mentioned but otherwise unexpanded (this can happen when a macro is called conditionally). autom4te is expected to be in the PATH, just as autoconf. Its location can be overridden using the AUTOM4TE environment variable.