Changes between Version 7 and Version 8 of pm-structure-config


Ignore:
Timestamp:
Apr 18, 2007 9:50:20 PM (14 years ago)
Author:
lou
Comment:

General cleanup.

Legend:

Unmodified
Added
Removed
Modified
  • pm-structure-config

    v7 v8  
    66== General Concepts ==
    77
    8 Autoconf works by running the preprocessor program {{{m4}}}, using the {{{configure.ac}}} file as input.  This file contains '''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.
     8Autoconf works by running the macro expansion program {{{m4}}}, using the {{{configure.ac}}} file as input.  This file contains '''macros''' that are expanded (recursively) until, in the end, a pure shell script for {{{sh}}} is created.  The {{{configure.ac}}} input file can also contain '''sh commands''', which will appear literally in the final {{{configure}}} script.
    99
    1010Everything 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 "{{{#}}}".
    1111
    12 By convention, macro names are capitalized, and they start with '''AC_''' if the macro is an autoconf 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 provide additional custom macros for COIN configuration (in the {{{BuildTools/coin.m4}}} file), which start with '''AC_COIN_'''. [http://www.gnu.org/software/autoconf/manual/ In the autoconf documentation] you can find a description of the predefined autoconf macros.
     12By convention, macro names are capitalized, and they start with '''{{{AC_}}}''' if the macro is an {{{autoconf }}} macro, '''{{{AM_}}}''' if it's an {{{automake}}} macro.  We provide additional custom macros for COIN configuration (in the [source:stable/0.5/coin.m4 coin.m4] file), which start with '''{{{AC_COIN_}}}'''. [http://www.gnu.org/software/autoconf/manual/ In the autoconf documentation] you can find a description of the predefined autoconf macros.
    1313
    14 Macros 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 square brackets "{{{[}}}" 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.
     14Like subroutines, macros can be written to have parameters and be invoked with arguments for those parameters.  Parameters and arguments are separated by commas.  The '''quotation symbols''' for {{{autoconf}}} are the square brackets "{{{[}}}" and "{{{]}}}".  If a single argument contains a comma, the argument must be quoted by enclosing it in brackets.  If in doubt, use quotation. If a macro is written to use four parameters, but only two arguments are provided, then the last two parameters are assumed to be unset (equivalent to an argument of {{{[]}}}).
    1515
    16 == Beginning of the configure.ac file ==
     16== Beginning of a {{{configure.ac}}} file ==
    1717
    1818At the beginning of a {{{configure.ac}}} file in COIN you will find something like the following:
     
    4646
    4747# Where should everything be installed by default?  Here, we want it
    48 # to be installed directly in 'bin', 'lib', 'include' subdirectories
     48# to be installed directly in 'bin', 'lib', and 'include' subdirectories
    4949# of the directory where configure is run.  The default would be
    5050# /usr/local.
     
    5252}}}
    5353
    54  * The file should contain the '''copyright notice''', 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 notice''', 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 committed (assuming that the {{{svn:keywords}}} property for this file contains "{{{Id}}}").
    5555
    56  * 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 the situation where different versions of the autotools generate large differences in the generated configuration files when multiple developers work on a project simultaneously.
     56 * The '''{{{AC_PREREQ}}}''' macro specifies the version number of {{{autoconf}}} that is required to generate 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 the situation where different versions of the autotools generate large differences in the generated configuration files when multiple developers work on a project simultaneously.
    5757
    58  * The '''AC_INIT''' macro takes as arguments the name of the project, 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}}}.
     58 * The '''{{{AC_INIT}}}''' macro takes as arguments the name of the project, 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 will be created by '{{{make dist}}}'.
    5959
    6060 * The argument of the '''AC_COPYRIGHT''' macro becomes the copyright notice in the generated {{{configure}}} script.
    6161
    62  * The '''AC_CONFIG_SRCDIR''' helps the {{{configure}}} script to do a sanity check. When executed, the {{{configure}}} script tests if it 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.
     62 * The '''{{{AC_CONFIG_SRCDIR}}}''' helps the {{{configure}}} script to do a sanity check. When the shell commands generated by expanding {{{AC_CONFIG_SRCDIR}}} are executed, the {{{configure}}} script tests if it is in the correct location with respect to the rest of the package.  As the argument, one provides a file (such as a source file) that belongs to the package.
    6363
    64  * The argument of the '''AC_PREFIX_DEFAULT''' macro determines where the products of the compilation should be installed by a {{{make install}}}, unless this location is overwritten by the user specifying the {{{--prefix}}} argument to configure.  In COIN, we decided to use as the default location the directory where the {{{configure}}} script is run.
     64 * The argument of the '''{{{AC_PREFIX_DEFAULT}}}''' macro determines where the products of the compilation should be installed by a '{{{make install}}}' command, unless this location is overwritten by the user by specifying the {{{--prefix}}} argument to {{{configure}}}.  In COIN, we decided to use as the default location the directory where the {{{configure}}} script is run.
    6565
    66  As you can see in the invocation of this macro. it is '''possible to give a shell command as an argument for a macro'''. (In this case we tell autoconf to use the output of {{{pwd}}} that will be produced when the generated {{{configure}}} script is run.) But don't forget that autoconf and automake only perform macro expansion. Shell commands used as parameters to autoconf macros are just text strings to autoconf. They are not executed until the generated {{{configure}}} script is executed.
     66 As you can see in the invocation of this macro. it is '''possible to give a shell command as an argument for a macro'''.  Don't forget that {{{autoconf}}} and {{{automake}}} only perform macro expansion. Shell commands used as arguments to {{{autoconf}}} macros are just text strings to {{{autoconf}}}. The shell command will not be executed until the generated {{{configure}}} script is executed. '''This is a feature! ''' In this case, the result is that the {{{configure}}} script will set the default installation directory according to the output of {{{pwd}}} produced when the generated {{{configure}}} script is run in the user's environment.
    6767
    68 == The Body of the configure.ac File ==
     68== The Body of the {{{configure.ac}}} File ==
    6969
    70 After the initialization described above, {{{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.
     70After the initialization described above, {{{configure.ac}}} usually contains a number of '''macros that will be expanded into the tests''' that are to be run by the {{{configure}}} script. The content of the body depends on whether this is a [wiki:pm-autotools#BaseDirConfigAc base directory configure.ac] file or a [wiki:pm-autotools#ProjDirConfigAc project directory configure.ac] file. In general, one checks for the '''availability and names of programs''' (such as compilers and other tools), tests for the presence of '''header files, libraries, ''etc.'' ''', and sets the values of {{{autoconf}}} output variables and [wiki:pm-autotools-intro#ConfigurationHeaderFiles configuration header] {{{#define}}}s.
    7171
    72  * Usually, one first checks for the '''availability and names of programs''' (such as compilers and other tools).
     72Autoconf output variables are specified with the macro invocation '''{{{AC_SUBST(VARNAME)}}}''', where {{{VARNAME}}} is the name of the output variable.  The value of the output variable will be 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{{{
     74VARNAME="value1 and maybe a few more"
     75}}}
     76'''The {{{sh}}} shell does not allow spaces before and after the {{{=}}} symbol! '''
    7377
    74  * 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.
     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].
    7579
    76 During 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
    77 
    78 {{{VARNAME="value1 and maybe a few more"}}}
    79 
    80 ''It is important not the have spaces before and after the {{{=}}} symbol!'''
    81 
    82 In 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].
    83 
    84 == The End of the configure.ac File ==
     80== The End of the {{{configure.ac}}} File ==
    8581
    8682At the end of the {{{configure.ac}}} file, we need to make sure that the '''output is written'''  In COIN, the bottom of the file usually looks like this:
     
    8884{{{
    8985##############################################################################
    90 #                   Finishing up by writing all the output                   #
     86#                   Finish up by writing all the output                   #
    9187##############################################################################
    9288
     
    106102}}}
    107103
    108  * 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@}}}").
     104 * The '''{{{AC_CONFIG_FILES}}}''' macro takes as its single argument a space-separated list of the files that are to be created from the corresponding {{{.in}}} template files. These are all the {{{Makefile}}}s and maybe some additional files.  In the example shown here, the project  installs a ''prjct''{{{_addlibs.txt}}} file, and this will also be created from a template. '''A template file must exist for each file listed in the argument to {{{AC_CONFIG_FILES}}}.'''
    109105
    110  * 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}}}.  The {{{configure.ac}}} files in package base directories don't need this, since they do not gather information for compilation.
     106 * The '''{{{AC_CONFIG_HEADER}}}''' macro takes as its argument the name of the [wiki:pm-autotools-intro#ConfigurationHeaderFiles configuration header] file that is to be created by {{{configure}}}.  For this file, the template will be created by the autotools utility {{{autoheader}}}. [wiki:pm-autotools#BaseDirConfigAc Base directory configure.ac] files don't need this, since they do not gather information for compilation.
    111107
    112  * 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.
     108 * The '''{{{AC_COIN_FINALIZE}}}''' macro takes care of actaully writing the output. Internally, it uses the {{{AC_OUTPUT}}} macro, but since additional actions might have to be taken, you should use {{{AC_COIN_FINALIZE}}} instead of using {{{AC_OUTPUT}}} directly.  {{{AC_COIN_FINALIZE}}} also writes the "configuration successful" message before the {{{configure}}} script finally stops.