8.7 aclocal Invocation

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

When aclocal is run, it scans your configure.ac for macros that you have used beyond the default ones provided by Autoconf. These include macros provided with Automake as well as any other custom macros. aclocal makes these macros available to autoconf by placing them in a file called aclocal.m4.

However, you should not usually need to run aclocal yourself, as it is run automatically by autoreconf. Using autoreconf will protect you against any future changes to the aclocal command, which are expected. (Some people install Automake to use aclocal to manage custom M4 macros without actually using Automake otherwise, so it’s possible that this functionality will cease to be offered as part of Automake.)

We can expand on the flowchart introduced in System overview to show the role of aclocal.

                 configure.ac
[local macros]  ____/|
     |         /     |
     |        |      |
     |        V      |
     `--->(aclocal)  |
              |      |
              V      |
          aclocal.m4 |
               \____ |
                    \|
                     |
                     V
                 (autoconf)
                     |
                     |
                     V
                  configure

See Custom 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 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 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.