Changes between Version 10 and Version 11 of pm-autotools


Ignore:
Timestamp:
May 31, 2006 11:29:25 PM (14 years ago)
Author:
andreasw
Comment:

added description of how to run autotools

Legend:

Unmodified
Added
Removed
Modified
  • pm-autotools

    v10 v11  
    11= Working With the GNU Autotools =
    22
    3 Mosf of the COIN projects use the '''GNU autotools''' to manage the automatic configuration of the compilation process on a user's machine.  The goal is that users don't need to edit Makefiles by hand, and to make the code and compilation as portable as possible.
     3Most of the COIN projects use the '''GNU autotools''' to manage the automatic configuration of the compilation process on a user's machine.  The goal is that users don't need to edit Makefiles by hand, and to make the code and compilation as portable as possible.
    44
    55Because the autotools try to serve many operating systems, compilers, and other environment characteristics, they might seem at the first sight somewhat complicated.  However, we tried to hide most of the details that are required to successully use those tools by encapsulating the difficult issues and provide a COIN project manager friendly layer on top of the autotools.
     
    99In COIN, we make use of the three GNU packages [http://www.gnu.org/software/autoconf/ autoconf], [http://www.gnu.org/software/automake/ automake], and [http://www.gnu.org/software/libtool/ libtool].
    1010
    11 A good description of those tools and how they play together can be found in the [http://sources.redhat.com/autobook/ Autobook]; but the versions of the tools discussed there are not the most recent ones.  The documentation for each tool are here for [http://www.gnu.org/software/autoconf/manual/autoconf-2.57/ autoconf], [http://www.gnu.org/software/automake/manual/automake.html automake], and [http://www.gnu.org/software/libtool/manual.html libtool].
     11A good description of those tools and how they play together can be found in the [http://sources.redhat.com/autobook/ Autobook]; but the versions of the tools discussed there are not the most recent ones.  The documentation for each tool are here for [http://www.gnu.org/software/autoconf/manual/autoconf-2.59/ autoconf], [http://www.gnu.org/software/automake/manual/automake.html automake], and [http://www.gnu.org/software/libtool/manual.html libtool].
    1212
    1313[wiki:pm-autotools-intro Here you find a short description of those tools and how they are used in COIN.]
     14
     15As a project manager, you will need to write the input files for the Autotools.  Those files are the {{{configure.ac}}} and {{{Makefile.am}}} files.  Once those are generated, you need to run the Autotool programs to generate the final scripts and template Makefiles.  All this is described next.
    1416
    1517== The configure.ac Files  ==
     
    2123In COIN, we decide between two types of {{{configure.ac}}} files:
    2224
    23  * '''Base directory configure.ac files''': Many packages 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.  [wiki:pm-base-config Here we discuss an example of the base directory configure.ac file].
     25 * '''Base directory configure.ac files''': Many packages 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.  [wiki:pm-base-config Here we discuss the package base directory configure.ac file].
    2426
    25  * '''Project directory configure.ac files''': In 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 {{{configure.ac}}} files here can be more involved.  [wiki:pm-project-config Here we discuss an example of a project configure.ac file].
     27 * '''Project directory configure.ac files''': In 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 {{{configure.ac}}} files here can be more involved.  [wiki:pm-project-config Here we discuss the project main directory configure.ac file].
    2628
    2729== The Makefile.am Files ==
     
    3133In a typical COIN project we have a number of different types of {{{Makefile.am}}}, depending on what the purpose of the corresponding directory is:
    3234
    33  * '''Base directory Makefile.am''':   Even though this generates the only Makefile a user will usually work with, it is very simple.  It mainly defines, which subdirectories {{{make}}} should recurse into, and it typically define additional targets, such as {{{tests}}} which runs {{{make test}}} in all subdirectories that have tests. The example Makefile.am for the base directory is discussed [wiki:pm-base-make here].
     35 * '''Base directory Makefile.am''':   Even though this generates the only Makefile a user will usually work with, it is very simple.  It mainly defines, which subdirectories {{{make}}} should recurse into, and it typically define additional targets, such as {{{tests}}} which runs {{{make test}}} in all subdirectories that have tests.  [wiki:pm-base-make The Makefile.am for the package base directory is discussed here].
    3436
    35  * '''Project main directory Makefile.am''':  In each projects main directory (the subdirectories under the base directory, such as {{{Cpl}}} and {{{CoinUtils}}} in the [wiki:user-directories directory structure example] is the Makefile that takes care of project specific main things, such defining how {{{make test}}} is run, what extra files are to be included in a tarball created by {{{make dist}}}.  It also knows, into which source code directories {{{make}}} should recurse in order to build everything that project has to provide. The example main {{{Makefile.am}}} for a project is discussed [wiki:pm-project-make here].
     37 * '''Project main directory Makefile.am''':  In each projects main directory (the subdirectories under the base directory, such as {{{Cpl}}} and {{{CoinUtils}}} in the [wiki:user-directories directory structure example] is the Makefile that takes care of project specific main things, such defining how {{{make test}}} is run, what extra files are to be included in a tarball created by {{{make dist}}}.  It also knows, into which source code directories {{{make}}} should recurse in order to build everything that project has to provide.  [wiki:pm-project-make The main Makefile.am for a project is discussed here].
    3638
    37  * '''Source code directory Makefile.am files''': This is where the real stuff happens.  Here one specifies what is to be built, what source files are required for this, where (and whether) the compiled files are to be installed. The {{{Makefile.am}}} files for the source code directories are discussed [wiki:pm-source-make here].
     39 * '''Source code directory Makefile.am files''': This is where the real stuff happens.  Here one specifies what is to be built, what source files are required for this, where (and whether) the compiled files are to be installed.  [wiki:pm-source-make The Makefile.am files for the source code directories are discussed here].
    3840
    39  * '''Unit Test Makefile.am files''':  Since those also compile a program, they are similar to source directory {{{Makefile.am}}} files, but usually simpler. The {{{Makefile.am}}} files for the test code directories are discussed [wiki:pm-test-make here].
     41 * '''Unit Test Makefile.am files''':  Since those also compile a program, they are similar to source directory {{{Makefile.am}}} files, but usually simpler.  [wiki:pm-test-make The Makefile.am files for the test code directories are discussed here].
     42
     43 * '''Example Makefile.in files''':  COIN projects that generate a library, should contain some example code that demonstrates how the library can be used.  Here, we also recommend a provide ''simple'' Makefile to the user, that is adapted to the user's system and can be easily modified for the user's own application.  Since the Makefiles generated by {{{automake}}} are very complicated, we prefer to provide the template file {{{Makefile.in}}} directly instead one that is produced by {{{automake}}}.  If you want to provide such a Makefile for your example program, have a look at another existing COIN project and adapt it.
     44
     45== Running the Autotools ==
     46
     47You can run the Autotools in your project by going into the package's base directory ({{{Coin-Clp}}} in the directory structure example), and run the '''BuildTools/run_autotools''' script.  This script will copy the required auxilliary files into the base directory, and run the tools for every {{{configure.ac}}} file that is found in the base directory and its subdirectories.
     48
     49Once you have a working version of your package and you can run {{{make}}}, you should (re)run the {{{configure}}} script with the '''--enable-maintainer-mode''' flag.  This will activate a number of Makefile rules that make the maintainance of the configuration and Makefiles easy.  When you now edit one of the {{{configure.ac}}} or {{{Makefile.am}}} files, the corresponding autotool program is run, if requires, the {{{configure}}} script will be rerun, so that everything is always up-to-date.  Also, for COIN, when the {{{Externals}}} file, which contains the definitions of the subversion externals, has changed, the Makefile will automatically update the subversion {{{svn:externals}}} property of the base directory.
     50
     51A few notes of caution:
     52
     53 * If you made a mistake in the {{{configure.ac}}} or {{{Makefile.am}} input file, the {{{make}}} for updating everything might fail.  In some cases it is then require to rerun the autotools by hand, using the {{{BuildTools/run_autotools}}} script.
     54
     55 * When you made a change in a {{{configure.ac}}} file, the {{{configure}}} script is rerun, but not recursively.  If the change you made would now require the recursion into a new directory, you will have to rerun the {{{configure}}} script by hand.  To find out, with which options the {{{configure}}} script was run the last time, you can look at the beginning of the {{{config.log}}} output file.  Make sure that you don't use the {{{--no-create}}} and {{{--no-recursion}}} option.
     56
     57 * The Makefiles will update the {{{svn:externals}}} when the {{{Externals}}} file has changed, but it will not automatically run a {{{svn update}}} to get any new external (to avoid unwanted conflicts).  If you want to get the code for a new external, you need to run {{{svn update}}} by hand.