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.

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

AC_OUTPUT

Automake uses this to determine which files to create (see section `Creating Output Files' in The Autoconf Manual). Listed files named Makefile are treated as `Makefile's. Other listed files are treated differently. Currently the only difference is that a `Makefile' is removed by make distclean, while other files are removed by make clean.

You may need the following macros in some conditions, even though they are not required.

AC_CHECK_TOOL([STRIP],[strip])

Installed binaries are usually stripped using strip when you run make install-strip. However strip might not be the right tool to use in cross-compilation environments, therefore Automake will honor the STRIP environment variable to overrule the program used to perform stripping. Automake will not set STRIP itself. If your package is not setup for cross-compilation you do not have to care (strip is ok), otherwise you can set STRIP automatically by calling AC_CHECK_TOOL([STRIP],[strip]) from your `configure.in'.

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

AC_CHECK_TOOL

Automake will ensure that `config.guess' and `config.sub' exist. Also, the `Makefile' variables `host_alias' and `host_triplet' are introduced. See both section `Getting the Canonical System Type' in The Autoconf Manual, and section `Generic Program Checks' 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_GETLOADAVG

AC_FUNC_MEMCMP

AC_STRUCT_ST_BLOCKS

AC_FUNC_FNMATCH

AC_FUNC_MKTIME

AM_FUNC_STRTOD

AC_REPLACE_FUNCS

AC_REPLACE_GNU_GETOPT

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.

LIBOBJS

Automake will detect statements which put `.o' files into LIBOBJS, and will treat these additional files as if they were discovered via AC_REPLACE_FUNCS. 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_DECL_YYTEXT

This macro is required if there is Lex source in the package. 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 is extensible for use by other packages.

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 will warn if it finds duplicates. 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 the `.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

AM_CONFIG_HEADER

Automake will generate rules to automatically regenerate the config header. If you do use this macro, you must create the file `stamp-h.in' in your source directory. It can be empty.

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_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_FUNC_STRTOD

If the strtod function is not available, or does not work correctly (like the one on SunOS 5.4), add `strtod.o' to output variable LIBOBJS.

AM_FUNC_ERROR_AT_LINE

If the function error_at_line is not found, then add `error.o' to LIBOBJS.

AM_FUNC_OBSTACK

Check for the GNU obstacks code; if not found, add `obstack.o' to `LIBOBJS'.

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

Runs many macros that most `configure.in''s need. This macro has two required arguments, the package and the version number. By default this macro AC_DEFINE's `PACKAGE' and `VERSION'. This can be avoided by passing in a non-empty third argument.

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_PATH_LISPDIR

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

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 will set ASFLAGS 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 in 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 with AC_DECL_YYTEXT (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.

Autoconf 2.50 and higher, in order to simplify the interface, includes the body of AC_DECL_YYTEXT in AC_PROG_LEX. To ensure backward compatibility, AC_DECL_YYTEXT is nevertheless defined as an invocation of AC_PROG_LEX. Since AM_PROG_LEX invokes both, it causes an annoying but benign warning (AC_PROG_LEX invoked multiple times) which you should just ignore. In the future, once Automake requires Autoconf 2.50, this issue will be fixed, but the current compatibility with Autoconf 2.13 prevents this.

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

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_TYPE_PTRDIFF_T

Define `HAVE_PTRDIFF_T' if the type `ptrdiff_t' is defined in `<stddef.h>'.

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.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 `$(datadir)/aclocal'.