wiki:pm-autotools

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

minor update

Working With the GNU Autotools

Mosf 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.

Introduction

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.

The configure.ac Files

The configure script is generated by autoconf based on the configure.ac 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 configure.ac file: The configure.ac files have a certain structure. Even if you used autoconf before, you should read about the basic structure of COIN configure.ac files, since we are using a number of custom defined autoconf macros.

In COIN, we decide between two types of configure.ac files:

  • Base directory configure.ac 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 an example of the base directory configure.ac file.

The Makefile.am Files

The Makefiles are generated by automake based on Makefile.am 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 Makefile.am, depending on what the purpose of the corresponding directory is:

  • Base directory Makefile.am: Even though this generates the only Makefile a user will usually work with, it is very simple. It mainly defines, which subdirectories make should recurse into, and it typically define additional targets, such as tests which runs make test in all subdirectories that have tests. The example Makefile.am for the base directory is discussed here.
  • Project main directory Makefile.am: In each projects 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 main things, such defining how make test is run, what extra files are to be included in a tarball created by make dist. It also knows, into which source code directories make should recurse in order to build everything that project has to provide. The example main Makefile.am for a project is discussed here.
  • Source code directory Makefile.am files: This is where the real stuff happens. Here one specifies what is to be built, what source files are required for this, where (and whether) the compiled files are to be installed. The Makefile.am files for the source code directories are discussed here.
  • Unit Test Makefile.am files: Since those also compile a program, they are similar to source directory Makefile.am files, but usually simpler. The Makefile.am files for the test code directories are discussed here.