+2002-07-31 Charles Wilson <cwilson@ece.gatech.edu>
+
+ * aclocal.in (parse_arguments): Add support for extending
+ default macro search path, using a `dirlist' file within
+ the aclocal directory.
+ * automake.texi (Invoking aclocal): Move option descriptions into ...
+ (aclocal options): ... this new node.
+ (Macro search path): New node.
+ * tests/dirlist.test: New file.
+ * tests/Makefile.am (TESTS): Add dirlist.test.
+ * m4/dirlist: New file.
+ * m4/Makefile.am (EXTRA_DIST): Add dirlist.
+ * tests/defs: Honor any installed dirlist when searching for
+ libtool.m4 and gettext.m4.
+
2002-07-30 Alexandre Duret-Lutz <duret_g@epita.fr>
Build info files in builddir instead of srcdir (for PR automake/168),
* lib/am/texibuild.am: Rewrite to output files in the current
directory, not $(srcdir). Also, support both generic and
non-generic output. Pass `-o $@' to makeinfo, texinfo, and
- texi2dvi -- this is a partial fix for PR automake/339.
+ texi2dvi (for PR automake/339).
* tests/texinfo3.test: Make sure the `.texi:' rule is output.
* tests/texinfo10.test: Use set -e, so the checks are not ignored.
* tests/texinfo16.test: New file.
to supply their own macros.
At startup, @code{aclocal} scans all the @file{.m4} files it can find,
-looking for macro definitions. Then it scans @file{configure.in}. Any
+looking for macro definitions (@pxref{Macro search path}). Then it
+scans @file{configure.in}. Any
mention of one of the macros found in the first step causes that macro,
and any macros it in turn requires, to be put into @file{aclocal.m4}.
comment which will be completely ignored by @code{aclocal}, use
@samp{##} as the comment leader.
+@menu
+* aclocal options:: Options supported by aclocal
+* Macro search path:: How aclocal finds .m4 files
+@end menu
+
+@node aclocal options, Macro search path, Invoking aclocal, Invoking aclocal
+@section aclocal options
+
+@cindex aclocal, Options
+@cindex Options, aclocal
+
@code{aclocal} accepts the following options:
@table @code
Print the version number of Automake and exit.
@end table
+@node Macro search path, , aclocal options, Invoking aclocal
+@section Macro search path
+
+@cindex Macro search path
+@cindex aclocal search path
+
+By default, @command{aclocal} searches for @file{.m4} files in the following
+directories, in this order:
+
+@table @code
+@item @var{acdir-APIVERSION}
+This is where the @file{.m4} macros distributed with automake itself
+are stored. @var{APIVERSION} depends on the automake release used;
+for automake 1.6.x, @var{APIVERSION} = @code{1.6}.
+
+@item @var{acdir}
+This directory is intended for third party @file{.m4} files, and is
+configured when @command{automake} itself is built. This is
+@file{@@datadir@@/aclocal/}, which typically
+expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
+value of @var{acdir}, use the @code{--print-ac-dir} option
+(@pxref{aclocal options}).
+@end table
+
+As an example, suppose that automake-1.6.2 was configured with
+@code{--prefix=/usr/local}. Then, the search path would be:
+
+@enumerate
+@item @file{/usr/local/share/aclocal-1.6/}
+@item @file{/usr/local/share/aclocal/}
+@end enumerate
+
+As explained in (@pxref{aclocal options}), there are several options that
+can be used to change or extend this search path.
+
+@subsection Modifying the macro search path: @code{--acdir}
+
+The most obvious option to modify the search path is
+@code{--acdir=@var{dir}}, which changes default directory and
+drops the @var{APIVERSION} directory. For example, if one specifies
+@code{--acdir=/opt/private/}, then the search path becomes:
+
+@enumerate
+@item @file{/opt/private/}
+@end enumerate
+
+Note that this option, @code{--acdir}, is intended for use
+by the internal automake test suite only; it is not ordinarily
+needed by end-users.
+
+@subsection Modifying the macro search path: @code{-I @var{dir}}
+
+Any extra directories specified using @code{-I} options
+(@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
+@code{aclocal -I /foo -I /bar} results in the following search path:
+
+@enumerate
+@item @file{/foo}
+@item @file{/bar}
+@item @var{acdir}-@var{APIVERSION}
+@item @var{acdir}
+@end enumerate
+
+@subsection Modifying the macro search path: @file{dirlist}
+
+There is a third mechanism for customizing the search path. If a
+@file{dirlist} file exists in @var{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 @emph{after}
+any directories specified on the command line using @code{-I}, but
+@emph{before} the @var{acdir} and @var{acdir-APIVERSION} directories.
+
+For example, suppose
+@file{@var{acdir}/dirlist} contains the following:
+
+@example
+/test1
+/test2
+@end example
+
+and that @code{aclocal} was called with the @code{-I /foo -I /bar} options.
+Then, the search path would be
+
+@enumerate
+@item @file{/foo}
+@item @file{/bar}
+@item @file{/test1}
+@item @file{/test2}
+@item @var{acdir}-@var{APIVERSION}
+@item @var{acdir}
+@end enumerate
+
+If the @code{--acdir=@var{dir}} option is used,
+then @command{aclocal} will search for the @file{dirlist} file in
+the @emph{redirected} @var{acdir} directory. In the
+@code{--acdir} example above, @command{aclocal} will search the
+@file{/opt/private/} directory for @file{dirlist}. Again, however,
+the @code{--acdir} option is intended for use by the internal
+automake test suite only; @code{--acdir} is not ordinarily
+needed by end-users.
+
+@file{dirlist} is useful in the following situation: suppose that
+@code{automake} version @code{1.6.2} is installed with
+$prefix=/usr by the system vendor. Thus, the default search
+directories are
+
+@enumerate
+@item @file{/usr/share/aclocal-1.6/}
+@item @file{/usr/share/aclocal/}
+@end enumerate
+
+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'' @file{.m4} files are in
+@file{/usr/local/share/aclocal}. The only way to force
+@file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files
+is to always call @code{aclocal -I /usr/local/share/aclocal}.
+This is inconvenient. With @file{dirlist}, one may create the file
+
+@file{/usr/share/aclocal/dirlist}
+
+which contains only the single line
+
+@file{/usr/local/share/aclocal}
+
+Now, the ``default'' search path on the affected system is
+
+@enumerate
+@item @file{/usr/local/share/aclocal/}
+@item @file{/usr/share/aclocal-1.6/}
+@item @file{/usr/share/aclocal/}
+@end enumerate
+
+without the need for @code{-I} options; @code{-I} options can be reserved
+for project-specific needs (@file{my-source-dir/m4/}), rather than
+using it to work around local system-dependent tool installation
+directories.
@node Macros, Extending aclocal, Invoking aclocal, configure
@section Autoconf macros supplied with Automake
git://sourceware.org / automake.git / commitdiff