5.5.3 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.