GNU Automake 版本(version 1.16.1, 26 February 2018)

Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover texts,
and with no Back-Cover Texts. A copy of the license is included in
the section entitled “GNU Free Documentation License.”

6 使用aclocal解析configure.ac

Automake通过解析文件 configure.ac 来决定软件包的信息。一些 autoconf 宏需要定义在该文件中。

6.1 Configuration requirements

Automake需要的一个必须的参数是AM_INIT_AUTOMAKE。

初次之外还有一些其他的宏，如下所示：

AC_CONFIG_FILES
AC_OUTPUT
这个两个宏一般位于文件的最末尾。

      AC_CONFIG_FILES([
        Makefile
        doc/Makefile
        src/Makefile
        src/lib/Makefile
        ...
      ])
      AC_OUTPUT

Automake使用这些信息来确定哪些文件需要被创建，上面的内容就是如果在目录中存在 Makefile.am的文件，那么将生成Makefile文件。
When using AC_CONFIG_FILES with multiple input files, as in
AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])

automake will generate the first .in input file for which a
.am file exists. If no such file exists the output file is not
considered to be generated by Automake.

通过 AC_CONFIG_FILES创建的文件在使用 make distclean的时候都会被清除。 Their inputs are
automatically distributed, unless they are the output of prior
AC_CONFIG_FILES commands. Finally, rebuild rules are generated
in the Automake Makefile existing in the subdirectory of the
output file, if there is one, or in the top-level Makefile
otherwise.

The above machinery (cleaning, distributing, and rebuilding) works
fine if the AC_CONFIG_FILES specifications contain only literals.
If part of the specification uses shell variables, automake will
not be able to fulfill this setup, and you will have to complete
the missing bits by hand. For instance, on

      file=input
      ...
      AC_CONFIG_FILES([output:$file],, [file=$file])

automake will output rules to clean output, and rebuild it.
However the rebuild rule will not depend on input, and this file
will not be distributed either. (You must add EXTRA_DIST = input
to your Makefile.am if input is a source file.)

Similarly

file=output
file2=out:in
…
AC_CONFIG_FILES([$file:input],, [file=$file])
AC_CONFIG_FILES([$file2],, [file2=$file2])

will only cause input to be distributed. No file will be cleaned
automatically (add DISTCLEANFILES = output out yourself), and no
rebuild rule will be output.

Obviously automake cannot guess what value $file is going to
hold later when configure is run, and it cannot use the shell
variable $file in a Makefile. However, if you make reference
to $file as ${file} (i.e., in a way that is compatible with
make``s syntax) and furthermore use AC_SUBSTto ensure that${file}is meaningful in aMakefile, then automakewill be able to use${file}` to generate all of these rules. For
instance, here is how the Automake package itself generates
versioned scripts for its test suite:

 AC_SUBST([APIVERSION], ...)
 ...
 AC_CONFIG_FILES(
   [tests/aclocal-${APIVERSION}:tests/aclocal.in],
   [chmod +x tests/aclocal-${APIVERSION}],
   [APIVERSION=$APIVERSION])
 AC_CONFIG_FILES(
   [tests/automake-${APIVERSION}:tests/automake.in],
   [chmod +x tests/automake-${APIVERSION}])

Here cleaning, distributing, and rebuilding are done automatically,
because ${APIVERSION} is known at make-time.

Note that you should not use shell variables to declare Makefile
files for which automake must create Makefile.in. Even
AC_SUBST does not help here, because automake needs to know the
file name when it runs in order to check whether Makefile.am
exists. (In the very hairy case that your setup requires such use
of variables, you will have to tell Automake which Makefile.ins
to generate on the command-line.)

It is possible to let automake emit conditional rules for
AC_CONFIG_FILES with the help of AM_COND_IF .

To summarize:
• Use literals for Makefiles, and for other files whenever
possible.
• Use $file (or ${file} without AC_SUBST([file])) for
files that automake should ignore.
• Use ${file} and AC_SUBST([file]) for files that automake
should not ignore.

6.2 Other things Automake recognizes

Every time Automake is run it calls Autoconf to trace configure.ac.
This way it can recognize the use of certain macros and tailor the
generated Makefile.in appropriately. Currently recognized macros and
their effects are:

AC_CANONICAL_BUILD
AC_CANONICAL_HOST
AC_CANONICAL_TARGET
Automake will ensure that config.guess and config.sub exist.
Also, the Makefile variables build_triplet, host_triplet and
target_triplet are introduced.

AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as
install-sh, in the directory named in this macro invocation.
(The full list of scripts is: ar-lib, config.guess,
config.sub, depcomp, compile, install-sh, ltmain.sh,
mdate-sh, missing, mkinstalldirs, py-compile,
test-driver, texinfo.tex, ylwrap.) Not all scripts are
always searched for; some scripts will only be sought if the
generated Makefile.in requires them.

 If `AC_CONFIG_AUX_DIR` is not given, the scripts are looked for in
 their standard locations.  For `mdate-sh`, `texinfo.tex`, and
 `ylwrap`, the standard location is the source directory
 corresponding to the current `Makefile.am`.  For the rest, the
 standard location is the first one of `.`, `..`, or `../..`
 (relative to the top source directory) that provides any one of the
 helper scripts.  

 Required files from `AC_CONFIG_AUX_DIR` are automatically
 distributed, even if there is no `Makefile.am` in this directory.

AC_CONFIG_LIBOBJ_DIR
Automake will require the sources file declared with AC_LIBSOURCE
(see below) in the directory specified by this macro.

AC_CONFIG_HEADERS
Automake will generate rules to rebuild these headers from the
corresponding templates (usually, the template for a foo.h header
being foo.h.in). Older versions of Automake required the use of
AM_CONFIG_HEADER; this is no longer the case, and that macro has
indeed been removed.

 As with `AC_CONFIG_FILES` , parts of the
 specification using shell variables will be ignored as far as
 cleaning, distributing, and rebuilding is concerned.

AC_CONFIG_LINKS
Automake will generate rules to remove configure generated links
on make distclean and to distribute named source files as part of
make dist.

 As for `AC_CONFIG_FILES` parts of the
 specification using shell variables will be ignored as far as
 cleaning and distributing is concerned.  (There are no rebuild
 rules for links.)

AC_LIBOBJ
AC_LIBSOURCE
AC_LIBSOURCES
Automake will automatically distribute any file listed in
AC_LIBSOURCE or AC_LIBSOURCES.

 Note that the `AC_LIBOBJ` macro calls `AC_LIBSOURCE`.  So if an
 Autoconf macro is documented to call `AC_LIBOBJ([file])`, then
 `file.c` will be distributed automatically by Automake.  This
 encompasses many macros like `AC_FUNC_ALLOCA`, `AC_FUNC_MEMCMP`,
 `AC_REPLACE_FUNCS`, and others.

 By the way, direct assignments to `LIBOBJS` are no longer
 supported.  You should always use `AC_LIBOBJ` for this purpose.
 Note `AC_LIBOBJ` vs. `LIBOBJS`: (autoconf)AC_LIBOBJ vs LIBOBJS.

AC_PROG_RANLIB
This is required if any libraries are built in the package. Note
Particular Program Checks: (autoconf)Particular Programs.

AC_PROG_CXX
This is required if any C++ source is included. Note Particular
Program Checks: (autoconf)Particular Programs.

AC_PROG_OBJC
This is required if any Objective C source is included. Note
Particular Program Checks: (autoconf)Particular Programs.

AC_PROG_OBJCXX
This is required if any Objective C++ source is included. Note
Particular Program Checks: (autoconf)Particular Programs.

AC_PROG_F77
This is required if any Fortran 77 source is included. Note
Particular Program Checks: (autoconf)Particular Programs.

AC_F77_LIBRARY_LDFLAGS
This is required for programs and shared libraries that are a
mixture of languages that include Fortran 77 .

AC_FC_SRCEXT
Automake will add the flags computed by AC_FC_SRCEXT to
compilation of files with the respective source extension

AC_PROG_FC
This is required if any Fortran 90/95 source is included. This
macro is distributed with Autoconf version 2.58 and later. Note
Particular Program Checks: (autoconf)Particular Programs.

AC_PROG_LIBTOOL
Automake will turn on processing for libtool

AC_PROG_YACC
If a Yacc source file is seen, then you must either use this macro
or define the variable YACC in configure.ac. The former is
preferred

AC_PROG_LEX
If a Lex source file is seen, then this macro must be used. Note
Particular Program Checks: (autoconf)Particular Programs.

AC_REQUIRE_AUX_FILE
For each AC_REQUIRE_AUX_FILE([FILE]), automake will ensure that
FILE exists in the aux directory, and will complain otherwise.
It will also automatically distribute the file. This macro should
be used by third-party Autoconf macros that require some supporting
files in the aux directory specified with AC_CONFIG_AUX_DIR
above. Note Finding configure Input: (autoconf)Input.

AC_SUBST
The first argument is automatically defined as a variable in each
generated Makefile.in, unless AM_SUBST_NOTMAKE is also used for
this variable. Note Setting Output Variables: (autoconf)Setting
Output Variables.

 For every substituted variable VAR, `automake` will add a line `VAR
 = VALUE` to each `Makefile.in` file.  Many Autoconf macros invoke
 `AC_SUBST` to set output variables this way, e.g., `AC_PATH_XTRA`
 defines `X_CFLAGS` and `X_LIBS`.  Thus, you can access these
 variables as `$(X_CFLAGS)` and `$(X_LIBS)` in any `Makefile.am` if
 `AC_PATH_XTRA` is called.

AM_CONDITIONAL
This introduces an Automake conditional

AM_COND_IF
This macro allows automake to detect subsequent access within
configure.ac to a conditional previously introduced with
AM_CONDITIONAL, thus enabling conditional AC_CONFIG_FILES

AM_GNU_GETTEXT
This macro is required for packages that use GNU gettext . It is distributed with gettext. If Automake sees this
macro it ensures that the package meets some of gettext`s
requirements.

AM_GNU_GETTEXT_INTL_SUBDIR
This macro specifies that the intl/ subdirectory is to be built,
even if the AM_GNU_GETTEXT macro was invoked with a first
argument of external.

AM_MAINTAINER_MODE([DEFAULT-MODE])
This macro adds an --enable-maintainer-mode option to
configure. If this is used, automake will cause
“maintainer-only” rules to be turned off by default in the
generated Makefile.ins, unless DEFAULT-MODE is enable. This
macro defines the MAINTAINER_MODE conditional, which you can use
in your own Makefile.am. Note maintainer-mode::.

AM_SUBST_NOTMAKE(VAR)
Prevent Automake from defining a variable VAR, even if it is
substituted by config.status. Normally, Automake defines a
make variable for each configure substitution, i.e., for each
AC_SUBST([VAR]). This macro prevents that definition from
Automake. If AC_SUBST has not been called for this variable,
then AM_SUBST_NOTMAKE has no effects. Preventing variable
definitions may be useful for substitution of multi-line values,
where VAR = @VALUE@ might yield unintended results.

m4_include
Files included by configure.ac using this macro will be detected
by Automake and automatically distributed. They will also appear
as dependencies in Makefile rules.

 `m4_include` is seldom used by `configure.ac` authors, but can
 appear in `aclocal.m4` when `aclocal` detects that some required
 macros come from files local to your package (as opposed to macros
 installed in a system-wide directory, note aclocal Invocation::).

6.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros that can be used in your
package (Macros::); some of them are actually required by Automake
in certain situations. These macros must be defined in your
aclocal.m4; otherwise they will not be seen by autoconf.

程序 aclocal 将根据 configure.ac自动生成文件 aclocal.m4 。 This provides a convenient way
to get Automake-provided macros, without having to search around. The
aclocal mechanism allows other packages to supply their own macros
(Extending aclocal::). You can also use it to maintain your own
set of custom macros (Local Macros::).

At startup, aclocal scans all the .m4 files it can find, looking
for macro definitions (Macro Search Path::). Then it scans
configure.ac. 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 aclocal.m4.

Putting the file that contains the macro definition into
aclocal.m4 is usually done by copying the entire text of this file,
including unused macro definitions as well as both # and dnl
comments. If you want to make a comment that will be completely ignored
by aclocal, use ## as the comment leader.

When a file selected by aclocal is located in a subdirectory
specified as a relative search path with aclocal``s -Iargument,aclocalassumes the file belongs to the package and usesm4_includeinstead of copying it intoaclocal.m4. This makes the package smaller, eases dependency tracking, and cause the file to be distributed automatically. (Note Local Macros::, for an example.) Any macro that is found in a system-wide directory, or via an absolute search path will be copied. So use -I pwd/reldirinstead of-I reldir` whenever
some relative directory should be considered outside the package.

The contents of acinclude.m4, if this file exists, are also
automatically included in aclocal.m4. We recommend against using
acinclude.m4 in new packages (note Local Macros::).

While computing aclocal.m4, aclocal runs autom4te (note Using
Autom4te: (autoconf)Using autom4te.) in order to trace the macros that
are really used, and omit from aclocal.m4 all macros that are
mentioned but otherwise unexpanded (this can happen when a macro is
called conditionally). autom4te is expected to be in the PATH, just
as autoconf. Its location can be overridden using the AUTOM4TE
environment variable.

6.3.1 aclocal Options

aclocal accepts the following options:

--automake-acdir=DIR
Look for the automake-provided macro files in DIR instead of in the
installation directory. This is typically used for debugging.

 The environment variable `ACLOCAL_AUTOMAKE_DIR` provides another
 way to set the directory containing automake-provided macro files.
 However `--automake-acdir` takes precedence over it.

--system-acdir=DIR
Look for the system-wide third-party macro files (and the special
dirlist file) in DIR instead of in the installation directory.
This is typically used for debugging.

--diff[=COMMAND]
Run COMMAND on M4 file that would be installed or overwritten by
--install. The default COMMAND is diff -u. This option
implies --install and --dry-run.

--dry-run
Do not actually overwrite (or create) aclocal.m4 and M4 files
installed by --install.

--help
Print a summary of the command line options and exit.

-I DIR
Add the directory DIR to the list of directories searched for .m4
files.

--install
Install system-wide third-party macros into the first directory
specified with -I DIR instead of copying them in the output file.
Note that this will happen also if DIR is an absolute path.

 When this option is used, and only when this option is used,
 `aclocal` will also honor `#serial NUMBER` lines that appear in
 macros: an M4 file is ignored if there exists another M4 file with
 the same basename and a greater serial number in the search path
 (note Serials::).

--force
Always overwrite the output file. The default is to overwrite the
output file only when really needed, i.e., when its contents
changes or if one of its dependencies is younger.

 This option forces the update of `aclocal.m4` (or the file
 specified with `--output` below) and only this file, it has
 absolutely no influence on files that may need to be installed by
 `--install`.

--output=FILE
Cause the output to be put into FILE instead of aclocal.m4.

--print-ac-dir
Prints the name of the directory that aclocal will search to find
third-party .m4 files. When this option is given, normal
processing is suppressed. This option was used in the past by
third-party packages to determine where to install .m4 macro
files, but this usage is today discouraged, since it causes
$(prefix) not to be thoroughly honored (which violates the GNU
Coding Standards), and a similar semantics can be better obtained
with the ACLOCAL_PATH environment variable; note Extending
aclocal::.

--verbose
Print the names of the files it examines.

--version
Print the version number of Automake and exit.

-W CATEGORY
--warnings=CATEGORY
Output warnings falling in CATEGORY. CATEGORY can be one of:
syntax
dubious syntactic constructs, underquoted macros, unused
macros, etc.
unsupported
unknown macros
all
all the warnings, this is the default
none
turn off all the warnings
error
treat warnings as errors

 All warnings are output by default.

 The environment variable `WARNINGS` is honored in the same way as
 it is for `automake` (note automake Invocation::).

6.3.2 Macro Search Path

默认情况下 aclocal 按照下面的目录顺序来搜索 .m4 文件：

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 (note aclocal Options::).

As an example, suppose that automake-1.11.2 was configured with
--prefix=/usr/local. Then, the search path would be:

/usr/local/share/aclocal-1.11.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 (note 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 (note 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 (note aclocal
Options::) are prepended to this search list. Thus, aclocal -I /foo -I /bar results in the following search path:

/foo
/bar
ACDIR-APIVERSION
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

/foo
/bar
ACDIR-APIVERSION
ACDIR
/test1
/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

/usr/share/aclocal-1.11/
/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

/usr/share/aclocal-1.11/
/usr/share/aclocal/
/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
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 (note 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, note 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!

6.3.3 Writing your own aclocal macros

The aclocal program doesn`t have any built-in knowledge of any macros,
so it is easy to extend it with your own macros.

This can be used by libraries that want to supply their own Autoconf
macros for use by other programs. For instance, the gettext library
supplies a macro AM_GNU_GETTEXT that should be used by any package
using gettext. When the library is installed, it installs this macro
so that aclocal will find it.

A macro files name should end in .m4. Such files should be installed in $(datadir)/aclocal`. This is as simple as writing:

 aclocaldir = $(datadir)/aclocal
 aclocal_DATA = mymacro.m4 myothermacro.m4

Please do use $(datadir)/aclocal, and not something based on the
result of aclocal --print-ac-dir (note Hard-Coded Install Paths::,
for arguments). It might also be helpful to suggest to the user to add
the $(datadir)/aclocal directory to his ACLOCAL_PATH variable (note
ACLOCAL_PATH::) so that aclocal will find the .m4 files installed by
your package automatically.

A file of macros should be a series of properly quoted AC_DEFUN``s (note (autoconf)Macro Definitions::). The aclocalprograms also understandsAC_REQUIRE(note (autoconf)Prerequisite Macros::), so it is safe to put each macro in a separate file. Each file should have no side effects but macro definitions. Especially, any call toAC_PREREQ`
should be done inside the defined macro, not at the beginning of the
file.

Starting with Automake 1.8, aclocal will warn about all underquoted
calls to AC_DEFUN. We realize this will annoy a lot of people,
because aclocal was not so strict in the past and many third party
macros are underquoted; and we have to apologize for this temporary
inconvenience. The reason we have to be stricter is that a future
implementation of aclocal (note Future of aclocal::) will have to
temporarily include all of these third party .m4 files, maybe several
times, including even files that are not actually needed. Doing so
should alleviate many problems of the current implementation, however it
requires a stricter style from the macro authors. Hopefully it is easy
to revise the existing macros. For instance,

 # bad style
 AC_PREREQ(2.68)
 AC_DEFUN(AX_FOOBAR,
 [AC_REQUIRE([AX_SOMETHING])dnl
 AX_FOO
 AX_BAR
 ])

should be rewritten as

 AC_DEFUN([AX_FOOBAR],
 [AC_PREREQ([2.68])dnl
 AC_REQUIRE([AX_SOMETHING])dnl
 AX_FOO
 AX_BAR
 ])

Wrapping the AC_PREREQ call inside the macro ensures that Autoconf
2.68 will not be required if AX_FOOBAR is not actually used. Most
importantly, quoting the first argument of AC_DEFUN allows the macro
to be redefined or included twice (otherwise this first argument would
be expanded during the second definition). For consistency we like to
quote even arguments such as 2.68 that do not require it.

If you have been directed here by the aclocal diagnostic but are
not the maintainer of the implicated macro, you will want to contact the
maintainer of that macro. Please make sure you have the latest version
of the macro and that the problem hasnt already been reported before doing so: people tend to work faster when they arent flooded by mails.

Another situation where aclocal is commonly used is to manage
macros that are used locally by the package, note Local Macros::.

6.3.4 Handling Local Macros

Feature tests offered by Autoconf do not cover all needs. People often
have to supplement existing tests with their own macros, or with
third-party macros.

There are two ways to organize custom macros in a package.

The first possibility (the historical practice) is to list all your
macros in acinclude.m4. This file will be included in aclocal.m4
when you run aclocal, and its macro(s) will henceforth be visible to
autoconf. However if it contains numerous macros, it will rapidly
become difficult to maintain, and it will be almost impossible to share
macros between packages.

The second possibility, which we do recommend, is to write each macro
in its own file and gather all these files in a directory. This
directory is usually called m4/. Then its enough to update configure.acby adding a proper call toAC_CONFIG_MACRO_DIRS`:

 AC_CONFIG_MACRO_DIRS([m4])

aclocal will then take care of automatically adding m4/ to its
search path for m4 files.

When aclocal is run, it will build an aclocal.m4 that
m4_includes any file from m4/ that defines a required macro. Macros
not found locally will still be searched in system-wide directories, as
explained in note Macro Search Path::.

Custom macros should be distributed for the same reason that
configure.ac is: so that other people have all the sources of your
package if they want to work on it. Actually, this distribution happens
automatically because all m4_included files are distributed.

However there is no consensus on the distribution of third-party
macros that your package may use. Many libraries install their own
macro in the system-wide aclocal directory (note Extending
aclocal::). For instance, Guile ships with a file called guile.m4
that contains the macro GUILE_FLAGS that can be used to define setup
compiler and linker flags appropriate for using Guile. Using
GUILE_FLAGS in configure.ac will cause aclocal to copy guile.m4
into aclocal.m4, but as guile.m4 is not part of the project, it will
not be distributed. Technically, that means a user who needs to rebuild
aclocal.m4 will have to install Guile first. This is probably OK, if
Guile already is a requirement to build the package. However, if Guile
is only an optional feature, or if your package might run on
architectures where Guile cannot be installed, this requirement will
hinder development. An easy solution is to copy such third-party macros
in your local m4/ directory so they get distributed.

Since Automake 1.10, aclocal offers the option --install to copy
these system-wide third-party macros in your local macro directory,
helping to solve the above problem.

With this setup, system-wide macros will be copied to m4/ the first
time you run aclocal. Then the locally installed macros will have
precedence over the system-wide installed macros each time aclocal is
run again.

One reason why you should keep --install in the flags even after
the first run is that when you later edit configure.ac and depend on a
new macro, this macro will be installed in your m4/ automatically.
Another one is that serial numbers (note Serials::) can be used to
update the macros in your source tree automatically when new system-wide
versions are installed. A serial number should be a single line of the
form

 #serial NNN

where NNN contains only digits and dots. It should appear in the M4
file before any macro definition. It is a good practice to maintain a
serial number for each macro you distribute, even if you do not use the
--install option of aclocal: this allows other people to use it.

6.3.5 Serial Numbers

Because third-party macros defined in *.m4 files are naturally shared
between multiple projects, some people like to version them. This makes
it easier to tell which of two M4 files is newer. Since at least 1996,
the tradition is to use a #serial line for this.

A serial number should be a single line of the form

 # serial VERSION

where VERSION is a version number containing only digits and dots.
Usually people use a single integer, and they increment it each time
they change the macro (hence the name of “serial”). Such a line should
appear in the M4 file before any macro definition.

The # must be the first character on the line, and it is OK to have
extra words after the version, as in

 #serial VERSION GARBAGE

Normally these serial numbers are completely ignored by aclocal and
autoconf, like any genuine comment. However when using aclocal``s –installfeature, these serial numbers will modify the wayaclocalselects the macros to install in the package: if two files with the same basename exist in your search path, and if at least one of them uses a#serialline,aclocalwill ignore the file that has the older#serial` line (or the file that has none).

Note that a serial number applies to a whole M4 file, not to any
macro it contains. A file can contains multiple macros, but only one
serial.

Here is a use case that illustrates the use of --install and its
interaction with serial numbers. Lets assume we maintain a package called MyPackage, the configure.acof which requires a third-party macroAX_THIRD_PARTYdefined in/usr/share/aclocal/thirdparty.m4` as
follows:

 # serial 1
 AC_DEFUN([AX_THIRD_PARTY], [...])

MyPackage uses an m4/ directory to store local macros as explained
in note Local Macros::, and has

 AC_CONFIG_MACRO_DIRS([m4])

in its configure.ac.

Initially the m4/ directory is empty. The first time we run
aclocal --install, it will notice that

• configure.ac uses AX_THIRD_PARTY
• No local macros define AX_THIRD_PARTY
• /usr/share/aclocal/thirdparty.m4 defines AX_THIRD_PARTY with
serial 1.

Because /usr/share/aclocal/thirdparty.m4 is a system-wide macro and
aclocal was given the --install option, it will copy this file in
m4/thirdparty.m4, and output an aclocal.m4 that contains
m4_include([m4/thirdparty.m4]).

The next time aclocal --install is run, something different
happens. aclocal notices that

• configure.ac uses AX_THIRD_PARTY
• m4/thirdparty.m4 defines AX_THIRD_PARTY with serial 1.
• /usr/share/aclocal/thirdparty.m4 defines AX_THIRD_PARTY with
serial 1.

Because both files have the same serial number, aclocal uses the first
it found in its search path order (note Macro Search Path::).
aclocal therefore ignores /usr/share/aclocal/thirdparty.m4 and
outputs an aclocal.m4 that contains m4_include([m4/thirdparty.m4]).

Local directories specified with -I are always searched before
system-wide directories, so a local file will always be preferred to the
system-wide file in case of equal serial numbers.

Now suppose the system-wide third-party macro is changed. This can
happen if the package installing this macro is updated. Lets suppose the new macro has serial number 2. The next time aclocal –install` is
run the situation is the following:

• configure.ac uses AX_THIRD_PARTY
• m4/thirdparty.m4 defines AX_THIRD_PARTY with serial 1.
• /usr/share/aclocal/thirdparty.m4 defines AX_THIRD_PARTY with
serial 2.

When aclocal sees a greater serial number, it immediately forgets
anything it knows from files that have the same basename and a smaller
serial number. So after it has found /usr/share/aclocal/thirdparty.m4
with serial 2, aclocal will proceed as if it had never seen
m4/thirdparty.m4. This brings us back to a situation similar to that
at the beginning of our example, where no local file defined the macro.
aclocal will install the new version of the macro in
m4/thirdparty.m4, in this case overriding the old version. MyPackage
just had its macro updated as a side effect of running aclocal.

If you are leery of letting aclocal update your local macro, you
can run aclocal --diff to review the changes aclocal --install would
perform on these macros.

Finally,note that the --force option of aclocal has absolutely
no effect on the files installed by --install. For instance, if you
have modified your local macros, do not expect --install --force to
replace the local macros by their system-wide versions. If you want to
do so, simply erase the local macros you want to revert, and run
aclocal --install.

6.3.6 The Future of `aclocal`

aclocal is expected to disappear. This feature really should not be
offered by Automake. Automake should focus on generating Makefiles;
dealing with M4 macros really is Autoconfs job. The fact that some people install Automake just to use aclocal, but do not use automake`
otherwise is an indication of how that feature is misplaced.

The new implementation will probably be done slightly differently.
For instance, it could enforce the m4/-style layout discussed in note
Local Macros::.

We have no idea when and how this will happen. This has been
discussed several times in the past, but someone still has to commit to
that non-trivial task.

From the user point of view, aclocal``s removal might turn out to be painful. There is a simple precaution that you may take to make that switch more seamless: never call aclocalyourself. Keep this guy under the exclusive control ofautoreconf and Automakes rebuild
rules. Hopefully you wont need to worry about things breaking, when aclocaldisappears, because everything will have been taken care of. If otherwise you used to callaclocal` directly yourself or from some
script, you will quickly notice the change.

Many packages come with a script called bootstrap or autogen.sh,
that will just call aclocal, libtoolize, gettextize or
autopoint, autoconf, autoheader, and automake in the right
order. Actually this is precisely what autoreconf can do for you. If
your package has such a bootstrap or autogen.sh script, consider
using autoreconf. That should simplify its logic a lot (less things
to maintain, yum!), its even likely you will not need the script anymore, and more to the point you will not call aclocal` directly
anymore.

For the time being, third-party packages should continue to install
public macros into /usr/share/aclocal/. If aclocal is replaced by
another tool it might make sense to rename the directory, but supporting
/usr/share/aclocal/ for backward compatibility should be really easy
provided all macros are properly written (note Extending aclocal::).

6.4 Autoconf macros supplied with Automake

Automake ships with several Autoconf macros that you can use from your
configure.ac. When you use one of them it will be included by
aclocal in aclocal.m4.

6.4.1 Public Macros

AM_INIT_AUTOMAKE([OPTIONS])
Runs many macros required for proper operation of the generated
Makefiles.

 Today, `AM_INIT_AUTOMAKE` is called with a single argument: a
 space-separated list of Automake options that should be applied to
 every `Makefile.am` in the tree.  The effect is as if each option
 were listed in `AUTOMAKE_OPTIONS` (note Options::).

 This macro can also be called in another, _deprecated_ form:
 `AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])`.  In this form,
 there are two required arguments: the package and the version
 number.  This usage is mostly obsolete because the PACKAGE and
 VERSION can be obtained from Autoconf`s `AC_INIT` macro.  However,
 differently from what happens for `AC_INIT` invocations, this
 `AM_INIT_AUTOMAKE` invocation supports shell variables` expansions
 in the `PACKAGE` and `VERSION` arguments (which otherwise defaults,
 respectively, to the `PACKAGE_TARNAME` and `PACKAGE_VERSION`
 defined via the `AC_INIT` invocation; note The `AC_INIT` macro:
 (autoconf)AC_INIT.); and this can be still be useful in some
 selected situations.  Our hope is that future Autoconf versions
 will improve their support for package versions defined dynamically
 at configure runtime; when (and if) this happens, support for the
 two-args `AM_INIT_AUTOMAKE` invocation will likely be removed from
 Automake.

 If your `configure.ac` has:

      AC_INIT([src/foo.c])
      AM_INIT_AUTOMAKE([mumble], [1.5])

 you should modernize it as follows:

      AC_INIT([mumble], [1.5])
      AC_CONFIG_SRCDIR([src/foo.c])
      AM_INIT_AUTOMAKE

 Note that if you`re upgrading your `configure.ac` from an earlier
 version of Automake, it is not always correct to simply move the
 package and version arguments from `AM_INIT_AUTOMAKE` directly to
 `AC_INIT`, as in the example above.  The first argument to
 `AC_INIT` should be the name of your package (e.g., `GNU
 Automake`), not the tarball name (e.g., `automake`) that you used
 to pass to `AM_INIT_AUTOMAKE`.  Autoconf tries to derive a tarball
 name from the package name, which should work for most but not all
 package names.  (If it doesn`t work for yours, you can use the
 four-argument form of `AC_INIT` to provide the tarball name
 explicitly).

 By default this macro `AC_DEFINE``s `PACKAGE` and `VERSION`.  This
 can be avoided by passing the `no-define` option (note List of
 Automake options::):
      AM_INIT_AUTOMAKE([no-define ...])

AM_PATH_LISPDIR
Searches for the program emacs, and, if found, sets the output
variable lispdir to the full path to Emacs` site-lisp directory.

 Note that this test assumes the `emacs` found to be a version that
 supports Emacs Lisp (such as GNU Emacs or XEmacs).  Other emacsen
 can cause this test to hang (some, like old versions of MicroEmacs,
 start up in interactive mode, requiring `C-x C-c` to exit, which is
 hardly obvious for a non-emacs user).  In most cases, however, you
 should be able to use `C-c` to kill the test.  In order to avoid
 problems, you can set `EMACS` to “no” in the environment, or use
 the `--with-lispdir` option to `configure` to explicitly set the
 correct path (if you`re sure you have an `emacs` that supports
 Emacs Lisp).

AM_PROG_AR([ACT-IF-FAIL])
You must use this macro when you use the archiver in your project,
if you want support for unusual archivers such as Microsoft lib.
The content of the optional argument is executed if the archiver
interface is not recognized; the default action is to abort
configure with an error message.

AM_PROG_AS
Use this macro when you have assembly code in your project. This
will choose the assembler for you (by default the C compiler) and
set CCAS, and will also set CCASFLAGS if required.

AM_PROG_CC_C_O
This is an obsolescent macro that checks that the C compiler
supports the -c and -o options together. Note that, since
Automake 1.14, the AC_PROG_CC is rewritten to implement such
checks itself, and thus the explicit use of AM_PROG_CC_C_O should
no longer be required.

AM_PROG_LEX
Like AC_PROG_LEX (note Particular Program Checks:
(autoconf)Particular Programs.), but uses the missing script on
systems that do not have lex. HP-UX 10 is one such system.

AM_PROG_GCJ
This macro finds the gcj program or causes an error. It sets
GCJ and GCJFLAGS. gcj is the Java front-end to the GNU
Compiler Collection.

AM_PROG_UPC([COMPILER-SEARCH-LIST])
Find a compiler for Unified Parallel C and define the UPC
variable. The default COMPILER-SEARCH-LIST is upcc upc. This
macro will abort configure if no Unified Parallel C compiler is
found.

AM_MISSING_PROG(NAME, PROGRAM)
Find a maintainer tool PROGRAM and define the NAME environment
variable with its location. If PROGRAM is not detected, then NAME
will instead invoke the missing script, in order to give useful
advice to the user about the missing maintainer tool. for more information on when the missing
script is appropriate.

AM_SILENT_RULES
Control the machinery for less verbose build output (note Automake
Silent Rules::).

AM_WITH_DMALLOC
Add support for the Dmalloc package (http://dmalloc.com/). If the
user runs configure with --with-dmalloc, then define
WITH_DMALLOC and add -ldmalloc to LIBS.

6.4.2 Obsolete Macros

Although using some of the following macros was required in past
releases, you should not use any of them in new code. All these macros
will be removed in the next major Automake version; if you are still
using them, running autoupdate should adjust your configure.ac
automatically (note Using autoupdate to Modernize configure.ac:
(autoconf)autoupdate Invocation.). Do it NOW!

AM_PROG_MKDIR_P

 From Automake 1.8 to 1.9.6 this macro used to define the output
 variable `mkdir_p` to one of `mkdir -p`, `install-sh -d`, or
 `mkinstalldirs`.

 Nowadays Autoconf provides a similar functionality with
 `AC_PROG_MKDIR_P` (note Particular Program Checks:
 (autoconf)Particular Programs.), however this defines the output
 variable `MKDIR_P` instead.  In case you are still using the
 `AM_PROG_MKDIR_P` macro in your `configure.ac`, or its provided
 variable `$(mkdir_p)` in your `Makefile.am`, you are advised to
 switch ASAP to the more modern Autoconf-provided interface instead;
 both the macro and the variable might be removed in a future major
 Automake release.

6.4.3 Private Macros
***********************

The following macros are private macros you should not call directly.
They are called by the other public macros when appropriate. Do not
rely on them, as they might be changed in a future version. Consider
them as implementation details; or better, do not consider them at all:
skip this section!

_AM_DEPENDENCIES
AM_SET_DEPDIR
AM_DEP_TRACK
AM_OUTPUT_DEPENDENCY_COMMANDS
These macros are used to implement Automake`s automatic dependency
tracking scheme. They are called automatically by Automake when
required, and there should be no need to invoke them manually.

AM_MAKE_INCLUDE
This macro is used to discover how the users makehandles include` statements. This macro is automatically invoked when
needed; there should be no need to invoke it manually.

AM_PROG_INSTALL_STRIP
This is used to find a version of install that can be used to
strip a program at installation time. This macro is automatically
included when required.

AM_SANITY_CHECK
This checks to make sure that a file created in the build directory
is newer than a file in the source directory. This can fail on
systems where the clock is set incorrectly. This macro is
automatically run from AM_INIT_AUTOMAKE.

浩瀚宇宙灿烂星空

Linux Automake 6 解析`configure.ac`

6 使用aclocal解析configure.ac

6.1 Configuration requirements

6.2 Other things Automake recognizes

6.3 Auto-generating aclocal.m4

6.3.1 aclocal Options

6.3.2 Macro Search Path

6.3.3 Writing your own aclocal macros

6.3.4 Handling Local Macros

6.3.5 Serial Numbers

6.3.6 The Future of `aclocal`

6.4 Autoconf macros supplied with Automake

6.4.1 Public Macros

6.4.2 Obsolete Macros

6.4.3 Private Macros
***********************

6 使用aclocal解析configure.ac

6.1 Configuration requirements

6.2 Other things Automake recognizes

6.3 Auto-generating aclocal.m4

6.3.1 aclocal Options

6.3.2 Macro Search Path

6.3.3 Writing your own aclocal macros

6.3.4 Handling Local Macros

6.3.5 Serial Numbers

6.3.6 The Future of aclocal

6.4 Autoconf macros supplied with Automake

6.4.1 Public Macros

6.4.2 Obsolete Macros

6.4.3 Private Macros***********************

6.3.6 The Future of `aclocal`

6.4.3 Private Macros
***********************