Go to the first, previous, next, last section, table of contents.

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.

Configuration requirements

The simplest way to meet the basic Automake requirements is to use the macro AM_INIT_AUTOMAKE (see section Autoconf macros supplied with Automake). But if you prefer, you can do the required steps by hand:

Define the variables PACKAGE and VERSION with AC_SUBST. PACKAGE should be the name of the package as it appears when bundled for distribution. For instance, Automake defines PACKAGE to be `automake'. VERSION should be the version number of the release that is being developed. We recommend that you make `configure.in' the only place in your package where the version number is defined; this makes releases simpler. Automake doesn't do any interpretation of PACKAGE or VERSION, except in `Gnits' mode (see section The effect of --gnu and --gnits).
Use the macro AC_ARG_PROGRAM if a program or script is installed. See section `Transforming Program Names When Installing' in The Autoconf.
Use AC_PROG_MAKE_SET if the package is not flat. See section `Creating Output Files' in The Autoconf Manual.
Use AM_SANITY_CHECK to make sure the build environment is sane.
Call AC_PROG_INSTALL (see section `Particular Program Checks' in The Autoconf Manual).

Use AM_MISSING_PROG to see whether the programs aclocal, autoconf, automake, autoheader, and makeinfo are in the build environment. Here is how this is done:

missing_dir=`cd $ac_aux_dir && pwd`
AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir)
AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir)
AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)

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.

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
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 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 Mixing Fortran 77 With C and C++). See section Autoconf macros supplied with Automake.
AM_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.
ALL_LINGUAS: If Automake sees that this variable is set in `configure.in', it will check the `po' directory to ensure that all the named `.po' files exist, and that all the `.po' files that exist are named.
AM_C_PROTOTYPES: This is required when using automatic de-ANSI-fication; see section Automatic de-ANSI-fication.
AM_GNU_GETTEXT: This macro is required for packages which 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_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 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.

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

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. A multilib library is one that is built multiple times, once per target flag combination. This is only useful when the library is intended to be cross-compiled. 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).
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_MKTIME: Check for a working mktime function. If not found, add `mktime.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_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_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 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.
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'.

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

Go to the first, previous, next, last section, table of contents.