Changes between Version 2 and Version 3 of pm-autotools

May 30, 2006 12:52:46 AM (14 years ago)



  • pm-autotools

    v2 v3  
    77== Introduction ==
    9 In COIN, we make use the three GNU packages [ autoconf], [ automake], and [ libtool].
     9In COIN, we make use of the three GNU packages [ autoconf], [ automake], and [ libtool].
    11 === Autoconf ===
     11A 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].
    13 Everybody, who has downloaded and installed a GNU package, has seen the {{{configure}}} step in the installation process.  Autoconf is the software that generates the rather complicated shell script "{{{configure}}}" from a simply input file, which is called {{{}}}.
     13[wiki:pm-autotools-intro Here] you find a short description of those tools and how they are used in COIN in our wiki pages.
    15 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.
     15== The Files  ==
    17 '''Template Files'''
     17The {{{configure}}} script is generated by {{{autoconf}}} based on the {{{}}} 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}}}).
    19 At completion, the {{{configure}}} script will have generated some ''output files'' (such as a {{{Makefile}}}), based on a template for this file, that has the extension {{{.in}}} (e.g., {{{}}}).  The template files contain strings (autoconf variable names) surrounded by {{{@}}}.  For example, the autoconf variable for the name of the C compiler is {{{CC}}}, and in the template for a makeile you will find a line like
     19Many projects in COIN have a simple {{{configure}}} script in the base directory of a package (the directory {{{Coin-Clp}}} in the example for the [wiki:user-directories 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 [wiki:pm-base-config example of the base directory file].
    21 {{{
    22 CC = @CC@
    23 }}}
     21In the project subdirectories (such as the {{{CoinUtils}}} and {{{Clp}}} subdirectories in [wiki:user-directories directory structure example]) are the real configuration files.  This is where the tests for each package are performed.  The {{{}}} files here can be more involved.  For an example of a project {{{}}} file check [wiki:pm-project-config here].
    25 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.
     23== The Files ==
    27 You won't have to create those templated files on your own, since we are using Automake to automatically generate Makefiles from a simply input file.
    29 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 {{{}}}, and it only includes the entry {{{@ADDLIBS@}}}.
    31 '''Configuration Header Files'''
    33 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.
    35 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. 
    37 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.
    39 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.
    41 The configuration header file contains {{{#define}}}s, 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_pkg.h}}} for the configuration file for a Package Pkg.  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 {{{PkgConfig.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.
    43 === Automake ===
    45 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}}}.
    47 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}}}.
    49 As a user of Automake, you write an input file, called {{{}}}, for each {{{}}} 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.
    51 === Libtool ===
    53 Libtool helps to build libraries and shared objects 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:
    55 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.
    57 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.
     25The Makefiles are generated by {{{automake}}} based on {{{}}} input files.  Those usually contain