Changes between Version 22 and Version 23 of pm-autotools


Ignore:
Timestamp:
Feb 20, 2011 7:51:04 AM (10 years ago)
Author:
stefan
Comment:

replace COIN by COIN-OR; updates for BuildTools? 0.7

Legend:

Unmodified
Added
Removed
Modified
  • pm-autotools

    v22 v23  
    33= Working With the GNU Autotools =
    44
    5 Most of the COIN projects use GNU autoconf, automake, and libtool (collectively, the '''GNU autotools''') to automatically configure the source code and the compilation process for a user's computing environment.  The goal is to spare users the chore of editing source and configuration files by hand, and to make the code and compilation as portable as possible.
     5Most of the COIN-OR projects use GNU autoconf, automake, and libtool (collectively, the '''GNU autotools''') to automatically configure the source code and the compilation process for a user's computing environment.  The goal is to spare users the chore of editing source and configuration files by hand, and to make the code and compilation as portable as possible.
    66
    7 Because the autotools support many operating systems, compilers, and other environment characteristics, they might seem somewhat complicated at first glance.  However, we have tried to hide most of the details that are required to successfully use these tools by encapsulating the difficult issues and provide a COIN project manager friendly layer on top of the autotools.
     7Because the autotools support many operating systems, compilers, and other environment characteristics, they might seem somewhat complicated at first glance.  However, we have tried to hide most of the details that are required to successfully use these tools by encapsulating the difficult issues and provide a COIN-OR project manager friendly layer on top of the autotools.
    88
    99== Introduction ==
    1010
    11 In 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].
     11In COIN-OR, 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].
    1212
    1313A 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 can be found 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].
    1414
    15 [wiki:pm-autotools-intro Here you can find a short description of the autotools and how they are used in COIN.]
     15[wiki:pm-autotools-intro Here you can find a short description of the autotools and how they are used in COIN-OR.]
    1616
    1717As a project manager, you will need to write the input files for the autotools: the {{{configure.ac}}} and {{{Makefile.am}}} files.  Once they are written, you need to run the autotools programs to generate the {{{configure}}} script and {{{Makefile.in}}} template files.  All this is described in the following sections.
     
    2121== The {{{configure.ac}}} Files  ==
    2222
    23 The {{{configure}}} script is generated by {{{autoconf}}} based on the {{{configure.ac}}} input file. {{{Configure.ac}}} usually contains autotools macro invocations and {{{sh}}} commands.  To make the use of autotools easier for COIN developers and to promote consistency across COIN projects, the !BuildTools project defines many new macros that provide many standard features. (You can examine the definitions in the file [source:stable/0.5/coin.m4]).
     23The {{{configure}}} script is generated by {{{autoconf}}} based on the {{{configure.ac}}} input file. {{{Configure.ac}}} usually contains autotools macro invocations and {{{sh}}} commands.  To make the use of autotools easier for COIN-OR developers and to promote consistency across COIN-OR projects, the !BuildTools project defines many new macros that provide many standard features. (You can examine the definitions in the file [source:stable/0.7/coin.m4]).
    2424
    25 In COIN, we distinguish between two types of {{{configure.ac}}} files, [wiki:pm-autotools#BaseDirConfigAc base directory configure.ac files] and [wiki:pm-autotools#ProjDirConfigAc project directory configure.ac files].
     25In COIN-OR, we distinguish between two types of {{{configure.ac}}} files, [#BaseDirConfigAc base directory configure.ac files] and [#ProjDirConfigAc project directory configure.ac files].
    2626
    2727=== Basic structure of the {{{configure.ac}}} file ===
    2828
    29 COIN {{{configure.ac}}} files have a certain structure.  Even if you've used {{{autoconf}}} before, you should read about [wiki:pm-structure-config the basic structure of COIN configure.ac files], since we are using a number of custom defined {{{autoconf}}} macros.
     29COIN-OR {{{configure.ac}}} files have a certain structure.  Even if you've used {{{autoconf}}} before, you should read about [wiki:pm-structure-config the basic structure of COIN-OR configure.ac files], since we are using a number of custom defined {{{autoconf}}} macros.
    3030
    3131=== Base directory {{{configure.ac}}} file === #BaseDirConfigAc
    3232
    33 Many packages in COIN use a simple {{{configure}}} script in the base directory of the package (''e.g.'', the directory {{{Coin-Clp}}} in the [wiki:user-directories directory structure example]).  This {{{configure}}} script usually does only a few tasks: create a {{{libtool}}} for use by the included packages, determine which components are available in subdirectories, and generate the main Makefile.  [wiki:pm-base-config Details of the corresponding configure.ac file can be found here].
     33Many packages in COIN-OR use a simple {{{configure}}} script in the base directory of the package (''e.g.'', the directory {{{Coin-Clp}}} in the [wiki:user-directories directory structure example]).  This {{{configure}}} script usually does only a few tasks: create a {{{libtool}}} for use by the included packages, determine which COIN-OR projects are available in subdirectories, and generate the main Makefile.  [wiki:pm-base-config Details of the corresponding configure.ac file can be found here].
    3434
    3535=== Package directory configure.ac files === #ProjDirConfigAc
     
    3939== The Makefile.am Files ==
    4040
    41 {{{Makefiles}}} are generated by the {{{configure}}} script from {{{Makefile.in}}} template files. {{{Makefile.in}}} files are generated by {{{automake}}} from {{{Makefile.am}}} input files.  {{{Makefile.am}}} files contain information on what targets are to be built (''e.g.'', programs or libraries), what source files are required for each target, where libraries and include files should be installed, ''etc.''  One can also write regular Makefile rules that will copied verbatim into the final Makefile. Just remember that if you want to keep portability, you're writing for the 'lowest common denominator' implementation of {{{make}}}.
     41{{{Makefiles}}} are generated by the {{{configure}}} script from {{{Makefile.in}}} template files. {{{Makefile.in}}} files are generated by {{{automake}}} from {{{Makefile.am}}} input files.  {{{Makefile.am}}} files contain information on what targets are to be built (''e.g.'', programs or libraries), what source files are required for each target, where libraries and include files should be installed, ''etc.''  One can also write regular Makefile rules that will be copied verbatim into the final Makefile. Just remember that if you want to keep portability, you're writing for the 'lowest common denominator' implementation of {{{make}}}.
    4242
    43 In a typical COIN project there are a number of different types of {{{Makefile.am}}}, depending on the purpose of the corresponding directory.  Before looking at the descriptions below, please read the [wiki:pm-automake-intro introduction to automake concepts].
     43In a typical COIN-OR project there are a number of different types of {{{Makefile.am}}}, depending on the purpose of the corresponding directory.  Before looking at the descriptions below, please read the [wiki:pm-automake-intro introduction to automake concepts].
    4444
    4545 * '''Base directory Makefile.am file''':   Even though this generates the only {{{Makefile}}} a typical user will use directly, it is very simple.  It defines the subdirectories into which {{{make}}} should recurse to build the project, and it typically defines additional recursive targets (''e.g.'', {{{tests}}}, which will run '{{{make test}}}' in all subdirectories that have tests).  [wiki:pm-base-make Details of the package base directory Makefile.am can be found here].
     
    4949 * '''Source code directory Makefile.am files''': This is where the actual build happens.  Here one specifies what is to be built, what source files are required, where (and whether) the compiled files are to be installed, ''etc.''  [wiki:pm-source-make Details of the Makefile.am files for the source code directories can be found here].
    5050
    51  * '''Unit Test Makefile.am files''':  These also provide specify how to compile a program and are thus similar to a source directory {{{Makefile.am}}} file, but they are usually simpler.  [wiki:pm-test-make Details of the Makefile.am files for the test code directories can be found here].
     51 * '''Unit Test Makefile.am files''':  These also specify how to compile a program and are thus similar to a source directory {{{Makefile.am}}} file, but they are usually simpler.  [wiki:pm-test-make Details of the Makefile.am files for the test code directories can be found here].
    5252
    53  * '''Example Makefile.in files''':  COIN projects that generate a library should provide some example code (typically a simple main program) that demonstrates how the library can be used. It is assumed that most users of COIN software will lack the skills or the environment to run the autotools; it follows, therefore, that providing a {{{Makefile.am}}} file for an example is pointless. It's also true that the Makefiles generated by {{{automake}}} are complex and generally unreadable by a human. For these reasons, project developers should provide a {{{Makefile.in}}} file which the {{{configure}}} script can process to generate a {{{Makefile}}}. It is recommended that the project provide a {{{Makefile.in}}} that produces a [wiki:user-examples ''simple'' Makefile] for the user that is configured for the user's system and can be easily modified for the user's own application. If you want to provide such a Makefile for your example program, have a look at existing COIN projects for examples and adapt them to your needs.
     53 * '''Example Makefile.in files''':  COIN-OR projects that generate a library should provide some example code (typically a simple main program) that demonstrates how the library can be used. It is assumed that most users of COIN-OR software will lack the skills or the environment to run the autotools; it follows, therefore, that providing a {{{Makefile.am}}} file for an example is pointless. It's also true that the Makefiles generated by {{{automake}}} are complex and generally unreadable by a human. For these reasons, project developers should provide a {{{Makefile.in}}} file which the {{{configure}}} script can process to generate a {{{Makefile}}}. It is recommended that the project provide a {{{Makefile.in}}} that produces a [wiki:user-examples ''simple'' Makefile] for the user that is configured for the user's system and can be easily modified for the user's own application. If you want to provide such a Makefile for your example program, have a look at existing COIN-OR projects for examples and adapt them to your needs.
    5454
    5555== Running the Autotools ==
     
    5757First, you should make sure that you are using the [wiki:pm-get-autotools correct version of the autotools.]
    5858
    59 You can run the autotools on your package by going into the package's base directory ({{{Coin-Clp}}} in the [wiki:user-directories directory structure example]) and running the '''{{{BuildTools/run_autotools}}}''' script. When run with no parameters, the script will examine the current directory and subdirectories for {{{configure.ac}}} files. For each directory found to contain a {{{configure.ac}}} file, the script will copy the required auxiliary files into the  directory and run the autotools. You can also explicitly specify a set of directories as arguments. The {{{run_autotools}}} script also observes the environment variable {{{COIN_SKIP_PROJECTS}}}.
     59You can run the autotools on your package by going into the package's base directory ({{{Coin-Clp}}} in the [wiki:user-directories directory structure example]) and running the '''{{{BuildTools/run_autotools}}}''' script. When run with no parameters, the script will examine the current directory and subdirectories for {{{configure.ac}}} files. For each directory found to contain a {{{configure.ac}}} file, the script will copy the required auxiliary files into the directory, create a temporary link to the !BuildTools directory (if not existing yet), and run the autotools. You can also explicitly specify a set of directories as arguments and disable the recursion into subdirectories. The {{{run_autotools}}} script also observes the environment variable {{{COIN_SKIP_PROJECTS}}}.
    6060
    61 Once 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}}}''' parameter.  This will activate a number of makefile rules that simplify the maintenance of the configuration files. When you now edit a {{{configure.ac}}} or {{{Makefile.am}}} file, the corresponding autotool program will be run at the next execution of {{{make}}}. If necessary, the {{{configure}}} script will be rerun so that everything is kept up-to-date. Specific to COIN, when the {{{Externals}}} file, which contains the definitions of subversion externals, has changed, the subversion {{{svn:externals}}} property of the base directory will be automatically updated.
     61Once 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}}}''' parameter.  This will activate a number of makefile rules that simplify the maintenance of the configuration files. When you now edit a {{{configure.ac}}} or {{{Makefile.am}}} file, the corresponding autotool program will be run at the next execution of {{{make}}}. If necessary, the {{{configure}}} script will be rerun so that everything is kept up-to-date. Specific to COIN-OR, when the {{{Dependencies}}} file, which contains the definitions of subversion externals, has changed, the subversion {{{svn:externals}}} property of the base directory will be automatically updated.
    6262
    6363A few notes of caution when maintainer mode is enabled:
     
    6767 * When you make a change in a {{{configure.ac}}} file, {{{make}}} will rerun the {{{configure}}} script, but ''not'' recursively.  If the change you made now requires recursion into a new directory, you will have to rerun the {{{configure}}} script by hand.  To determine the options used in the most recent run of the {{{configure}}} script, look at the beginning of the {{{config.log}}} output file.  Make sure that you don't use the {{{--no-create}}} or {{{--no-recursion}}} options when you rerun the script.
    6868
    69  * The base directory Makefile will update the {{{svn:externals}}} property when the {{{Externals}}} file has been changed, but it will not automatically run a '{{{svn update}}}' command to check out new external directories (to avoid unwanted conflicts).  To check out the code for a new external dependency, run '{{{svn update}}}' by hand.
     69 * The base directory Makefile will update the {{{svn:externals}}} property when the {{{Dependencies}}} file has been changed, but it will not automatically run a '{{{svn update}}}' command to check out new external directories (to avoid unwanted conflicts).  To check out the code for a new external dependency, run '{{{svn update}}}' by hand.
    7070
    7171== Which Files Should be in the Subversion Repository? ==
     
    7979 * Every '''{{{configure}}}''' and '''{{{Makefile.in}}}''' file. These are generated by the autotools and cannot be recreated by the average user. '''Do not''' include {{{Makefile}}}s; these are generated when the user runs the {{{configure}}} script.
    8080
    81  * In the base directory of the package, include '''{{{config.guess}}}''', '''{{{config.sub}}}''', '''{{{depcomp}}}''', '''{{{install-sh}}}''', '''{{{ltmain.sh}}}''', and '''{{{missing}}}'''.  These files will be copied into the directory automatically when you run {{{BuildTools/run_autotools}}} from the base directory.
    82 
    83  * You should also make sure that you have a subversion external dependency defined in your package's {{{Externals}}} file to check out {{{BuildTools/stable/}}}''current_release'' into a subdirectory named {{{BuildTools}}} in the package's base directory. Otherwise, the autotools will not work.
     81 * In the base and project directory of the package, include '''{{{config.guess}}}''', '''{{{config.sub}}}''', '''{{{depcomp}}}''', '''{{{install-sh}}}''', '''{{{ltmain.sh}}}''', and '''{{{missing}}}'''.  These files will be copied into the directory automatically when you run {{{BuildTools/run_autotools}}}.
     82   For users that checkout the base directory of a project, it is sufficient to find these files in the base directory. However, for users that checkout only the project directory and want to build against installed versions of dependencies these files are also required to be present in the project directory.
    8483
    8584== Working On Your Project ==