2.4.2 amhello’s ‘configure.ac’ Setup Explained

Let us begin with the contents of ‘configure.ac’.

AC_INIT([amhello], [1.0], [bug-automake@gnu.org])
AM_INIT_AUTOMAKE([-Wall -Werror foreign])
AC_PROG_CC
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_FILES([
 Makefile
 src/Makefile
])
AC_OUTPUT

This file is read by both autoconf (to create ‘configure’) and automake (to create the various ‘Makefile.in’s). It contains a series of M4 macros that will be expanded as shell code to finally form the ‘configure’ script. We will not elaborate on the syntax of this file, because the Autoconf manual has a whole section about it (see Writing ‘configure.ac’ in The Autoconf Manual).

The macros prefixed with AC_ are Autoconf macros, documented in the Autoconf manual (see Autoconf Macro Index in The Autoconf Manual). The macros that start with AM_ are Automake macros, documented later in this manual (see section Macro Index).

The first two lines of ‘configure.ac’ initialize Autoconf and Automake. AC_INIT takes in as parameters the name of the package, its version number, and a contact address for bug-reports about the package (this address is output at the end of ./configure --help, for instance). When adapting this setup to your own package, by all means please do not blindly copy Automake’s address: use the mailing list of your package, or your own mail address.

The argument to AM_INIT_AUTOMAKE is a list of options for automake (see section Changing Automake’s Behavior). ‘-Wall’ and ‘-Werror’ ask automake to turn on all warnings and report them as errors. We are speaking of Automake warnings here, such as dubious instructions in ‘Makefile.am’. This has absolutely nothing to do with how the compiler will be called, even though it may support options with similar names. Using ‘-Wall -Werror’ is a safe setting when starting to work on a package: you do not want to miss any issues. Later you may decide to relax things a bit. The ‘foreign’ option tells Automake that this package will not follow the GNU Standards. GNU packages should always distribute additional files such as ‘ChangeLog’, ‘AUTHORS’, etc. We do not want automake to complain about these missing files in our small example.

The AC_PROG_CC line causes the configure script to search for a C compiler and define the variable CC with its name. The ‘src/Makefile.in’ file generated by Automake uses the variable CC to build ‘hello’, so when configure creates ‘src/Makefile’ from ‘src/Makefile.in’, it will define CC with the value it has found. If Automake is asked to create a ‘Makefile.in’ that uses CC but ‘configure.ac’ does not define it, it will suggest you add a call to AC_PROG_CC.

The AC_CONFIG_HEADERS([config.h]) invocation causes the configure script to create a ‘config.h’ file gathering ‘#define’s defined by other macros in ‘configure.ac’. In our case, the AC_INIT macro already defined a few of them. Here is an excerpt of ‘config.h’ after configure has run:

…
/* Define to the address where bug reports for this package should be sent. */
#define PACKAGE_BUGREPORT "bug-automake@gnu.org"

/* Define to the full name and version of this package. */
#define PACKAGE_STRING "amhello 1.0"
…

As you probably noticed, ‘src/main.c’ includes ‘config.h’ so it can use PACKAGE_STRING. In a real-world project, ‘config.h’ can grow really big, with one ‘#define’ per feature probed on the system.

The AC_CONFIG_FILES macro declares the list of files that configure should create from their ‘*.in’ templates. Automake also scans this list to find the ‘Makefile.am’ files it must process. (This is important to remember: when adding a new directory to your project, you should add its ‘Makefile’ to this list, otherwise Automake will never process the new ‘Makefile.am’ you wrote in that directory.)

Finally, the AC_OUTPUT line is a closing command that actually produces the part of the script in charge of creating the files registered with AC_CONFIG_HEADERS and AC_CONFIG_FILES.

When starting a new project, we suggest you start with such a simple ‘configure.ac’, and gradually add the other tests it requires. The command autoscan can also suggest a few of the tests your package may need (see Using autoscan to Create ‘configure.ac’ in The Autoconf Manual).

This document was generated on January 25, 2014 using texi2html 5.0.