By default, aclocal searches for .m4 files in the following directories, in this order:
As an example, suppose that automake-1.11.2 was configured with --prefix=/usr/local. Then, the search path would be:
The paths for the acdir and acdir-APIVERSION directories can be changed respectively through aclocal options --system-acdir and --automake-acdir (see aclocal Options). Note however that these options are only intended for use by the internal Automake test suite, or for debugging under highly unusual situations; they are not ordinarily needed by end-users.
As explained in (see aclocal Options), there are several options that can be used to change or extend this search path.
Any extra directories specified using -I options (see aclocal Options) are prepended to this search list. Thus, ‘aclocal -I /foo -I /bar’ results in the following search path:
There is a third mechanism for customizing the search path. If a
dirlist file exists in acdir, then that file is assumed to
contain a list of directory patterns, one per line. aclocal
expands these patterns to directory names, and adds them to the search
list after all other directories. dirlist entries may
use shell wildcards such as ‘*’, ‘?’, or
For example, suppose acdir/dirlist contains the following:
/test1 /test2 /test3*
and that aclocal was called with the ‘-I /foo -I /bar’ options. Then, the search path would be
and all directories with path names starting with
If the --system-acdir=dir option is used, then aclocal will search for the dirlist file in dir; but remember the warnings above against the use of --system-acdir.
dirlist is useful in the following situation: suppose that
1.11.2 is installed with
‘--prefix=/usr’ by the system vendor. Thus, the default search
However, suppose further that many packages have been manually installed on the system, with $prefix=/usr/local, as is typical. In that case, many of these “extra” .m4 files are in /usr/local/share/aclocal. The only way to force /usr/bin/aclocal to find these “extra” .m4 files is to always call ‘aclocal -I /usr/local/share/aclocal’. This is inconvenient. With dirlist, one may create a file /usr/share/aclocal/dirlist containing only the single line
Now, the “default” search path on the affected system is
without the need for -I options; -I options can be reserved for project-specific needs (my-source-dir/m4/), rather than using it to work around local system-dependent tool installation directories.
Similarly, dirlist can be handy if you have installed a local copy of Automake in your account and want aclocal to look for macros installed at other places on the system.
The fourth and last mechanism to customize the macro search path is also the simplest. Any directory included in the colon-separated environment variable ACLOCAL_PATH is added to the search path and takes precedence over system directories (including those found via dirlist), with the exception of the versioned directory acdir-APIVERSION (see Macro Search Path). However, directories passed via -I will take precedence over directories in ACLOCAL_PATH.
Also note that, if the --install option is used, any .m4 file containing a required macro that is found in a directory listed in ACLOCAL_PATH will be installed locally. In this case, serial numbers in .m4 are honoured too, see Serials.
Conversely to dirlist, ACLOCAL_PATH is useful if you are using a global copy of Automake and want aclocal to look for macros somewhere under your home directory.
The order in which the directories in the macro search path are currently looked up is confusing and/or suboptimal in various aspects, and is probably going to be changed in the future Automake release. In particular, directories in ACLOCAL_PATH and acdir might end up taking precedence over acdir-APIVERSION, and directories in acdir/dirlist might end up taking precedence over acdir. This is a possible future incompatibility!