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 automake 1.6.x, APIVERSION = 1.6.

acdir

This directory is intended for third party .m4 files, and is configured when automake itself is built. This 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).

As an example, suppose that automake-1.6.2 was configured with --prefix=/usr/local. Then, the search path would be:

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

As explained in (see aclocal options), there are several options that can be used to change or extend this search path.

Modifying the macro search path: --acdir

The most obvious option to modify the search path is --acdir=dir, which changes default directory and drops the APIVERSION directory. For example, if one specifies --acdir=/opt/private/, then the search path becomes:

1. /opt/private/

Note that this option, --acdir, is intended for use by the internal automake test suite only; it is not ordinarily needed by end-users.

Modifying the macro search path: -I dir

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:

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 directories, one per line, to be added to the search list. These directories are searched after all other directories.

For example, suppose acdir/dirlist contains the following:

     /test1
     /test2
     

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

If the --acdir=dir option is used, then aclocal will search for the dirlist file in dir. In the --acdir=/opt/private/ example above, aclocal would look for /opt/private/dirlist. Again, however, the --acdir option is intended for use by the internal automake test suite only; --acdir is not ordinarily needed by end-users.

dirlist is useful in the following situation: suppose that automake version 1.6.2 is installed with $prefix=/usr by the system vendor. Thus, the default search directories are

1. /usr/share/aclocal-1.6/
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. 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 the file

/usr/share/aclocal/dirlist

which contains only the single line

/usr/local/share/aclocal

Now, the "default" search path on the affected system is

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

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 Automake on your account and want aclocal to look for macros installed at other places on the system.