wiki:pm-autotools

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

formatting

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.

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.

As a project manager, you will need to write the input files for the Autotools. Those files are the configure.ac and Makefile.am 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 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 the package 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, 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 Makefile.am for the package 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 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 Makefile.am for a project is discussed here.
  • Example Makefile.in files: COIN projects that generate a library, should contain some example code that demonstrates how the library can be used. Here, we also recommend a provide 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 Makefile.in 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

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 configure.ac 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 configure.ac or Makefile.am 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 configure.ac or Makefile.am input file, the make for updating everything might fail. In some cases it is then require to rerun the autotools by hand, using the BuildTools/run_autotools script.
  • When you made a change in a configure.ac 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.ac, configure, Makefile.am and Makefile.in file, but no Makefile file. Make sure, that the svn:keywords property for the configure.ac and Makefile.am 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, ltmain.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 define to BuildTools/trunk into a subdirectory BuildTools of the package's base directory, since otherwise the Autotools will not work.