automake-1.16: Macro Search Path
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 (⇒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’ (⇒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 (⇒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 (⇒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 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’
...............................................
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 (⇒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 honored too, ⇒Serials.
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!_
Info Catalog
automake-1.16: aclocal Options
automake-1.16: aclocal Invocation
automake-1.16: Extending aclocal