wiki:pm-autotools-intro

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

added link to autotools versions

Introduction

This pages gives a general introduction of the Autotools, in the specific context of using them in COIN. If you want to use them, you need to make sure that you are using the correct version of the Autotools.

Autoconf

Everybody, who has downloaded and installed a GNU package, has seen the configure step in the installation process. Autoconf is the software that generates this rather complicated shell script "configure" from a simple input file, which is called configure.ac.

The goal of Autoconf is to provide developers of open source software with an easy way to ensure portability of their code. Autoconf can perform tests to find out platform and compiler dependent properties, such as the presence of certain program, libraries, or header files. The configure script is a shell script for /bin/sh, i.e., the basic shell that is available on every UNIX-like system (including Linux, Cygwin, and MSys). The attempt is made to write this script so that it will work on almost every such system, and therefore the least common denominator of all platforms is taken.

Autoconf uses the preprocessor m4 to generate the script. In the configure.ac input file, you specify autoconf macros, some of which take arguments, and can in a sense be understood as subprograms.

Template Files

At completion, the configure script will have generated some output files (such as a Makefile), based on templates for these files, which have the extension .in (e.g., Makefile.in). The template files contain strings (autoconf output variable names) surrounded by @. For example, the autoconf variable for the name of the C compiler is CC, and in the template for a makefile you will find a line like

CC = @CC@

The generated final Makefile will then contain this line, with @CC@ replaced by the name of the C compiler program that the configure program has determined.

You won't have to create those templated files by hand, since we are using Automake to automatically generate Makefile.in from a simply input file.

Another template file in many COIN packages is used to generate the pkg_addlibs.txt file, which is installed together with the libraries of a package and includes the string that should be added to the link command to link with the library to specify additionally required libraries. The name of the template file is then pkg_addlibs.txt.in, and it only includes the entry @ADDLIBS@.

Configuration Header Files

An additional output of the configure script is a configuration header file (you might have seen the config.h file in GNU packages). This file can be used to convey information about the configuration run to the source code of the package.

For example, system calls, such as those for obtaining the CPU time, are different on different platforms. The configure script can test for the presence of header files.

Also, one can test for the presence of libraries and functions in libraries. An example of this is used in the CoinUtils package, for which, if configure is run with the --enable-gnu-packages flag, the configuration script checks if the compression library libz is available.

Similarly, the user of a package can determine certain aspects of the configuration, for example, which linear programming solvers are available, and where the libraries and header files are.

The configuration header file contains #defines, that can simply be just defined, or can be set to specific values (such as the path for a certain directory). In COIN, we follow the convention to use the name config_prjct.h for the configuration file for a COIN project Prjct. However, to make it easy to compile the COIN code also with the MS Developer Studio, this file should not be include directly in the COIN source code. Instead, the "wrapper" header file PrjctConfig.h should be used, which on UNIX-like machines includes the header generated by configure, but uses default values for other systems, as well as a system specific header files for platform dependencies.

Automake

Automake is a package that generates Makefile template files for Autoconf. The generated makefiles are very powerful; for example, they support automatic header file dependency tracking (if this information can be somehow obtained from the compiler). The makefiles work with any UNIX make, they have targets like install, uninstall, clean, distclean, and dist.

Automake generated Makefiles can work recursively, and support parallel compilation (e.g., with the -j flag of GNU make). Also, it is possible to specify conditional content of the Makefile, the activation of which depends on the output of a test done by configure.

As a user of Automake, you write an input file, called Makefile.am, for each Makefile.in you want to create. In there, you tell Automake what you want to build (a program, a library, etc.), and what source code files are required to build this file. There are ways to specify more information, e.g., if additional libraries are required for linking.

Libtool

Libtool helps to build static and shared libraries on different platforms. It works together with Autoconf and Automake, so that you usually don't need to interact with it directly. Here just some background information:

The libtool script itself is generated by configure for the host system the configuration is done on. It can then be used to compile code, create libraries, and link programs. Most of the rules of the Makefiles therefore work through libtool, and in the output you usually first see the command line that executes libtool, when then echos the command it finally executes.

Libtool generates auxilliary files, such as .lo files corresponding to object files, and .la files corresponding to libraries. Also, the compiled objects and libraries are located in the compilation directory itself, and in a .libs subdirectory. If both static and shared libraries are compiled, each source file is compiled twice, because the compilation might be different for the different library types.