6.3.2 Macro Search Path ¶

By default, aclocal searches for .m4 files in the following directories, in this order:

acdir-APIVERSION

This is where the .m4 macros distributed with Automake itself are stored. APIVERSION depends on the Automake release used; for example, for Automake 1.11.x, APIVERSION = 1.11.

acdir

This directory is intended for third party .m4 files, and is configured when automake itself is built. It is @datadir@/aclocal/, which typically expands to ${prefix}/share/aclocal/. To find the compiled-in value of acdir, use the --print-ac-dir option (see aclocal Options).

For example, suppose that Automake 1.11.2 was configured with --prefix=/usr/local. Then, the search path would be:

1. /usr/local/share/aclocal-1.11.2/
2. /usr/local/share/aclocal/

The paths for the acdir and acdir-APIVERSION directories can be changed respectively through the aclocal options --system-acdir and --automake-acdir (see aclocal Options). These options are not ordinarily needed by end-users; they’re mainly intended for use by the Automake test suite, or for debugging.

As also listed in (see aclocal Options), several other options can be used to change or extend the macro search path.

Modifying the Macro Search Path: ‘-I dir’ ¶

Any 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:

1. /foo
2. /bar
3. acdir-APIVERSION
4. acdir

Modifying the Macro Search Path: dirlist ¶

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

1. /foo
2. /bar
3. acdir-APIVERSION
4. acdir
5. /test1
6. /test2
7. all directories with path names starting with /test3.

If the --system-acdir=dir option is used, then aclocal will search for the dirlist file in that dir.

dirlist is useful in the following situation: suppose that Automake 1.11.2 is installed with ‘--prefix=/usr’ by the system vendor. Thus, the default search directories are

1. /usr/share/aclocal-1.11/
2. /usr/share/aclocal/

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. Without dirlist, 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 can create a file /usr/share/aclocal/dirlist containing the single line

/usr/local/share/aclocal

Now, the “default” search path on the affected system is

1. /usr/share/aclocal-1.11/
2. /usr/share/aclocal/
3. /usr/local/share/aclocal/

This way, -I options can be reserved for project-specific needs (my-source-dir/m4/), rather than using them 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.

Modifying the Macro Search Path: --aclocal-path/ACLOCAL_PATH ¶

The fourth and last mechanism to customize the macro search path: any directory included in the colon-separated path given to the --aclocal-path command-line option, or (if the option is not specified) in the ACLOCAL_PATH environment variable, is added to the search path. These directories take 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/ACLOCAL_PATH.

If the --install option is used, any .m4 file containing a required macro that is found in a directory listed in --aclocal-path/ACLOCAL_PATH will be installed locally. In this case, serial numbers in .m4 are honored too (see Serial Numbers).

--aclocal-path/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. This is more or less the opposite of dirlist.

Possible future incompatibility in aclocal ¶

The order in which the directories in the macro search path are currently looked up is confusing and/or suboptimal in various aspects. In particular, directories in --aclocal-path/ACLOCAL_PATH and acdir might end up taking precedence over acdir-APIVERSION, and directories in acdir/dirlist might end up taking precedence over acdir. There are no definite plans to change the current behavior, but if bug reports show the need (so please report issues), the default might need to be changed, and the current behavior retained as an option.