Invoking aclocal (automake)

6.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros that can be used in your package (see 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 Writing your own aclocal macros). You can also use it to maintain your own set of custom macros (see Handling Local Macros).

At startup, aclocal scans all the .m4 files it can find, looking for macro definitions (see 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 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 should 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 Handling Local Macros).

While computing aclocal.m4, aclocal runs autom4te (see 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.