configure.in

autoconf processes configure.in to produce a configure script. configure is a portable shell script which examines the build environment to determine which libraries are available, which features the platform has, where libraries and headers are located, and so on. Based on this information, it modifies compiler flags, generates makefiles, and/or outputs the file config.h with appropriate preprocessor symbols defined. Again, configure does not require autoconf to run; you generate it before distributing your software, so users do not have to have autoconf.

Your job is to write configure.in. The file is basically a series of m4 macros, which expand to snippets of shell script according to the parameters you pass them. You can also write shell code manually. Really understanding how to write a configure.in requires some knowledge of m4 (which is pretty simple) and some knowledge of the Bourne shell (which is a black art). Fortunately, you can cheat: start with an existing configure.in and modify it slightly to suit your application. There's also an extensive autoconf manual, which describes the many pre-written macros shipped with autoconf.

The GTK+ and Gnome developers have simplified things still further, by providing macros to locate GTK+ and Gnome on the user's system.

Here is a sample configure.in, from a Gnome version of "Hello, World":

AC_INIT(src/hello.c)

AM_CONFIG_HEADER(config.h)

AM_INIT_AUTOMAKE(GnomeHello, 0.1)

AM_MAINTAINER_MODE

AM_ACLOCAL_INCLUDE(macros)

GNOME_INIT

AC_PROG_CC
AC_ISC_POSIX
AC_HEADER_STDC
AC_ARG_PROGRAM
AM_PROG_LIBTOOL

GNOME_COMPILE_WARNINGS

ALL_LINGUAS="da de es fr gl nl no pl ru sv fi uk"
AM_GNU_GETTEXT

AC_SUBST(CFLAGS)
AC_SUBST(CPPFLAGS)
AC_SUBST(LDFLAGS)

AC_OUTPUT([
Makefile
macros/Makefile
src/Makefile
intl/Makefile
po/Makefile.in
pixmaps/Makefile
doc/Makefile
doc/C/Makefile
doc/es/Makefile
])

Before describing each macro, some general points should be made. First, those macros that begin with AC come with autoconf, and those that begin with AM usually come with automake. (This is useful when you're trying to find documentation for them.) The macros that begin with GNOME come in the Gnome macros directory. These macros are written in m4; the standard ones from autoconf/automake reside in /usr/share/aclocal, if you installed autoconf/automake under /usr. (An aside: the macros directory is not a good thing; each Gnome package should install its own m4 files to /usr/share/aclocal. Newer Gnome versions attempt to fix the problem.)

• AC_INIT is always the first macro in configure.in. It expands to a lot of boilerplate code shared by all configure scripts; this code parses the command line arguments to configure. The macro's one argument is a file that should be present in the source directory; this is used as a sanity check, to be sure configure has correctly located the source directory.

• AM_CONFIG_HEADER specifies a header file to create; this will almost always be config.h. The created header file will contain C preprocessor symbols defined by configure. At a minimum, the symbols PACKAGE and VERSION will be defined, which makes it easy to put the name and version of your program in your code without hard-coding them. (Your non-public source files should #include <config.h> to take advantage of its definitions; however, config.h should never be installed, because it would conflict with other packages.)

• AM_INIT_AUTOMAKE initializes automake; the arguments to this macro are the name and version of the package being compiled. (These arguments become the values of PACKAGE and VERSION, defined in config.h.)

• AM_MAINTAINER_MODE turns off maintainer-only makefile targets by default, and changes configure to understand a --enable-maintainer-mode option. --enable-maintainer-mode turns the maintainer-only targets back on. The maintainer-only makefile targets permit end users to clean automatically-generated files such as configure, which means they have to have autoconf and automake installed to repair the damage. AM_MAINTAINER_MODE makes it a bit harder for users to shoot themselves in the foot. Note, however, that the autogen.sh script used in Gnome automatically passes --enable-maintainer-mode to configure, since autogen.sh is intended for developers to use.

• AM_ACLOCAL_INCLUDE specifies an additional directory in which to search for m4 macros. In this case, it specifies the macros subdirectory, where you should have copied the Gnome macros.

• GNOME_INIT adds a number of Gnome-related command-line arguments to configure, and defines makefile variables containing the necessary preprocessor and linker flags for Gnome programs. These flags are obtained from a gnome-config script installed by the gnome-libs package.

• AC_PROG_CC locates the C compiler.

• AC_ISC_POSIX adds some flags needed for POSIX compatibility on certain platforms.

• AC_HEADER_STDC checks whether the present system has the standard ANSI header files, and defines STDC_HEADERS if so.

• AC_ARG_PROGRAM adds options to configure so that users can modify the name of an installed program. (Useful if your program happens to have the same name as some locally-installed program on their system.)

• AM_PROG_LIBTOOL is used by automake to set up its use of libtool. This is only required if you are planning to build a shared library or dynamically loadable modules; it is unnecessary for this early version of GnomeHello, but we're planning ahead.

• GNOME_COMPILE_WARNINGS adds a number of warning options to the gcc command line, but does nothing for most other compilers.

• ALL_LINGUAS="es" is not a macro, just a bit of shell code. It contains a space-separated list of language abbreviations, corresponding to .po files in the po subdirectory. (.po files contain translations into other languages, so ALL_LINGUAS should list all languages your program has been translated into.)

• AM_GNU_GETTEXT is used by automake, but the macro itself is distributed with the gettext package. It causes automake to perform a number of internationalization-related tasks.

• AC_SUBST "exports" a variable into the files generated by configure. More on this below.

• AC_OUTPUT lists the files to be created by the configure script. These will be created from a file with the same name, with .in appended. For example, the output file src/Makefile is generated from src/Makefile.in, and config.h comes from config.h.in.

In the AC_OUTPUT stage, configure processes files containing variables marked with two @ symbols; for example, @PACKAGE@. It recognizes such variables only if AC_SUBST was used to "export" the variable (many of the pre-written macros discussed above use AC_SUBST to define variables). Most commonly, this features is used to convert a Makefile.in to a Makefile. Makefile.in is typically generated by automake from Makefile.am. (However, you can use autoconf without automake, and write Makefile.in yourself.)