Changes between Version 9 and Version 10 of pm-autotools-intro


Ignore:
Timestamp:
Apr 16, 2007 6:47:01 PM (14 years ago)
Author:
lou
Comment:

Cleanup as part of BuildTools? wiki update.

Legend:

Unmodified
Added
Removed
Modified

  • pm-autotools-intro

    v9 v10  
    11= Autotools Basics =
    22
    3 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 [wiki:pm-get-autotools using the correct version of the Autotools].
     3This 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 [wiki:pm-get-autotools using the correct version of the autotools].
    44
    5 == Autoconf ==
     5== {{{autoconf}}} ==
    66
    7 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}}}.
     7Anyone 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}}}.
    88
    9 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.
     9The 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.
    1010
    11 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.
     11{{{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.
    1212
    1313=== Template Files ===
    1414
    15 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
    16 
     15When run by the user, the {{{configure}}} script will generate '''output files
     16based on templates for these files'''. A template file typically has the extension {{{.in}}}. Template files contain strings ('''{{{autoconf}}} output variable''' names) surrounded by {{{@}}}.
     17For example, {{{Makefile}}} is generated from {{{Makefile.in}}}.
     18The {{{autoconf}}} variable for the name of the C compiler is {{{CC}}}, and in {{{Makefile.in}}} you will find a line like
    1719{{{
    1820CC = @CC@
    1921}}}
     22The 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.
    2023
    21 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.
     24You '''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}}}.
    2225
    23 You '''won't have to create those templated files by hand''', since we are using Automake to automatically generate {{{Makefile.in}}} from a simple input file.
     26Another template file found in many COIN packages 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 required libraries.  For example, the OSI project uses the template file {{{osi_addlibs.txt.in}}}; it contains the single line
     27{{{
     28@ADDLIBS@
     29}}}
     30When the user requests that OSI be configured to use the {{{glpk}}} solver, the resulting {{{osi_addlibs.txt}}} file contains the line
     31{{{
     32-L/cs/mitacs4/Glpk-Sun/lib -lglpk -lm
     33}}}
     34(The line shown here was generated when {{{configure}}} was run on a Sun Solaris system; the result may well differ in other environments.)
    2435
    25 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@}}}.
    2636
    2737=== Configuration Header Files ===
    2838
    29 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.
     39One 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:
     40  * 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'''. 
    3041
    31 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'''. 
     42  * 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.
    3243
    33 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.
     44  * 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.
    3445
    35 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.
     46The {{{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
     47use 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 ''Prjct''{{{Config.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.
    3648
    37 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_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 included 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.
     49== {{{automake}}} ==
    3850
    39 == Automake ==
     51Automake is a package that '''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}}}.
    4052
    41 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}}}.
     53{{{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
     54facility is limited, but it's portable (again, think 'least common denominator' over all known implementations of {{{make}}}).
    4255
    43 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}}}.
     56As 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.
    4457
    45 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.
     58== {{{libtool}}} ==
    4659
    47 == Libtool ==
     60{{{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.
    4861
    49 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 is just some background information:
     62Like {{{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.
    5063
    51 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.
    52 
    53 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.
     64{{{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.