wiki:pm-autotools-intro

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

Tweaking the wording.

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, first make sure that you are using the correct version of the autotools.

autoconf

The goal of autoconf is to provide developers of open source software with an easy way to ensure the portability of their code. Autoconf knows how to perform tests to find out platform and compiler dependent properties, for example, the presence of particular program, library, or header files.

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, configure.ac. 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 configure.ac file. In configure.ac 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 configure.ac 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 Makefile.in. The autoconf variable for the name of the C compiler is CC, and in Makefile.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 Makefile.in from Makefile.am and configure.ac.

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

@ADDLIBS@

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_prjct.h for the configuration header file for Prjct. 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 PrjctConfig.h should be used. On UNIX-like machines this wrapper should include config_prjct.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

Automake generates Makefile.in 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 Makefile.am, for each Makefile.in you want to create. In Makefile.am 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

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.