Quick and Dirty Autotools Howto

Author: Miika Komu

Introduction

For small UNIX development C/C++ projects, manually created Makefiles for make are usually enough for building the source code. However, when the source code base grows larger, there is a need to automatize the building process. For example, you may have a need to automatize the following things:

You can do all of these with Makefiles, but it will be quite painful to maintain especially in larger projects. Fortunately, there is a way around this maintenance hell. Autotools can be used for automatizing building, installation and maintenance of source code. It is an assortment of tools, with two main components called autoconf and automake.

Next, we will go through a minimal example project with autoconf. You can use it as a skeleton of a new development project.

Starting a A New Project with Autotools

Make sure that you have autoconf (1.9 or later), automake and libtool installed on your machine before trying out the example project described in here. Download autotoolsdemo.tgz and extract it to somewhere (tar xvzf autotoolsdemo.tgz). Change your working directory to the extracted directory and type the following commands to build the code: 

% ./autogen.sh
% ./configure
% make

If the previous operations were successful, you can try to run the application (./hello). Now you can start modifying the example for your own purposes. Usually you just need to edit Makefile.am to e.g. add your own files.

Running the autogen.sh script and configure is usually necessary only for the first time when bootstrapping a local copy of the source code. After that you can just type "make". The generated configure script is usually automatically invoked when you do modifications to configure.ac or Makefile.am. However, it is sometimes necessary to run autogen.sh when you e.g. do extensive changes to configure.ac.

How to Migrate an Existing Project to Autotools

In this section, I will show how I wrapped the hello project around autotools from scratch. I started by creating the following files manually:

Please see the example project of how to create the Makefile.am

I constructed configure.ac and some other files as follows:

% autoscan # creates a configure.scan file
% mv configure.scan configure.ac
% edit configure.ac so that it contains at least the following lines
% (order is significant):
AC_INIT(helloworld, 0.1, foo@bar.com)
AC_CONFIG_SRCDIR([hello.c])
AC_CONFIG_HEADER([config.h])
AM_INIT_AUTOMAKE(helloworld, main)

# Checks for programs. 
AC_PROG_CC
AC_PROG_INSTALL
AC_PROG_MAKE_SET

# Checks for libraries.
AM_PROG_LIBTOOL

# Checks for header files.
# Checks for typedefs, structures, and compiler characteristics.
# Checks for library functions.
AC_CONFIG_FILES([Makefile])
AC_OUTPUT

Now I can create the configure script, execute it and build the code as instructed in the previous section: 

% ./autogen.sh # creates e.g. the configure script
% ./configure  # checks dependencies and can be given compile options (--enable-xx)
% make # build the executables and libraries

Note that there also some other automatically generated targets for make: 

% make clean   # clean all temporary files
# make install # install the binaries, libraries and documentation the system, requires root privileges
% make dist    # create a distribution tarball

Notice the use of "make dist". It creates a tarball of the source code that developer can distribute to users. It does not include the autogen.sh script at all. Instead, it includes a prebuilt configure script and the source files. Users can build the source code from the tarball as follows: 

% ./configure
% make

Related Work

Acknowledgements

Thanks for Mika Kousa for comments and Jukka Manner for testing the instructions. Thanks for Diego Biurrun for the link for the Autotools mythbuster.