Autotools Tutorial

http://www.developingprogrammers.com/index.php/2006/01/05/autotools-tutorial/

Autotools are the set of GNU tools that configure their source packages for a particular computer system. If you have ever compiled a program using “configure” followed by “make” commands then chances are you have already used the output of Autotools. The purpose of these “configure” scripts is to create Makefiles and “config.h” files for your projects that point to libraries, define or undefine C macros, and make a range of other adjustments as needed to compile a program on a particular computer.

Configure scripts are used by a huge number of applications that are distributed in source form. They work nearly universally on Unix style platforms like Linux. They also work on Mac OS X and with Unixy add-ons like Cygwin they can work on Windows platforms too.

The Autotools themselves are the set of programs and scripts that create and support “configure” scripts. They include autoconf, automake, autoheader, and libtool. This is an introduction for beginners so I’ll stick with a subset of Autotools that will work for a very simple project.

Speaking of a simple project, I have provided a much loved classic example project for you, although feel free to use your own. The initial project with no Makefiles or configure scripts or anything can be foundhere in the hello-initial directory (also downloadable as a .tgz file if you’d like to test out the scripts as you read).

The hello-final directory contains all the files I ended up with after going through all the steps myself. Depending on your version of the Autotools your files might vary a little but they should be mostly the same.

Two Main Kinds of File

The first goal in setting up a project for Autotools is to make two files (shown in green on the chart):

• Makefile.am (for each directory of your project)
• configure.ac

Makefile.am is used to create the Makefile for each directory, but the contents look very different to a normal Makefile. Instead of listing dependencies one by one, you simply say what the output file is (for example, the program), what the sources are, and let it rip. This resembles the approach that Trolltech’s qmake takes. I’ll go through examples in a moment.

configure.ac is a set of GNU m4 macros that says what needs to be done to configure your project. M4 is a scripting language geared towards macro substitution. It’s a little like Perl but is even more likely to be found on a generic Unix-like setup. Luckily a template for the configure.ac file can be generated for you so you don’t need to know much about m4. Older versions of Autotools called this file “configure.in” so if you see references to that anywhere it’s the same thing as “configure.ac” but hasn’t been brought up to date.

Creating Makefile.am

In our sample project we have a main “hello” directory (copy this from “hello-initial” if you’re trying this out) which contains a “src” source directory. Makefile.am for the main directory should simply say which subdirectories to recurse into for more Makefiles:

hello/Makefile.am:

SUBDIRS=src

In the “src” directory the Makefile.am should say at least three things:

• What programs to build.
• Which directory to install the program into for “make install”.
• What source files are needed for each program.

hello/src/Makefile.am:

helloprgdir=../
helloprg_PROGRAMS=hello
hello_SOURCES=hello.c

Note that for the example I’ve told it to “install” the Hello World executable a directory up from the src directory where it’s compiled. Normally this would be “/usr/local/bin/” or similar but this keeps our example self contained.

Creating configure.ac

From the “hello” directory, simply run “autoscan” . Autoscan is a program that scans your source tree and outputs a sample “configure.ac” file. As it is important to edit this file before using it, autoscan names it “configure.scan” initially. You should rename it to “configure.ac” or just use “save as” when you edit the file.

Edit configure.scan with your favorite text editor to produce configure.ac.

Originally, hello/configure.scan says something like:

#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.
AC_PREREQ(2.59)
AC_INIT(FULL-PACKAGE-NAME, VERSION, BUG-REPORT-ADDRESS)
AC_CONFIG_SRCDIR([src/hello.h])
AC_CONFIG_HEADER([config.h])
# Checks for programs.
AC_PROG_CC
# Checks for libraries.
# Checks for header files.
# Checks for typedefs, structures, and compiler characteristics.
# Checks for library functions.
AC_OUTPUT

Change it as follows:

• Change AC_PREREQ(2.59) to AC_PREREQ(2.50) because we don’t need our users to be quite as up to date as we are so we’ll let them fall as far behind as version 2.50 but no further.
• Fill in AC_INIT(FULL-PACKAGE-NAME, VERSION, BUG-REPORT-ADDRESS) with sensible values to produce something like AC_INIT(hello, 1.0, sarah at developingprogrammers.com)
• Add AM_INIT_AUTOMAKE directive to tell Autoconf that our configure script should produce Makefiles.
• Change AC_CONFIG_HEADER([config.h]) to AM_CONFIG_HEADER([config.h]) because the AM macro does some additional setting up for Automake that the AC macro doesn’t do.
• Add AC_CONFIG_FILES([Makefile src/Makefile]) to spell out what exact files we want produced.

After these changes, the final hello/configure.ac should look something like this:

#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.
AC_PREREQ(2.50)
AC_INIT(hello, 1.0, sarah at developingprogrammers.com)
AC_CONFIG_SRCDIR([src/hello.h])
AM_INIT_AUTOMAKE
AM_CONFIG_HEADER([config.h])
AC_CONFIG_FILES([Makefile
        src/Makefile])
# Checks for programs.
AC_PROG_CC
# Checks for libraries.
# Checks for header files.
# Checks for typedefs, structures, and compiler characteristics.
# Checks for library functions.
AC_OUTPUT

Note the comments about other configurable entities like libraries etc. In a more complex project those would be filled in too.

Create Configure Script and Friends

At this point we have the Makefile.am files saying what we need our Makefiles to do, and the configure.ac file saying that we want our configure script to make a config.h file and the Makefiles.

We can now automatically produce four files from these two:

• aclocal.m4
• Makefile.in for each subdirectory
• config.h.in
• The “configure” script itself.

Creating aclocal.m4

This file contains a copy of the definition for any m4 macros you need to run your configure.ac script. By copying them into this file they will be available on any platform, whether the person running “configure” has installed the same macros you have or not. This is created automatically using the command:

aclocal

Creating Makefile.in

Each Makefile.ac file needs to be turned into a more detailed Makefile.in template. The Makefile.in files look more like a conventional Makefile; but still have some blanks to be filled in by “configure”. The Autotool called automake converts Makefiles from the high level “.ac” format to the detailed “.in” format.

Automake expects several files to be part of any project. Some of these you will need to create (even if they’re just empty) so that automake doesn’t complain, and others it can create for you. The “-ac” flags tells automake that if it can’t find a file it should add the file for you by copying from its store of generic template files. The files in question are:

• COPYING: This defaults to GNU’s GPL if you don’t specify your own.
• AUTHORS: Who wrote this program? Automake will complain if you don’t add this yourself.
• ChangeLog: A history of changes or a link to where you can find it. Automake complains if you don’t add this yourself.
• INSTALL: Installation instructions. The default file says some generic things about running “configure” then “make”, which is often good enough.
• NEWS: Project news or a link to where it can be found. Add this yourself.
• README: A file saying where to find installation instructions (point people to the INSTALL file), what your project is about and anything else you want them to know before installing it.

Once you have created the files that automake won’t create for you, run the command:

automake -ac

If you’ve missed creating any files then automake will complain about it now.

Creating config.h.in

This is a template for your “config.h” file that makes sure values get set for any C macros that you want defined. The program “autoheader” will create this for you based on “configure.ac”. Run:

autoheader

Creating the “configure” Script

Finally, to create the configure script itself, simply run:

autoconf

This creates a script called “configure”. Creating the script doesn’t need much more than the “configure.ac” file, but to actually run it you’ll need support files like the various “.in” files and aclocal.m4.

Configure Your Project

Now the project is in a state that can be configured for various computers. It has a “configure” script which you should be able to run now from the “hello” directory:

./configure

This should do a whole lot of tests and finally output a “Makefile” in each project directory and a “config.h” file. If it worked then try running:

make

This will compile your program. Did it work?

In theory there should be make targets there for “make install”, “make clean”, and even “make dist” which cleans up the directories and makes a “tar.gz” archive ready for shipping.