automake: Macro Search Path

1 
1 6.3.2 Macro Search Path
1 -----------------------
1 
1 By default, ‘aclocal’ searches for ‘.m4’ files in the following
1 directories, in this order:
1 
1 ‘ACDIR-APIVERSION’
1      This is where the ‘.m4’ macros distributed with Automake itself are
1      stored.  APIVERSION depends on the Automake release used; for
1      example, for Automake 1.11.x, APIVERSION = ‘1.11’.
1 
1 ‘ACDIR’
1      This directory is intended for third party ‘.m4’ files, and is
1      configured when ‘automake’ itself is built.  This is
1      ‘@datadir@/aclocal/’, which typically expands to
1      ‘${prefix}/share/aclocal/’.  To find the compiled-in value of
1      ACDIR, use the ‘--print-ac-dir’ option (⇒aclocal Options).
1 
1    As an example, suppose that ‘automake-1.11.2’ was configured with
1 ‘--prefix=/usr/local’.  Then, the search path would be:
1 
1   1. ‘/usr/local/share/aclocal-1.11.2/’
1   2. ‘/usr/local/share/aclocal/’
1 
1    The paths for the ACDIR and ACDIR-APIVERSION directories can be
1 changed respectively through aclocal options ‘--system-acdir’ and
1 ‘--automake-acdir’ (⇒aclocal Options).  Note however that these
1 options are only intended for use by the internal Automake test suite,
1 or for debugging under highly unusual situations; they are not
1 ordinarily needed by end-users.
1 
1    As explained in (⇒aclocal Options), there are several options
1 that can be used to change or extend this search path.
1 
1 Modifying the Macro Search Path: ‘-I DIR’
1 .........................................
1 
11 Any extra directories specified using ‘-I’ options (⇒aclocal
 Options) are _prepended_ to this search list.  Thus, ‘aclocal -I /foo
1 -I /bar’ results in the following search path:
1 
1   1. ‘/foo’
1   2. ‘/bar’
1   3. ACDIR-APIVERSION
1   4. ACDIR
1 
1 Modifying the Macro Search Path: ‘dirlist’
1 ..........................................
1 
1 There is a third mechanism for customizing the search path.  If a
1 ‘dirlist’ file exists in ACDIR, then that file is assumed to contain a
1 list of directory patterns, one per line.  ‘aclocal’ expands these
1 patterns to directory names, and adds them to the search list _after_
1 all other directories.  ‘dirlist’ entries may use shell wildcards such
1 as ‘*’, ‘?’, or ‘[...]’.
1 
1    For example, suppose ‘ACDIR/dirlist’ contains the following:
1 
1      /test1
1      /test2
1      /test3*
1 
1 and that ‘aclocal’ was called with the ‘-I /foo -I /bar’ options.  Then,
1 the search path would be
1 
1   1. ‘/foo’
1   2. ‘/bar’
1   3. ACDIR-APIVERSION
1   4. ACDIR
1   5. ‘/test1’
1   6. ‘/test2’
1 
1 and all directories with path names starting with ‘/test3’.
1 
1    If the ‘--system-acdir=DIR’ option is used, then ‘aclocal’ will
1 search for the ‘dirlist’ file in DIR; but remember the warnings above
1 against the use of ‘--system-acdir’.
1 
1    ‘dirlist’ is useful in the following situation: suppose that
1 ‘automake’ version ‘1.11.2’ is installed with ‘--prefix=/usr’ by the
1 system vendor.  Thus, the default search directories are
1 
1   1. ‘/usr/share/aclocal-1.11/’
1   2. ‘/usr/share/aclocal/’
1 
1    However, suppose further that many packages have been manually
1 installed on the system, with $prefix=/usr/local, as is typical.  In
1 that case, many of these “extra” ‘.m4’ files are in
1 ‘/usr/local/share/aclocal’.  The only way to force ‘/usr/bin/aclocal’ to
1 find these “extra” ‘.m4’ files is to always call ‘aclocal -I
1 /usr/local/share/aclocal’.  This is inconvenient.  With ‘dirlist’, one
1 may create a file ‘/usr/share/aclocal/dirlist’ containing only the
1 single line
1 
1      /usr/local/share/aclocal
1 
1    Now, the “default” search path on the affected system is
1 
1   1. ‘/usr/share/aclocal-1.11/’
1   2. ‘/usr/share/aclocal/’
1   3. ‘/usr/local/share/aclocal/’
1 
1    without the need for ‘-I’ options; ‘-I’ options can be reserved for
1 project-specific needs (‘my-source-dir/m4/’), rather than using it to
1 work around local system-dependent tool installation directories.
1 
1    Similarly, ‘dirlist’ can be handy if you have installed a local copy
1 of Automake in your account and want ‘aclocal’ to look for macros
1 installed at other places on the system.
1 
1 Modifying the Macro Search Path: ‘ACLOCAL_PATH’
1 ...............................................
1 
1 The fourth and last mechanism to customize the macro search path is also
1 the simplest.  Any directory included in the colon-separated environment
1 variable ‘ACLOCAL_PATH’ is added to the search path and takes precedence
1 over system directories (including those found via ‘dirlist’), with the
11 exception of the versioned directory ACDIR-APIVERSION (⇒Macro
 Search Path).  However, directories passed via ‘-I’ will take
1 precedence over directories in ‘ACLOCAL_PATH’.
1 
1    Also note that, if the ‘--install’ option is used, any ‘.m4’ file
1 containing a required macro that is found in a directory listed in
1 ‘ACLOCAL_PATH’ will be installed locally.  In this case, serial numbers
1 in ‘.m4’ are honored too, ⇒Serials.
1 
1    Conversely to ‘dirlist’, ‘ACLOCAL_PATH’ is useful if you are using a
1 global copy of Automake and want ‘aclocal’ to look for macros somewhere
1 under your home directory.
1 
1 Planned future incompatibilities
1 ................................
1 
1 The order in which the directories in the macro search path are
1 currently looked up is confusing and/or suboptimal in various aspects,
1 and is probably going to be changed in the future Automake release.  In
1 particular, directories in ‘ACLOCAL_PATH’ and ‘ACDIR’ might end up
1 taking precedence over ‘ACDIR-APIVERSION’, and directories in
1 ‘ACDIR/dirlist’ might end up taking precedence over ‘ACDIR’.  _This is a
1 possible future incompatibility!_
1