wiki:pm-structure-config

Version 4 (modified by andreasw, 14 years ago) (diff)

minor update

Basic Structure of the configure.ac File

Make sure you read the introduction to the autotools first. Here you can find the full Autoconf documentation.

General Concepts

Autoconf 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.

Everything 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 "#".

By 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_.

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 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.

Beginning of the configure.ac file

At the beginning of a configure.ac file in COIN you will find something like the following:

## Copyright (C) 2006 International Business Machines.
# All Rights Reserved.
# This file is distributed under the Common Public License.

## $Id: configure.ac,v 1.1.2.1 2006/04/19 23:25:12 andreasw Exp $

# Author:  Andreas Waechter            IBM    2006-04-13

#############################################################################
#                       Names and other basic things                        #
#############################################################################

AC_PREREQ(2.59)

AC_INIT([SuperSolver],[1.2.1],[http://projects.coin-or.org/SuperSolver])

AC_COPYRIGHT([
Copyright 2006 International Business Machines and others.
All Rights Reserved.
This file is part of the open source package Coin which is distributed
under the Common Public License.])

# List one file in the package so that the configure script can test
# whether the package is actually there
AC_CONFIG_SRCDIR(src/SuperSolverMain.cpp)

# Where should everything be installed by default?  Here, we want it
# to be installed directly in 'bin', 'lib', 'include' subdirectories
# of the directory where configure is run.  The default would be
# /usr/local.
AC_PREFIX_DEFAULT([`pwd`])
  • 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").
  • 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 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.
  • 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.
  • 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.
  • 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.

The Body of the configure.ac File

After 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.

  • Usually, one first checks for the availability and names of programs (such as compilers and other tools).
  • Then one lists macros for the test of header files, libraries, etc., and determines the values of autoconf output variables or configuration header #defines.

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

VARNAME="value1 and maybe a few more"

It is important not the have spaces before and after the = symbol'''

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 Autoconf documentation.

The End of the configure.ac File

At 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:

##############################################################################
#                   Finishing up by writing all the output                   #
##############################################################################

# Here list all the files that configure should create (except for the
# configuration header file)
AC_CONFIG_FILES([Makefile
                 examples/Makefile
                 src/Makefile
                 test/Makefile
                 clp_addlibs.txt])

# Here put the location and name of the configuration header file
AC_CONFIG_HEADER([inc/config_clp.h])

# Finally, we let configure write all the output...
AC_COIN_FINALIZE
  • 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@").
  • 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.
  • 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.