automake.info: Macro search path

Go forward to Macros
Go backward to aclocal options
Go up to configure
Go to the top op automake

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
     automake 1.6.x, APIVERSION = `1.6'.
`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 (*note aclocal options::).
   As an example, suppose that automake-1.6.2 was configured with
`--prefix=/usr/local'.  Then, the search path would be:
  1. `/usr/local/share/aclocal-1.6/'
  2. `/usr/local/share/aclocal/'
   As explained in (*note aclocal options::), there are several options
that can be used to change or extend this search path.

Modifying the macro search path: `--acdir'

   The most obvious option to modify the search path is `--acdir=DIR',
which changes default directory and drops the APIVERSION directory.
For example, if one specifies `--acdir=/opt/private/', then the search
path becomes:
  1. `/opt/private/'
   Note that this option, `--acdir', is intended for use by the
internal automake test suite only; it is not ordinarily needed by
end-users.

Modifying the macro search path: `-I DIR'

   Any extra directories specified using `-I' options (*note 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 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.