Version 18 (modified by andreasw, 15 years ago) (diff)

added link to autotools versions

Working With the GNU Autotools

Most of the COIN projects use the GNU autotools to manage the automatic configuration of the compilation process on a user's machine. The goal is that users don't need to edit Makefiles by hand, and to make the code and compilation as portable as possible.

Because the autotools try to serve many operating systems, compilers, and other environment characteristics, they might seem at the first sight somewhat complicated. However, we tried to hide most of the details that are required to successully use those tools by encapsulating the difficult issues and provide a COIN project manager friendly layer on top of the autotools.


In COIN, we make use of the three GNU packages autoconf, automake, and libtool.

A good description of those tools and how they play together can be found in the Autobook; but the versions of the tools discussed there are not the most recent ones. The documentation for each tool are here for autoconf, automake, and libtool.

Here you find a short description of those tools and how they are used in COIN.

As a project manager, you will need to write the input files for the Autotools. Those files are the and files. Once those are generated, you need to run the Autotool programs to generate the final scripts and template Makefiles. All this is described next.

The Files

The configure script is generated by autoconf based on the input file. This script usually contains autoconf macros and maybe some /bin/sh commands. To make the usage of autoconf easier for COIN developers, we define a number of new autoconf macros (in the file BuildTools/coin.m4).

  • Basic structure of the file: The files have a certain structure. Even if you used autoconf before, you should read about the basic structure of COIN files, since we are using a number of custom defined autoconf macros.

In COIN, we distinguish between two types of files:

  • Base directory files: Many packages in COIN have a simple configure script in the base directory of a package (the directory Coin-Clp in the example for the directory structure, which is the trunk directory in the repository). This configure script usually only verifies which components are available in the subdirectories, and generates the main Makefile. Here we discuss the package base directory file.

The Files

The Makefiles are generated by automake based on input files. Those usually contain information on what is to be compiled (e.g., program, library) and what source files are required for each, where things should be installed. etc. One can also add regular Makefile rules that will copied verbatim into the final Makefile.

In a typical COIN project we have a number of different types of, depending on what the purpose of the corresponding directory is. Before looking at the descriptions below, you should read the introduction of Automake concepts.

  • Base directory Even though this generates the only Makefile a user will usually work with, it is very simple. It mainly defines, into which subdirectories make should recurse, and it typically defines additional targets, such as tests which runs make test in all subdirectories that have tests. The for the package base directory is discussed here.
  • Project main directory In each project's main directory (the subdirectories under the base directory, such as Cpl and CoinUtils in the directory structure example), is the Makefile that takes care of project specific things, such defining how make test is run. It also knows, into which source code directories make should recurse in order to build everything that the project has to provide. The main for a project is discussed here.
  • Example files: COIN projects that generate a library, should contain some example code that demonstrates how the library can be used. Here, we also recommend to provide a ''simple'' Makefile to the user, that is adapted to the user's system and can be easily modified for the user's own application. Since the Makefiles generated by automake are very complicated, we prefer to provide the template file directly instead one that is produced by automake. If you want to provide such a Makefile for your example program, have a look at another existing COIN project and adapt it.

Running the Autotools

First, you should make sure that you are using the correct version of the Autotools.

You can run the Autotools in your project by going into the package's base directory (Coin-Clp in the directory structure example), and run the BuildTools?/run_autotools script. This script will copy the required auxilliary files into the base directory, and run the tools for every file that is found in the base directory and its subdirectories.

Once you have a working version of your package and you can run make, you should (re)run the configure script with the --enable-maintainer-mode flag. This will activate a number of Makefile rules that make the maintainance of the configuration and Makefiles easy. When you now edit one of the or files, the corresponding autotool program is run. If necessary, the configure script will be rerun, so that everything is always kept up-to-date. Also, for COIN, when the Externals file, which contains the definitions of the subversion externals, has changed, the Makefile will automatically update the subversion svn:externals property of the base directory.

A few notes of caution:

  • If you made a mistake in the or input file, the make for updating everything might fail. In some cases it is then require to rerun the autotools "by hand" after the error has been corrected, using the BuildTools/run_autotools script.
  • When you made a change in a file, a make will rerun the configure script (if you configured in the maintainer-mode), but not recursively. If the change you made now requires the recursion into a new directory, you will have to rerun the configure script by hand. To find out, with which options the configure script was run the last time, you can look at the beginning of the config.log output file. Make sure that you don't use the --no-create and --no-recursion option when you rerun the script.
  • The Makefiles will update the svn:externals when the Externals file has changed, but it will not automatically run a svn update to get any new external (to avoid unwanted conflicts). If you want to get the code for a new external, you need to run svn update by hand.

Which Files Should be in the Subversion Repository

The following files should be included in the subversion repository:

  • Every, configure, and file, but no Makefile file. Make sure, that the svn:keywords property for the and files are set to "Author Date Id Revision".
  • In the base directory of the package, you also need to include: config.guess, config.sub, depcomp, install-sh,, and missing. Those files will be copied into this directory automatically when you run BuildTools/run_autotools there.
  • You should also make sure that you have a subversion external dependency defined to BuildTools/trunk into a subdirectory BuildTools of the package's base directory, since otherwise the Autotools will not work.