Version 11 (modified by lou, 14 years ago) (diff)

Correct usage of package and project.

Autotools Basics

This page gives a general introduction to 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.


Anyone who has downloaded and installed a GNU package has seen the configure step in the installation process ("... type ./configure ..."). Autoconf is the software that generates the rather complicated shell script, configure, from a simple input file,

The goal of autoconf is to provide developers of open source software with an easy way to ensure the portability of their code. Autoconf can perform tests to find out platform and compiler dependent properties, for example, the presence of particular program, library, or header files. The configure script is a shell script for sh, the basic shell that is available on every UNIX-like system (including Linux, Cygwin, and MSys). So that it will work on every system known to the autotools developers, it assumes only the least common denominator over all sh implementations. Configure scripts can be very long --- it takes a lot of simple shell commands to accomplish complicated tests.

Autoconf uses the macro processor m4 to generate the configure script from the file. In you specify autoconf macros, some of which take arguments. In a sense these macros can be understood as subroutines, but it's a bit more subtle than that. Keep firmly in mind that macros in are expanded when the autotools are run, in the project manager's development environment, to create the configure shell script. The shell commands in the configure script are run by the user, in their environment, to adapt the source code and build process to the user's environment. An easy and frustrating conceptual mistake, when using the autotools, is to expect shell code to execute during macro expansion.

Template Files

When run by the user, the configure script will generate output files based on templates for these files. A template file typically has the extension .in. Template files contain strings (autoconf output variable names) surrounded by @. For example, Makefile is generated from The autoconf variable for the name of the C compiler is CC, and in you will find a line like

CC = @CC@

The generated Makefile will then contain this line, with @CC@ replaced by the name of the C compiler (cc, cl, gcc, etc.) appropriate for the build environment, as determined by the configure script.

You don't have to create most template files; they are generated by the various autotools. For example, automake automatically generates from and

Another template file found in many COIN packages is the file, used to generate pkg_addlibs.txt. The generated file includes the string that should be added to the link command to specify additional libraries required by the package. For example, the OSI package uses the template file; it contains the single line


When the user requests that OSI be configured to use the glpk solver, the resulting osi_addlibs.txt file contains the line

-L/cs/mitacs4/Glpk-Sun/lib -lglpk -lm

(The line shown here was generated when configure was run on a Sun Solaris system; the result may well differ in other environments.)

Configuration Header Files

One output file generated by the configure script is worth separate mention. The configuration header file (you may have noticed the config.h file in GNU packages) can be used to convey information about the configuration run to the source code of the package. Some examples:

  • System calls, such as those for obtaining the CPU time, are different on different platforms, and the header files in which they are declared are also different. The configure script can test for the presence of header files and functions.
  • The configure script can test for the presence of libraries and functions in libraries. In the CoinUtils package, if configure is run with the --enable-gnu-packages argument, it checks whether the compression library libz is available.
  • The user of a package can specify certain aspects of the configuration when configure is run, for example, the set of available linear programming solvers, and where their libraries and header files reside.

The configure script will place #define statements in the configuration header file. These can simply define a symbol or set a symbol to a specific value (such as the path to a default directory). In COIN, the convention is to use the name config_pkg.h for the configuration header file for pkg. However, to make it possible to compile the COIN code in environments which do not support autotools (e.g., MS Developer Studio), this file should not be included directly in your source code. Instead, a "wrapper" header file PkgConfig.h should be used. On UNIX-like machines this wrapper should include config_pkg.h. On other systems, it should include a system specific header file for platform dependencies, plus definitions for other symbols which may need to be changed by the user. Look to existing COIN projects for examples.


Automake is a package that generates 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.

Makefiles generated by automake can work recursively and support parallel compilation (e.g., with the -j flag of GNU make). Also, it is possible to specify conditional content in the Makefile, the activation of which depends on the output of a test performed by the configure script. This facility is limited, but it's portable (again, think 'least common denominator' over all known implementations of make).

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


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. Still, a bit of background information will help you understand its role.

Like configure, libtool is a shell script. It's generated when configure is run in the user's environment and contains the correct commands to compile code, create libraries, and link programs. Automake assumes that it will work through libtool. In the output produced during compilation and linking, you first see the libtool command line, then the command executed from the libtool script.

Libtool generates auxilliary files: .lo files correspond to object files, and .la files correspond to libraries. These files are instructions (in plain ascii) that libtool leaves for itself for later use. The compiled object files and fully or partially linked libraries are hidden in a .libs subdirectory. (The command 'make install' will move the hidden programs and libraries to the installation directory.) 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.