6.3.2.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 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 ‘--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 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.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.