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. 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 section aclocal Options).

As an 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 aclocal options ‘--system-acdir’ and ‘--automake-acdir’ (see section 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 section aclocal Options), there are several options that can be used to change or extend this search path.

Modifying the Macro Search Path: ‘-I dir’

Any extra directories specified using ‘-I’ options (see section 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

and 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 dir; but remember the warnings above against the use of ‘--system-acdir’.

‘dirlist’ is useful in the following situation: suppose that automake version 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’. 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

/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/

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.

Modifying the Macro Search Path: ‘ACLOCAL_PATH’

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 section 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 section Serial Numbers.

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.

Planned future incompatibilities

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!

This document was generated on January 25, 2014 using texi2html 5.0.