Changes between Version 1 and Version 2 of pm-structure-config


Ignore:
Timestamp:
May 31, 2006 3:43:08 PM (14 years ago)
Author:
andreasw
Comment:

first draft

Legend:

Unmodified
Added
Removed
Modified
  • pm-structure-config

    v1 v2  
    11= Basic Structure of the configure.ac File =
    22
    3 Autoconf works by running the preprocessor program {{{m4}}}, using the {{{configure.ac}}} as input.  This input file containts '''proprocessor macros''', that are expanded (recursively), until in the end a pure shell script for the {{{/bin/sh}}} is created.  The {{{configure.ac}}} input file can also contain '''{{{/bin/sh}}} commands''', which will appear litterally in the final {configure} script.
     3Make sure you read the [wiki:pm-autotools-intro introduction to the autotools] first.
     4[http://www.gnu.org/software/autoconf/manual/ Here you can find the full Autoconf documentation].
     5
     6== General Concepts ==
     7
     8Autoconf works by running the preprocessor program {{{m4}}}, using the {{{configure.ac}}} as input.  This input file containts '''preprocessor macros''', that are expanded (recursively), until in the end a pure shell script for {{{/bin/sh}}} is created.  The {{{configure.ac}}} input file can also contain '''/bin/sh commands''', which will appear literally in the final {{{configure}}} script.
    49
    510Everything in a line following a "{{{#}}}" is a '''comment'''.  Comments are usually copied into the generated {{{configure}}} script, unless the line starts with at least two "{{{#}}}".
    611
    7 == Beginning of the File ===
     12By convention, macro names are capitalized, and they start with '''AC_''' if the macro is an Automake feature, or '''AM_''' if it corresponds to a macro in connection with Automake (such as {{{AM_CONDITIONAL}}}, which defines an Automake conditional that can be used for an "{{{if}}}" in the {{{Makefile.am}}} file).  We also provide additional custom macros for COIN configuration (in the {{{BuildTools/coin.m4}}} file), which start with '''AC_COIN_'''.
     13
     14Macros can be given arguments, depending on the macro.  Arguments are separated by commas.  If a macro takes, say, four arguments, but only two are provided, then the last two arguments are assumed to be unset.  The quotation symbols for Autoconf are the squared bracket "{{{[}}}" and "{{{]}}}".  Sometimes it is necessary to enclose arguments in those brackets, for example, when the argument itself contains a comma.  If in doubt, use quotation.
     15
     16== Beginning of the configure.ac file ==
    817
    918At the beginning of a {{{configure.ac}}} file in COIN you will find something like the following:
     
    2433AC_PREREQ(2.59)
    2534
    26 AC_INIT([SuperSolver],[0.1],[http://projects.coin-or.org/SuperSolver])
     35AC_INIT([SuperSolver],[1.2.1],[http://projects.coin-or.org/SuperSolver])
    2736
    2837AC_COPYRIGHT([
     
    3140This file is part of the open source package Coin which is distributed
    3241under the Common Public License.])
    33 
    34 AC_REVISION(0.9)
    3542
    3643# List one file in the package so that the configure script can test
     
    4552}}}
    4653
    47  * The file should contain the copyright note, information about the authors, and state under what license the file is made available.  Note the {{{$Id ...$}}} string.  This is a subversion keyword, which is expanded to contain information about the file, such as revision number, author and date of the last submission etc, when the file is submitted (assuming that the {{{svn::keywords}}} property for this file contains "{{{Id}}}").
     54 * The file should contain the '''copyright note''', information about the '''authors''', and state under what '''license''' the file is made available.  Note the {{{$Id ...$}}} string.  This is a subversion keyword, which is expanded to contain information about the file, such as revision number, author and date of the last submission etc, when the file is submitted (assuming that the {{{svn::keywords}}} property for this file contains "{{{Id}}}").
    4855
    4956 * The '''AC_PREREQ''' macro specifies the version number of autoconf that is required to generated a {{{configure}}} script from this input file.  In COIN we ask people to [wiki:pm-get-autotools use exactly the same versions of all the GNU autotools], so that we can collectively take care of bug fixes, and can avoid that different versions of the autotools generate large difference of the resulting output files if two developers work on a project simultaneously.
     
    5158 * The '''AC_INIT''' macro takes as arguments the name of the project for which this {{{configure.ac}}} file is, its version number, and   contact information in case a user wants to get in touch with the developers, e.g., in order to report a bug.  The name and version number determine the name of the tarball that can be created with {{{make dist}}}.
    5259
    53  *
     60 * The '''AC_CONFIG_SRCDIR''' helps the {{{configure}}} script to do a sanity check by testing, if the configure script is in the correct location with respect to the rest of the package.  As argument, one provides a file (such as a source file) that belongs to the package.
     61
     62 * The argument of the '''AC_PREFIX_DEFAULT''' determines where the products of the compilcation should be installed by a {{{make install}}}, unless this location is overwritten by a user by specifying the {{{--prefix}}} argument to configure.  In COIN, we decided to use as default location the directory where the {{{configure}}} script is run.  As you can see in the invocation of this macro. it is possible to give it a shell command as argument (in this case we tell autoconf to use the output of {{{pwd}}} during the configuration run).  Note, however, that it is not possible for all autoconf macros speficy arguments, whose value is determined when the final {{{configure}}} script is run by the user.
     63
     64== The Body of the configure.ac File ==
     65
     66After the initialization as described above, the {{{configure.ac}}} usually contains a number of macros that will be translated into the tests that are to be run by the final {{{configure}}} script.
     67
     68 * Usually, one first checks for the '''availability and names of programs''' (such as compilers and other tools).
     69
     70 * Then one lists macros for the test of '''header files, libraries, etc.''', and determines the values of autoconf output variables or configuration header {{{#define}}}s.
     71
     72During this main phase, the {{{configure}}} script determines the values of '''autoconf output variables''', which are later used to fill-in the placeholders in the autoconf output files (ending with {{{.in}}}).  Autoconf output variables are specified with the macro '''AC_SUBST(VARNAME)''', where {{{VARNAME}}} is the name of the output variable.  To set the value of the output variable is the value of the corresponding shell variable in the {{{configure}}} script.  Therefore, setting the value of an output variable is done with a shell command like
     73
     74{{{VARNAME="value1 and maybe a few more"}}}
     75
     76''It is important not the have spaces before and after the {{{=}}} symbol!'''
     77
     78In order to include a "{{{#define}}}# into the configuration header file that the {{{configure}}} script is going to create, one uses the '''AC_DEFINE''' and '''AC_DEFINE_UNQUOTED''' macros, see the [http://www.gnu.org/software/autoconf/manual/ Autoconf documentation].
     79
     80== The End of the configure.ac File ==
     81
     82At the end of the {{{configure.ac}}} file, we need to make sure that the output is actually written.  In COIN, the bottom of the file usually looks like this:
     83
     84{{{
     85##############################################################################
     86#                   Finishing up by writing all the output                   #
     87##############################################################################
     88
     89# Here list all the files that configure should create (except for the
     90# configuration header file)
     91AC_CONFIG_FILES([Makefile
     92                 examples/Makefile
     93                 src/Makefile
     94                 test/Makefile
     95                 clp_addlibs.txt])
     96
     97# Here put the location and name of the configuration header file
     98AC_CONFIG_HEADER([inc/config_clp.h])
     99
     100# Finally, we let configure write all the output...
     101AC_COIN_FINALIZE
     102}}}
     103
     104 * The '''AC_CONFIG_FILES''' macro takes as argument the list of the files that are to be created from the corresponding {{{.in}}} template files.  These are all the Makefiles, and maybe some additional files.  In a package that installs the {{{..._addlibs.txt}}} file, this is also created from a template (which only contains "{{{@ADDLIBS@}}}").
     105
     106 * The '''AC_CONFIG_HEADER''' macro takes as argument the name of the configuration header files that is to be created by {{{configure}}}.  Also for this file a template is required, but it looks differently, and it should be create by the Autoconf utility {{{autoheader}}}.
     107
     108 * The '''AC_COIN_FINALIZE''' finally takes care of actaully writing the output. It internally uses the '''AC_OUTPUT''' macro, but since additional actions might have to be taken, you should use '''AC_COIN_FINALIZE''' instead of '''AC_OUTPUT''' directly.  The '''AC_COIN_FINALIZE''' also writes the "configuration successful" message before the {{{configure}} script finally stops.