6. Scanning `configure.ac'

Automake scans the package's `configure.ac' to determine certain information about the package. Some autoconf macros are required and some variables must be defined in `configure.ac'. Automake will also use information from `configure.ac' to further tailor its output.

Automake also supplies some Autoconf macros to make the maintenance easier. These macros can automatically be put into your `aclocal.m4' using the aclocal program.

6.1 Configuration requirements

The one real requirement of Automake is that your `configure.ac' call AM_INIT_AUTOMAKE. This macro does several things that are required for proper Automake operation (see section Autoconf macros supplied with Automake).

Here are the other macros that Automake requires but which are not run by AM_INIT_AUTOMAKE:

AC_CONFIG_FILES

AC_OUTPUT

These two macros are usually invoked as follows near the end of `configure.ac'.

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

Automake uses these to determine which files to create (see (autoconf)Output section `Creating Output Files' in The Autoconf Manual). A listed file is considered to be an Automake generated `Makefile' if there exists a file with the same name and the `.am' extension appended. Typically, `AC_CONFIG_FILES([foo/Makefile])' will cause Automake to generate `foo/Makefile.in' if `foo/Makefile.am' exists.

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.

Files created by AC_CONFIG_FILES, be they Automake `Makefile's or not, are all removed by `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_SUBST to ensure that `${file}' is meaningful in a `Makefile', then automake will be able to use `${file}' to generate all 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.in's 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 (see section Other things Automake recognizes).

To summarize:

• Use literals for `Makefile's, 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. See (autoconf)Canonicalizing section `Getting the Canonical System Type' in The Autoconf Manual.

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: `config.guess', `config.sub', `depcomp', `elisp-comp', `compile', `install-sh', `ltmain.sh', `mdate-sh', `missing', `mkinstalldirs', `py-compile', `texinfo.tex', and `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. See (autoconf)Input section `Finding `configure' Input' in The Autoconf Manual.

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. Older versions of Automake required the use of AM_CONFIG_HEADER (see section Autoconf macros supplied with Automake); this is no longer the case.

As for AC_CONFIG_FILES (see section Configuration requirements), 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 (see section Configuration requirements), 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. See (autoconf)AC_LIBOBJ vs LIBOBJS section `AC_LIBOBJ vs. LIBOBJS' in The Autoconf Manual.

AC_PROG_RANLIB

This is required if any libraries are built in the package. See (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_CXX

This is required if any C++ source is included. See (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_OBJC

This is required if any Objective C source is included. See (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_F77

This is required if any Fortran 77 source is included. This macro is distributed with Autoconf version 2.13 and later. See (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual.

AC_F77_LIBRARY_LDFLAGS

This is required for programs and shared libraries that are a mixture of languages that include Fortran 77 (see section Mixing Fortran 77 With C and C++). See section Autoconf macros supplied with Automake.

AC_FC_SRCEXT

Automake will add the flags computed by AC_FC_SRCEXT to compilation of files with the respective source extension (see (autoconf)Fortran Compiler section `Fortran Compiler Characteristics' in The Autoconf Manual).

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. See (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_LIBTOOL

Automake will turn on processing for libtool (see (libtool)Top section `Introduction' in The Libtool Manual).

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 (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual).

AC_PROG_LEX

If a Lex source file is seen, then this macro must be used. See (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual.

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. See (autoconf)Input section `Finding configure Input' in The Autoconf Manual.

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. See (autoconf)Setting Output Variables section `Setting Output Variables' in The Autoconf Manual.

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_C_PROTOTYPES

This is required when using the obsolete de-ANSI-fication feature; see Automatic de-ANSI-fication.

AM_CONDITIONAL

This introduces an Automake conditional (see section Conditionals).

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 (see section Usage of Conditionals).

AM_GNU_GETTEXT

This macro is required for packages that use GNU gettext (see section 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.in's, unless default-mode is `enable'. This macro defines the MAINTAINER_MODE conditional, which you can use in your own `Makefile.am'. See section missing and AM_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, see section Auto-generating aclocal.m4).

6.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros that can be used in your package (see section Autoconf macros supplied with Automake); 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.

The aclocal program will automatically generate `aclocal.m4' files based on the contents of `configure.ac'. 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 (see section Writing your own aclocal macros). You can also use it to maintain your own set of custom macros (see section Handling Local Macros).

At startup, aclocal scans all the `.m4' files it can find, looking for macro definitions (see section 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 `-I' argument, aclocal assumes the file belongs to the package and uses m4_include instead of copying it into `aclocal.m4'. This makes the package smaller, eases dependency tracking, and cause the file to be distributed automatically. (See section Handling 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`/reldir' instead of `-I reldir' whenever some relative directory need to 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 (see section Handling Local Macros).

While computing `aclocal.m4', aclocal runs autom4te (see (autoconf)Using autom4te section `Using Autom4te' in The Autoconf Manual) 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:

--acdir=dir

Look for the macro files in dir instead of 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.

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 (see section Serial Numbers).

--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 can be used by a package to determine where to install a macro file.

--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 (see section Creating a `Makefile.in').

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 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 (see section 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 (see section 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 erroneous 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/'

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 (see section 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 `--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 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.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 of Automake in your account and want aclocal to look for macros installed at other places on the system.

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 file's 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'. See section Installing to Hard-Coded Locations, for arguments.

A file of macros should be a series of properly quoted AC_DEFUN's (see (autoconf)Macro Definitions section `Macro Definitions' in The Autoconf Manual). The aclocal programs also understands AC_REQUIRE (see (autoconf)Prerequisite Macros section `Prerequisite Macros' in The Autoconf Manual), 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 to AC_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 (see section The Future of aclocal) will have to temporarily include all 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.57)
AC_DEFUN(AX_FOOBAR,
[AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
])

should be rewritten as

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

Wrapping the AC_PREREQ call inside the macro ensures that Autoconf 2.57 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.57 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 hasn't already been reported before doing so: people tend to work faster when they aren't flooded by mails.

Another situation where aclocal is commonly used is to manage macros that are used locally by the package, Handling 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/'. To build `aclocal.m4', one should therefore instruct aclocal to scan `m4/'. From the command line, this is done with `aclocal -I m4'. The top-level `Makefile.am' should also be updated to define

ACLOCAL_AMFLAGS = -I m4

ACLOCAL_AMFLAGS contains options to pass to aclocal when `aclocal.m4' is to be rebuilt by make. This line is also used by autoreconf (see (autoconf)autoreconf Invocation section `Using autoreconf to Update `configure' Scripts' in The Autoconf Manual) to run aclocal with suitable options, or by autopoint (see (gettext)autopoint Invocation section `Invoking the autopoint Program' in GNU gettext tools) and gettextize (see (gettext)gettextize Invocation section `Invoking the gettextize Program' in GNU gettext tools) to locate the place where Gettext's macros should be installed. So even if you do not really care about the rebuild rules, you should define ACLOCAL_AMFLAGS.

When `aclocal -I m4' 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 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 (see section Writing your own aclocal macros). 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 an option to copy these system-wide third-party macros in your local macro directory, solving the above problem. Simply use:

ACLOCAL_AMFLAGS = -I m4 --install

With this setup, system-wide macros will be copied to `m4/' the first time you run autoreconf. 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 (see section Serial Numbers) 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 `--install' feature, these serial numbers will modify the way aclocal selects 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 `#serial' line, aclocal will 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. Let's assume we maintain a package called MyPackage, the `configure.ac' of which requires a third-party macro AX_THIRD_PARTY defined 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 Handling Local Macros, and has

ACLOCAL_AMFLAGS = -I m4 --install

in its top-level `Makefile.am'.

Initially the `m4/' directory is empty. The first time we run autoreconf, it will fetch the options to pass to aclocal in `Makefile.am', and run `aclocal -I m4 --install'. aclocal 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 -I m4 --install' is run (either via autoreconf, by hand, or from the `Makefile' rebuild rules) 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 (see section 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. Let's suppose the new macro has serial number 2. The next time `aclocal -I m4 --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 -I m4 --diff' to review the changes `aclocal -I m4 --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 -I m4 --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 `Makefile's; dealing with M4 macros really is Autoconf's 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 Handling 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 aclocal yourself. Keep this guy under the exclusive control of autoreconf and Automake's rebuild rules. Hopefully you won't need to worry about things breaking, when aclocal disappears, because everything will have been taken care of. If otherwise you used to call aclocal directly yourself or from some script, you will quickly notice the change.

Many packages come with a script called `bootstrap.sh' 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.sh' or `autogen.sh' script, consider using autoreconf. That should simplify its logic a lot (less things to maintain, yum!), it's 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 (see section Writing your own aclocal macros).

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_ENABLE_MULTILIB

This is used when a "multilib" library is being built. The first optional argument is the name of the `Makefile' being generated; it defaults to `Makefile'. The second optional argument is used to find the top source directory; it defaults to the empty string (generally this should not be used unless you are familiar with the internals). See section Support for Multilibs.

AM_INIT_AUTOMAKE([OPTIONS])

AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])

Runs many macros required for proper operation of the generated Makefiles.

This macro has two forms, the first of which is preferred. In this form, 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 (see section Changing Automake's Behavior).

The second, deprecated, form of AM_INIT_AUTOMAKE has two required arguments: the package and the version number. This form is obsolete because the package and version can be obtained from Autoconf's AC_INIT macro (which itself has an old and a new form).

If your `configure.ac' has:

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

you can 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, as in:

AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])

or by passing a third non-empty argument to the obsolete form.

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_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 like AC_PROG_CC_C_O, but it generates its results in the manner required by Automake. You must use this instead of AC_PROG_CC_C_O when you need this functionality, that is, when using per-target flags or subdir-objects with C sources.

AM_PROG_LEX

Like AC_PROG_LEX (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual), 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_SILENT_RULES

Enable the machinery for less verbose build output (see section Changing Automake's Behavior).

AM_WITH_DMALLOC

Add support for the Dmalloc package. If the user runs configure with `--with-dmalloc', then define WITH_DMALLOC and add `-ldmalloc' to LIBS.

AM_WITH_REGEX

Adds `--with-regex' to the configure command line. If specified (the default), then the `regex' regular expression library is used, `regex.o' is put into LIBOBJS, and WITH_REGEX is defined. If `--without-regex' is given, then the rx regular expression library is used, and `rx.o' is put into LIBOBJS.

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. Running autoupdate should adjust your `configure.ac' automatically (see (autoconf)autoupdate Invocation section `Using autoupdate to Modernize `configure.ac'' in The Autoconf Manual).

AM_C_PROTOTYPES

Check to see if function prototypes are understood by the compiler. If so, define `PROTOTYPES' and set the output variables U and ANSI2KNR to the empty string. Otherwise, set U to `_' and ANSI2KNR to `./ansi2knr'. Automake uses these values to implement the obsolete de-ANSI-fication feature.

AM_CONFIG_HEADER

Automake will generate rules to automatically regenerate the config header. This obsolete macro is a synonym of AC_CONFIG_HEADERS today (see section Other things Automake recognizes).

AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL

If the use of TIOCGWINSZ requires `<sys/ioctl.h>', then define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be found in `<termios.h>'. This macro is obsolete, you should use Autoconf's AC_HEADER_TIOCGWINSZ instead.

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 (see (autoconf)Particular Programs section `Particular Program Checks' in The Autoconf Manual), however this defines the output variable MKDIR_P instead. Therefore AM_PROG_MKDIR_P has been rewritten as a thin wrapper around AC_PROG_MKDIR_P to define mkdir_p to the same value as MKDIR_P for backward compatibility.

If you are using Automake, there is normally no reason to call this macro, because AM_INIT_AUTOMAKE already does so. However, make sure that the custom rules in your `Makefile's use $(MKDIR_P) and not $(mkdir_p). Even if both variables still work, the latter should be considered obsolete.

If you are not using Automake, please call AC_PROG_MKDIR_P instead of AM_PROG_MKDIR_P.

AM_SYS_POSIX_TERMIOS

Check to see if POSIX termios headers and functions are available on the system. If so, set the shell variable am_cv_sys_posix_termios to `yes'. If not, set the variable to `no'. This macro is obsolete, you should use Autoconf's AC_SYS_POSIX_TERMIOS instead.

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 user's make handles 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.

This document was generated on July, 20 2009 using texi2html 1.76.