wiki:pm-project-config

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

cleaned up

The Project Directory configure.ac File

The purpose of the configuration script in a project's main directory (Clp and CoinUtils in the example) is to test everything required for the compilation of the project's source code, and to set up all Makefiles.

The beginning and the end of the file follow the basic structure of configure.ac files. The body for a project main directory configure.ac contains the following parts:

  • Initialization of tools and checks for programs, such as compiler
  • Checks for other COIN components
  • Checks for third party libraries (such as GNU's zlib or a third party LP solver)
  • Generation of links to files required for unit tests or example programs in case of a VPATH configuration
  • Other project specific tests and settings (such as byte size of types, existence of header files etc)

In the following we describe the indiviual parts of the configure.ac file body in more details and present examples.

Initialization of Tools and Compilers

This part usually looks like this:

#############################################################################
#                         Standard build tool stuff                         #
#############################################################################

# Get the system type
AC_CANONICAL_BUILD

# If this project depends on external projects, the Externals file in
# the source root directory contains definition of where to find those
# externals.  The following macro ensures that those externals are
# retrieved by svn if they are not there yet.
AC_COIN_PROJECTDIR_INIT

# Check if user wants to produce debugging code
AC_COIN_DEBUG_COMPILE

# Get the name of the C compiler and appropriate compiler options
AC_COIN_PROG_CC

# Get the name of the C++ compiler and appropriate compiler options
AC_COIN_PROG_CXX

# Initialize automake and libtool
AC_COIN_INIT_AUTO_TOOLS
  • The AC_CANONICAL_BUILD makes the configure script check the host type, on which the script is run.
  • AC_COIN_PROJECTDIR_INIT is a COIN specific macro that inializes a few things and should be included at this place
  • The macro AC_COIN_DEBUG_COMPILE makes the --enable-debug flag available for configure. It also sets the Automake conditional COIN_DEUBG accordingly, as well as the COIN_DEBUG for the configuration header file.
  • The macros AC_COIN_PROG_CC and AC_COIN_PROG_CXX determine the name of the C and C++ compiler, and chooses the default compiler options. One only needs to specify those compilers that are required to compile the source code in the project. If the source code contains Fortran files, one should use AC_COIN_PROG_F77.
  • Finally, the AC_COIN_INIT_AUTO_TOOLS sets everything up that is required to have Automake and Libtool work correctly.

Check for Other COIN Components

This part looks like this:

#############################################################################
#                              COIN components                              #
#############################################################################

AC_COIN_HAS_PROJECT(Cbc)
AC_COIN_HAS_PROJECT(Cgl)
AC_COIN_HAS_PROJECT(Clp)
AC_COIN_HAS_PROJECT(CoinUtils)
AC_COIN_HAS_PROJECT(DyLP)
AC_COIN_HAS_PROJECT(Osi)
AC_COIN_HAS_PROJECT(Sym)
AC_COIN_HAS_PROJECT(Vol)

Here, for each COIN project that is required to compile the libraries and programs in this project (including unit tests and example programs), we list its name as argument of one AC_COIN_HAS_PROJECT. This example is taken from Cbc, and as you see, the project itself should also be listed.

The final configure script will search for the project; first, it will check if itself is this package (by comparing with the name that is given to AC_INIT at the beginning of the configure.ac file), and otherwise looks for a parallel subdirectory with the projects name.

If the project is found, a #define will set in the configuration header files with the name COIN_HAS_PRJCT (where PRJCT is replaced by the name of the project in all capital letters, e.g., COIN_HAS_CLP in the example above). Also, an Automake conditional with the same name will be set to true.

The projects can be listed in any order.

Checks For Third-Party Components

For a few third-party packages we have defined special COIN macros, namely for those packages that are released under the GNU Public License (GLP). Those libraries will only be used, if the user specified the --enable-gnu-packages flag for configure. So far, those macros are

  • AC_COIN_CHECK_GNU_ZLIB: Check for the zlib compression library
  • AC_COIN_CHECK_GNU_BZLIB: Check for the bzlib compression library
  • AC_COIN_CHECK_GNU_READLINE: Check for the readline library.

Those macros check for the availability of those packages (if requested by the user with the --enable-gnu-packages). If the package is available, it adds the flags required for linking to the ADDLIBS output variable, #defines the preprocessor COIN_HAS_ZLIB (and similar) in the configuration header file, and defines an Automake conditional with the same name.

We also provide a generic macro for testing the availability of other third-party libraries, called AC_COIN_HAS_USER_LIBRARY. A typical invocation looks like this:

AC_COIN_HAS_USER_LIBRARY([Cplex],[CPX],[cplex.h],[CPXgetstat])

The arguments have to following meaning:

  1. Name of the library package. This is the name as it will appear in the configure output.
  2. Abbreviation of the library package. This should all be in capital letters. Using this macro will make configure options available to the user, to specify the link commands for the library, and to specify the directory in which the library header files can be found. The name of the flags use the abbreviation given as this second argument to the macro. In the above exmaple, the --with-cpx-lib flag can be used by the user to specify the link commands, and the flags --with-cpx-incdir to specify the directory with the header files.
  3. Name of a header file. This is the name of a header file that should be present in the include directory provided by the user via -with-cpx-incdir. If this file is not found, the configure script terminates with an error message. If this argument is omitted, the test will not be performed.
  4. Name of a C function in the library. This should be the name of a C function has should be defined in the library. If the users uses the --with-cpx-lib flag, it is tested if this function is indeed available. If not, the configure script with fail with an error message. If this argument for the macro is omitted, this test is skipped.

A user will have to either specify both --with-libname-incdir and --with-libname-lib flags, or none. After successful completation of the tests, the link commands will be added to the automake output variable ADDLIBS. Also, the preprocessor macro COIN_HAS_CPX (where "CPX" is replaced by the abbreviation given to the macro) for the configuration header file and an Automake conditional with the same name are defined.

Generation of Links for Data Files

Some unit test programs and example programs require input data files. In a VPATH configuration (i.e., the compilation takes place in different directories from where the source files are) it is then important to make sure that links to those data files exist so that the programs can be run in those directories.

To this purpose, the AC_COIN_VPATH_LINK macro should be used for each such file. An example of this section of the configure.ac file from the Volume project is

##############################################################################
#                   VPATH links for example input files                      #
##############################################################################

# In case this is a VPATH configuration we need to make sure that the
# input files for the examples are available in the VPATH directory.

AC_COIN_VPATH_LINK(examples/VolUfl/ufl.par)
AC_COIN_VPATH_LINK(examples/VolUfl/data.gz)
AC_COIN_VPATH_LINK(examples/Volume-LP/data.mps.gz)
AC_COIN_VPATH_LINK(examples/Volume-LP/lp.par)

Project Specific Tests

If you need to perform other tests, you might need to use further autoconf macros and/or write some /bin/sh code. For this, please consult the autoconf documentation.

If you have questions or run into problems, or would like some help to write a specific test, please submit a ticket at the BuildTools Trac pages, using the "New Ticket" link above.