Version 21 (modified by andreasw, 14 years ago) (diff)

added TOC for autotools stuff

Table of Contents

  1. Working With the GNU Autotools
    1. Introduction
    2. The Files
    3. The Files
    4. Running the Autotools
    5. Which Files Should be in the Subversion Repository
    6. Working On Your Project
  2. Autotools Basics
    1. autoconf
      1. Template Files
      2. Configuration Header Files
    2. automake
    3. libtool
  3. Basic Structure of the File
    1. General Concepts
    2. Beginning of a file
    3. The Body of the File
    4. The End of the File
  4. The Package Base Directory File
  5. The Project Directory File
    1. Initialization of Tools and Compilers
    2. Check for other COIN-OR Components
    3. Checks for some specific System Libraries
      1. Check for the Math Library
      2. Checks for BLAS and LAPACK
      3. Checks for GNU libraries
    4. Check for User Libraries
    5. Generation of Links for Data Files
    6. Project Specific Tests
  6. Introduction of Automake Concepts
  7. The Package Base Directory File
  8. The Project Main Directory File
  9. The Source Directories Files
    1. Beginning of the File
    2. Building a Library
      1. Name of the Library
      2. Source Files for the Library
      3. Additional Link Command for the Library
      4. Collecting Objects from Other Libraries
    3. Building a Program
      1. Name of the Program
      2. Source Files for the Executable
      3. Specifying Linking Flags
    4. Additional Flags
      1. Include Directories
      2. Additional Preprocessor Definitions
      3. Correction for Default Include Flags
    5. Installation of Header Files
  10. The Test Directory File
    1. Beginning of the File
    2. Compilation of the Unit Test Program
    3. The Test Target
    4. House Cleaning
  11. Using the Correct Version of the Autotools
  12. Hints, tricks, bugs, and suggestions
    1. Using autoreconf

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. If you run the script without arguments, the autotools will be run in every subdirectory (including the current one), where a file is found. You can also explicitly specify the directories as arguments, in which you want to run the autotools.

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.

Working On Your Project

If you are working on your project, you should run configure with the --enable-maintainer-mode flag. This way, changes in your and files will automatically trigger execution of the autotools programs. If necessary, you can run the autotools "by hand", using the BuildTools?/run_autotools script.

If you want to compile the code with debug information, you should use the --enable-debug flag when you run the configure script. This will automatically switch on the debug compiler flag. It will also switch to the usage of static libraries. (When you compile only shared libraries, which is otherwise the default behavior, the executables generated will be in the .libs subdirectory, and not run properly, since the shared libraries might not be found.)