5. Scanning `configure.in'

Automake scans the package's `configure.in' to determine certain information about the package. Some autoconf macros are required and some variables must be defined in `configure.in'. Automake will also use information from `configure.in' 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.

5.1 Configuration requirements
5.2 Other things Automake recognizes
5.3 Auto-generating aclocal.m4
5.4 Autoconf macros supplied with Automake
5.5 Writing your own aclocal macros

5.1 Configuration requirements

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

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

AC_CONFIG_FILES

AC_OUTPUT

Automake uses these to determine which files to create (see 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.

Other listed files are treated differently. Currently the only difference is that an Automake `Makefile' is removed by make distclean, while other files are removed by make clean.

5.2 Other things Automake recognizes

Automake will also recognize the use of certain macros and tailor the generated `Makefile.in' appropriately. Currently recognized macros and their effects are:

AC_CONFIG_HEADER

Automake requires the use of AM_CONFIG_HEADER (see section 5.4 Autoconf macros supplied with Automake), which is similar to AC_CONFIG_HEADER (see section `Configuration Header Files' in The Autoconf Manual), but does some useful Automake-specific work.

AC_CONFIG_AUX_DIR

Automake will look for various helper scripts, such as `mkinstalldirs', in the directory named in this macro invocation. If not seen, the scripts are looked for in their `standard' locations (either the top source directory, or in the source directory corresponding to the current `Makefile.am', whichever is appropriate). See section `Finding `configure' Input' in The Autoconf Manual. FIXME: give complete list of things looked for in this directory

AC_PATH_XTRA

Automake will insert definitions for the variables defined by AC_PATH_XTRA into each `Makefile.in' that builds a C program or library. See section `System Services' in The Autoconf Manual.

AC_CANONICAL_HOST

Automake will ensure that `config.guess' and `config.sub' exist. Also, the `Makefile' variables `host_alias' and `host_triplet' are introduced. See section `Getting the Canonical System Type' in The Autoconf Manual.

AC_CANONICAL_SYSTEM

This is similar to AC_CANONICAL_HOST, but also defines the `Makefile' variables `build_alias' and `target_alias'. See section `Getting the Canonical System Type' in The Autoconf Manual.

AC_FUNC_ALLOCA

AC_FUNC_ERROR_AT_LINE

AC_FUNC_FNMATCH

AC_FUNC_GETLOADAVG

AC_FUNC_MEMCMP

AC_FUNC_MKTIME

AC_FUNC_OBSTACK

AC_FUNC_STRTOD

AC_REPLACE_FUNCS

AC_REPLACE_GNU_GETOPT

AC_STRUCT_ST_BLOCKS

AM_WITH_REGEX

Automake will ensure that the appropriate dependencies are generated for the objects corresponding to these macros. Also, Automake will verify that the appropriate source files are part of the distribution. Note that Automake does not come with any of the C sources required to use these macros, so automake -a will not install the sources. See section 9.2 Building a library, for more information. Also, see section `Particular Function Checks' in The Autoconf Manual.

AC_LIBOBJ

LIBOBJS

AC_LIBSOURCE

AC_LIBSOURCES

Automake will detect statements which put `.o' files into LIBOBJS, or pass `.o' files to AC_LIBOBJ, and will treat these additional files as if they were discovered via AC_REPLACE_FUNCS. Similarly, Automake will also distribute file listed in AC_LIBSOURCE and AC_LIBSOURCES.

Note that assignments to LIBOBJS is a construct which is being phased out; they will be ignored in a future release of Automake. You should call the AC_LIBOBJ macro instead. See section `Generic Function Checks' in The Autoconf Manual.

AC_PROG_RANLIB

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

AC_PROG_CXX

This is required if any C++ source is included. See 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 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 9.10.3 Mixing Fortran 77 With C and C++). See section Autoconf macros supplied with Automake.

AC_PROG_LIBTOOL

Automake will turn on processing for libtool (see 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.in'. The former is preferred (see 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 section `Particular Program Checks' in The Autoconf Manual.

AM_C_PROTOTYPES

This is required when using automatic de-ANSI-fication; see 9.13 Automatic de-ANSI-fication.

AM_GNU_GETTEXT

This macro is required for packages which use GNU gettext (see section 11.2 Gettext). It is distributed with gettext. If Automake sees this macro it ensures that the package meets some of gettext's requirements.

AM_MAINTAINER_MODE

This macro adds a `--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. This macro is disallowed in `Gnits' mode (see section 21. The effect of --gnu and --gnits). This macro defines the `MAINTAINER_MODE' conditional, which you can use in your own `Makefile.am'.

AC_SUBST

AC_CHECK_TOOL

AC_CHECK_PROG

AC_CHECK_PROGS

AC_PATH_PROG

AC_PATH_PROGS

For each of these macros, the first argument is automatically defined as a variable in each generated `Makefile.in'. See section `Setting Output Variables' in The Autoconf Manual, and section `Generic Program Checks' in The Autoconf Manual.

5.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros which can be used in your package; 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.in'. This provides a convenient way to get Automake-provided macros, without having to search around. Also, the aclocal mechanism allows other packages to supply their own macros.

At startup, aclocal scans all the `.m4' files it can find, looking for macro definitions. Then it scans `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 `aclocal.m4'.

The contents of `acinclude.m4', if it exists, are also automatically included in `aclocal.m4'. This is useful for incorporating local macros into `configure'.

aclocal tries to be smart about looking for new AC_DEFUNs in the files it scans. It also tries to copy the full text of the scanned file into `aclocal.m4', including both `#' and `dnl' comments. If you want to make a comment which will be completely ignored by aclocal, use `##' as the comment leader.

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.

--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.

--output=file

Cause the output to be put into file instead of `aclocal.m4'.

--print-ac-dir

Prints the name of the directory which 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.

5.4 Autoconf macros supplied with Automake

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

5.4.1 Public macros		Macros that you can use.
5.4.2 Private macros		Macros that you should not use.

5.4.1 Public macros

AM_CONFIG_HEADER

Automake will generate rules to automatically regenerate the config header.

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 option 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 18.3 Support for Multilibs.

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 automatic de-ANSI-fication.

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>'.

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 second of which has two required arguments: the package and the version number. This latter 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.in' has:

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

you can modernize it as follow:

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

Note that if you're upgrading your `configure.in' 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 of AC_INIT is the name of your package (e.g. `GNU Automake'), not the tarball name (e.g. `automake') you used to pass to AM_INIT_AUTOMAKE. Autoconf's rule to derive a tarball name from the package name should work for most but not all packages. Especially, if your tarball name is not all lower case, you will have to use the four-argument form of AC_INIT (supported in Autoconf versions greater than 2.52g).

When AM_INIT_AUTOMAKE is called with a single argument, it is interpreted as a space-separated list of Automake options which should be applied to every `Makefile.am' in the tree. The effect is as if each option were listed in AUTOMAKE_OPTIONS.

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 explictly 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.

AM_PROG_CC_STDC

If the C compiler is not in ANSI C mode by default, try to add an option to output variable CC to make it so. This macro tries various options that select ANSI C on some system or another. It considers the compiler to be in ANSI C mode if it handles function prototypes correctly.

If you use this macro, you should check after calling it whether the C compiler has been set to accept ANSI C; if not, the shell variable am_cv_prog_cc_stdc is set to `no'. If you wrote your source code in ANSI C, you can make an un-ANSIfied copy of it by using the ansi2knr option (see section 9.13 Automatic de-ANSI-fication).

AM_PROG_LEX

Like AC_PROG_LEX (see 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_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'.

AM_WITH_DMALLOC

Add support for the dmalloc package. If the user configures 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'.

5.4.2 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 which 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.

5.5 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 is mostly used for libraries which want to supply their own Autoconf macros for use by other programs. For instance the gettext library supplies a macro AM_GNU_GETTEXT which should be used by any package using gettext. When the library is installed, it installs this macro so that aclocal will find it.

A file of macros should be a series of AC_DEFUN's. The aclocal programs also understands AC_REQUIRE, so it is safe to put each macro in a separate file. See section `Prerequisite Macros' in The Autoconf Manual, and section `Macro Definitions' in The Autoconf Manual.

A macro file's name should end in `.m4'. Such files should be installed in `aclocal --print-ac-dir` (which usually happens to be `$(datadir)/aclocal').