6.2 The GNU Autotools

Although Makefiles are very powerful ( especially when using pkg-config ), they run against limitations in the following situations:

The source code distribution has several subdirectories, most requiring their own Makefiles.
Several Makefiles share common components .
The installation process copies files into several user -configured places on your system.
Target platforms have slight incompatibilities requiring preprocessor directives or other circumvention methods .

Free software usually has all of the above traits, so managing compiles can get to be a problem. Perhaps you've already seen one popular solution to this problem when issuing these three commands to build a package:

 $ ./configure $ make $ make install

The tools behind the configure program are collectively known as the GNU autotools. This book provides only a survey of this powerful configuration/ compilation system. For more detailed information, see [Vaughan].

6.2.1 Overview

The general procedure for outfitting your source code with the GNU autotools is as follows :

Create a configure.ac file in your top-level source distribution directory. This file not only defines GNU autotool behavior, but later, a macro expansion creates the configure script. (At one time, configure.ac carried the name configure.in. )
Create a Makefile.am file in each subdirectory where the compiler or installer runs.
Run gettexttize for localization, intltoolize for additional translation support, and/or libtoolize to build your own libraries.
Run aclocal to gather all necessary macros from the macro library into the aclocal.m4 file.
Run autoheader to create a config.h.in file ” a template for the preprocessor macros necessary for your package.
Run automake to build a Makefile.in template from each of your Makefile.am files.
Use autoconf to run the m4 macro processor on configure.ac with the macros in aclocal.m4 to create the configure script.

You do not need to perform any of these steps with most public source code distributions because the developers do everything for you. However, if you get your hands on developer code (with CVS, for instance), things look quite different, because you may need several other current software packages and a complete set of GNU autotools just to get to the point where you can run ./configure .

The configure script checks your system for necessary prerequisites to build the package. If successful, configure creates a number of files from . in templates (for example, config.h from config.h.in ).

Note	Makefiles also come from Makefile.in templates in the GNU autotools system and are therefore disposable. Furthermore, a program called automake sometimes generates Makefile.in templates from Makefile.am files.

If everything goes well, configure leaves you with Makefiles in all of the relevant subdirectories. The top-level Makefile contains targets like all , install , clean , and distclean ; a make command to build one of these targets also runs make on the Makefile in the each subdirectory.

Even given the simplified description of the autotools so far, you can see that the process is far from trivial. The tools (and the files that they generate) work together to form one complex, powerful system, sort of like the gears in a clock. Rather than go into hundreds of pages of explanation, this book contains a recipe for everyday autotool use.

The example you're about to see is a fictitious GNOME package named example . Its distribution tree contains the subdirectories src for the source code and pixmaps for image data.

6.2.2 configure.ac

The centerpiece of the configuration process is configure.ac , located in your software distribution's top-level directory. Several tools read and process the macro invocations inside configure.ac , including autoconf (to create the configure script).

Note	The name configure.ac has not been around for very long ” you may see configure.in instead.

You may find the m4 macro syntax somewhat unusual. You should always remember that configure.ac contains no real instructions, but rather, macro invocations that m4 expands into shell script fragments .

As you look at configure.ac , remember the following rules:

Do not leave whitespace between the macro name and its opening parenthesis.
Do not leave whitespace between a macro argument and its comma separator, and do not leave whitespace between the last argument and the closing parenthesis.
m4 normally processes its input until there is nothing left to expand.
m4 does not process anything inside square brackets ( [ ] ).
Comments start with a hash mark ( # ).

 # ============== initialization ====================== AC_INIT([Example], [0.1], [example-bugs@example.com], [example]) AC_CONFIG_SRCDIR([src/main.c]) AC_CONFIG_HEADER(config.h) AM_INIT_AUTOMAKE AM_MAINTAINER_MODE # ============== basic compiler settings ============= AC_PROG_CC AC_HEADER_STDC # ============== take care of some localization ====== AH_TEMPLATE([GETTEXT_PACKAGE], [Package name for gettext]) GETTEXT_PACKAGE=example # note that this is a command AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, "$GETTEXT_PACKAGE") AC_SUBST(GETTEXT_PACKAGE) ALL_LINGUAS="de es" AM_GLIB_GNU_GETTEXT AC_PROG_INTLTOOL # ============== export compiler/linker options ====== AC_SUBST(CFLAGS) AC_SUBST(CPPFLAGS) AC_SUBST(LDFLAGS) # ============== look for GNOME ====================== GNOME_MODULES="libgnomeui-2.0 >= 2.0.0" PKG_CHECK_MODULES(GNOME, $GNOME_MODULES) AC_SUBST(GNOME_CFLAGS) AC_SUBST(GNOME_LIBS) # ============== generate files ====================== AC_CONFIG_FILES([ Makefile src/Makefile pixmaps/Makefile po/Makefile.in ]) AC_OUTPUT

The configure.ac file starts with this expansion:

 AC_INIT(  name  ,  version  ,  email  ,  short_name  )

where name is the package's full name, version is the version number, email is a contact address, and short_name is the package's main program. Put each of these in square brackets to disable further expansion. For GNOME applications, use the parameters that you gave to gnome_program_init() .

AC_CONFIG_SRCDIR( path ) configures the source directory; path defines the relative path to a file in the actual source code directory.

AC_CONFIG_HEADER( header_file ) specifies the main C preprocessor target file that configure generates. Normally, header_file is config.h .

The next part of the file is AM_INIT_AUTOMAKE to initialize automake, and then AM_MAINTAINER_MODE to enable certain developer targets in the Makefiles when you run configure with the --enable-maintainer-mode option.

Now you're ready for compiler settings. Make sure that the compiler works and has standard C headers with

 AC_PROG_CC AC_HEADER_STDC

The next section in the configure.ac file deals with gettext , to make sure that the program can match different locales. The expansion of

 AH_TEMPLATE(  var_name  ,  description  )

causes autoheader to define var_name in the preprocessor template file. If you want GETTEXT_PACKAGE in config.h.in , you should specify it with AH_TEMPLATE , because you'll get error messages from autoheader otherwise .

To set GETTEXT_PACKAGE to a program name that should be localized, assign it as you would a shell variable. Then use

 AC_DEFINE_UNQUOTED(  var_name  , "$  var_name  ")

to make sure that var_name and its value make it into config.h . In addition, use

 AC_SUBST(  var_name  )

to export var_name to Makefile.am .

ALL_LINGUAS defines additional locales (here, "de es" for German and Spanish). Finally, activate gettext and intltool with

 AM_GLIB_GNU_GETTEXT AC_PROG_INTLTOOL

You're finished with localization; it's time to export some more variables for the compiler. Use AC_SUBST on CFLAGS (compiler options), CPPFLAGS (C preprocessor options, such as include paths), and LDFLAGS (linker options).

The next part uses pkg-config to see if the GNOME version number is high enough:

 GNOME_MODULES="libgnomeui-2.0 >= 2.0.0" PKG_CHECK_MODULES(GNOME, $GNOME_MODULES)

That first parameter to PKG_CHECK_MODULES is very important; the expansion of PKG_CHECK_MODULES( name , " package ..")) sets name _CFLAGS to the output of pkg-config--cflags package ( name _LDFLAGS is similar). Therefore, the next two lines export the GNOME compiler and linker options:

 AC_SUBST(GNOME_CFLAGS) AC_SUBST(GNOME_LIBS)

Now you're ready to tell the autotools what files configure should generate with

 AC_CONFIG_FILES([  file1   file2  ... ])

To generate the files, use

 AC_OUTPUT

Every file that configure generates needs a .in template. You do not need to create all of these by yourself; in particular, you can tell automake to create Makefile.in files for you.

6.2.3 Makefile Templates

The automake utility builds Makefile.in from Makefile.am, a file that consists of these definitions:

The programs to compile.
The header and library requirements.
The files that in the current directory need to be installed upon a make install , and where to install them.
Any subdirectories that need make .

Top-Level Makefile.am

Here is the top-level Makefile.am for the example program:

 ## Process this file with automake to produce Makefile.in SUBDIRS = src pixmaps po desktopdir = $(datadir)/applications desktop_in_files = example.desktop.in desktop_DATA = $(desktop_in_files:.desktop.in=.desktop) @INTLTOOL_DESKTOP_RULE@ EXTRA_DIST = example.desktop.in \              intltool-extract.in \              intltool-merge.in \              intltool-update.in DISTCLEANFILES = intltool-extract \                  intltool-merge \                  intltool-update clean-local:         rm -f example.desktop         rm -f po/.intltool-merge-cache

At the very top is SUBDIRS , the other subdirectories that make should enter. Notice that if you add a directory to your source distribution, you need to add it in configure.ac and the top-level Makefile.am.

The menu item definitions in example.desktop (see Section 6.3) comes from example.desktop.in . You need some more definitions to tell automake how to build an appropriate Makefile rule:

Set desktopdir to the installation directory. automake knows that variables ending in dir are installation directories.
The desktop_in_files line sets the input file to example.desktop.in .
A _DATA suffix tells automake that the given file needs no further compilation or processing. However, you may be confused by this part:
```
 $(desktop_in_files:.desktop.in=.desktop) 
```
This means "expand the $desktop_in_files variable, but substitute .desktop.in with .desktop ."
@INTLTOOL_DESKTOP_RULE@ tells automake to insert an intltool Makefile rule to convert .desktop.in to .desktop . See Section 6.5 for more information on gettext and intltool.

Next up in this Makefile.am is EXTRA_DIST , a list of extra files to include in when packing the source code for distribution (see Section 6.2.7 for a list of the standard files).

The DISTCLEANFILES variable is a list of files to remove when running make distclean .

Finally, there is a normal make target, clean-local , to remove files generated from .in templates; automake and autoconf support -local as dependencies of standard targets (see Section 6.2.10 for a list), and therefore, a make clean runs the rule for clean-local .

Note	In all honesty, you should use CLEANFILES to add files to the make clean sequence, just as was the case with DISTCLEANFILES . This slightly unconventional approach is here only for didactic purposes.

Source Directory Makefile.am

This is src/Makefile.am in the example package:

 ## Process this file with automake to produce Makefile.in INCLUDES = -DGNOMELOCALEDIR=\""$(datadir)/locale/"\" \            -DG_LOG_DOMAIN=\"Example\" \            -I$(top_srcdir) \            $(GNOME_CFLAGS) LIBS = $(GNOME_LIBS) bin_PROGRAMS = example example_SOURCES = main.c

The standard variable INCLUDES contains preprocessor options such as include paths and macro definitions:

GNOMELOCALEDIR is the end target for localization files (note the backslash before the first and last quotation marks).
You saw G_LOG_DOMAIN (for message logging) in Section 1.4.6.
-I$(top_srcdir) includes the top-level distribution directory, so that your program can include config.h .
$(GNOME_CFLAGS) includes the configure options for GNOME. Recall that configure.ac exported GNOME_CFLAGS as the output of a pkg-config --cflags command.

LIBS is the standard variable for linker options. GNOME_LIBS comes from configure , much like the C flags just mentioned.

With the options out of the way, you must now specify the programs to build, where to install them, and the source code to compile. Set the special variable bin_PROGRAMS to the names of the programs to build. The bin component means that a make install should put the executables in the user-configured binary directory, and _PROGRAMS says that the linker must create the given program from object files.

The example_SOURCES setting tells automake how to form a target for a program from a collection of source code files. example is a program name; _SOURCES , another special suffix, indicates that the following source files are the basis for example . The automake utility defines rules for creating object files from these source files.

Pixmap Directory Makefile.am

The pixmaps/Makefile.am file demonstrates how easy it is to create a Makefile to copy files into a user-configured directory:

 ## Process this file with automake to produce Makefile.in pixmapsdir = $(datadir)/pixmaps pixmaps_DATA = example.png

6.2.4 Extra Tools

If you want to support locale with GNU gettext, run gettextize to set up the infrastructure in your distribution. Among other things, this program initializes the po directory for translation files.

You can add support for the intltool-utilities with intltoolize . This setup program is necessary to convert GConf . schemas files, menu items ( .desktop ), and GnomeVFS . keys files. Refer to Section 6.5 for information on how to use gettext and intltool.

To build your own dynamic libraries, run libtoolize to add libtool to your distribution. Refer to the libtool info page for information on how to tie it into your source code.

6.2.5 aclocal and m4 Libraries

Before you can process the macros in Makefile.am and configure.ac , you must run aclocal to gather the macro definitions from the system libraries and place them into aclocal.m4 . On an ideal system, you would not need to supply any arguments, but for GNOME programs, you often need to grab macros from your GNOME installation. For example, if GNOME lives in /opt/gnome , run

 aclocal -I /opt/gnome/share/aclocal

Warning

Don't forget the space between -I and the path. It's easy to confuse this with a compiler option.

6.2.6 autoheader

You're almost ready to run automake , but first, you need to run autoheader to create config.h.in . If you want to create your own macro templates for the config.h.in macro, see the GETTEXT_PACKAGE example in Section 6.2.2.

6.2.7 automake and Standard Package Files

To build a Makefile.in from each of your Makefile.am files, run automake . Normally, you should run

 automake --add-missing --gnu

to add any of these standard files:

AUTHORS: A list of the authors. Email addresses are optional (you may want to use disguises, so that spam address harvesters can't collect anything).
ChangeLog: A detailed list of all changes in the code in GNU Emacs changelog-mode format. Have a look at the ChangeLog file in any GNOME component package if you don't know what this is. CVS servers require a ChangeLog entry for each change in a source tree.
COPYING: Your package's license. By default, this is the newest version of the GNU GPL [FSF 1991].
INSTALL: Installation instructions. A generic configure -based document is the default.
NEWS: A small summary of your package's changes and new features, indexed by version.
README: A description of your package, along with any other notes.

Note

The automake program creates empty files for AUTHORS, ChangeLog, NEWS, and README if they do not exist. For the remaining files, automake normally creates symbolic links to files in your automake installation directory. However, if you are assembling a package for distribution, add -c to actually copy the missing files. If you want to make sure that the files (the license, for example) are up-to-date, use -f .

6.2.8 autoconf

Run autoconf in your package's top-level directory to create configure . A by-product is autom4te.cache , containing macro cache data. Deleting this directory has no ill effects.

6.2.9 configure

Most people run ./configure alone on the command line. However, there are several important options:

--prefix= dir sets the package installation prefix to dir . The default is /usr/ local . Many systems put GNOME in /opt/gnome , with binaries in /opt/gnome , header files in /opt/gnome/include , and so on.
--help displays an extensive help message for all of the configure options.
--version displays the version of the software package and the autoconf used to generate configure .
--enable-maintainer-mode adds Makefile targets to ensure that the tree stays current when someone updates a Makefile.am or configure.ac file.

The configure script performs a number of tests on your system, printing messages as it progresses. The config.log file contains more specific information and is the place to look if configure aborts with an error.

Finally, configure runs config.status to create all Makefiles and anything else in AC_CONFIG_FILES .

6.2.10 Standard Targets

After you configure your source tree, you have the following make targets at your disposal:

make all : Compiles all code in the tree. This is usually the default target.
make clean : Removes all executables and object files.
make distclean : Cleans the source tree to a state suitable for redistribution. In particular, this removes all files generated by configure .
make maintainer-clean : Like make distclean , but removes everything automatically generated by the GNU autotools.
make install : Installs the package.
make install-strip : Installs the package, removing the symbol table from executables and libraries as it goes. This saves some space.
make dist : Creates a .tar.gz distribution file for the source tree based on the application identifier and version number.
make distcheck : Verifies that a package compiles and makes sure that it is ready to distribute (for example, it checks whether make distclean really does what it is supposed to do).
make uninstall : Removes the package from your system. This works only in a configured source tree.

6.2.11 autogen .sh

Most packages include a autogen.sh script to run everything from gettextize to configure for you, so that you don't have to worry about getting all of the steps in the right order.

You must come up with your own autogen.sh script. In other words, you're probably going to steal one from some other place. You have two options here:

Glade comes with an autogen.sh script to copy into new projects. You may have to make some changes (for example, the script may refer to configure.in instead of configure.ac ), but it's better than nothing.
Adapt the autogen.sh script from the gnome-common package from cvs.gnome.org.