Version 6 (modified by stefan, 11 years ago) (diff)

fix typos

Table of Contents

  1. Working With the GNU Autotools
    1. Introduction
    2. The Files
    3. The Files
    4. Running the Autotools
    5. Which Files Should be in the Subversion Repository?
    6. Working On Your Project
  2. Autotools Basics
    1. autoconf
    2. automake
    3. libtool
  3. Basic Structure of the File
    1. General Concepts
    2. Beginning of a file
    3. The Body of the File
    4. The End of the File
  4. The Package Base Directory File
  5. The Project Directory File
    1. Initialization of Tools and Compilers
    2. Check for other COIN-OR Components
    3. Checks for some specific System Libraries
    4. Check for User Libraries
    5. Generation of Links for Data Files
    6. Project Specific Tests
  6. Configuration Header Files
    1. Private and public header files
    2. Header files for non-autotools setups
    3. Bringing them all together
    4. Example
  7. Introduction of Automake Concepts
  8. The Package Base Directory File
  9. The Project Main Directory File
  10. The Source Directories Files
    1. Beginning of the File
    2. Building a Library
    3. Building a Program
    4. Additional Flags
    5. Installation of Header Files
  11. The Test Directory File
    1. Beginning of the File
    2. Compilation of the Unit Test Program
    3. The Test Target
    4. House Cleaning
  12. The pkg-config configuration files of a project
    1. Introduction
    2. The .pc file of an installed COIN-OR project library
    3. The .pc file of an uninstalled COIN-OR project library
    4. The NO pkg-config case
  13. Using the Correct Version of the Autotools
  14. Brief Tutorial on Switching from BuildTools 0.5 to 0.7
    1. What Needs to be Edited
    2. Externals to Dependencies
    3. Changes to Installation Directories
    4. Changes to autotools files
    5. Changes to configuration header files
  15. Hints, tricks, bugs, and suggestions
    1. Using autoreconf

Configuration Header Files

Recall the introduction on configuration header files. The AC_CONFIG_HEADER macro in allows to setup a list of configuration header files that convey information about the configuration run to the source code of the package in the form of #define statements. Since the define statements in different projects may define the same symbols (e.g., PACKAGE_NAME or HAVE_ZLIB), it is undesirable to install a full configuration header file and to require them for building against the package. On the other hand, sometimes it is necessary to convey some information about a package configuration via the header file to users of that package.

Private and public header files

Therefore, in COIN-OR, the convention is to use two header files, a private header file which has the defines for all symbols that are needed to build the package, and a public header file which has the defines only for symbols that may be required by a user of the package. The private header file uses the name config.h and must not be installed. The public header file uses the name config_prjct.h when it is uninstalled and will usually get installed with the name PrjctConfig.h. It is important that the public header defines only symbols with unique names, so conflicts from including several header files are avoided.

Header files for non-autotools setups

To complicate things further, COIN-OR wants to make it possible to compile COIN-OR code in environments which do not support autotools (e.g., MS Developer Studio). In these systems, the config.h and config_prjct.h are substituted by header files config_default.h and config_prjct_default.h that define a set of default symbols. A user may then have to adjust these files for her system.

Bringing them all together

The logic which of the four header files to include in which situation is implemented in a fifth header file PrjctConfig.h. None of the config*.h files should ever be included (directly) in any source code (internal or external to the project), but the file PrjctConfig.h should be include instead. In an autotools build of the project itself, the file config.h will be included (through inclusion in PrjctConfig.h). When someone builds against the library exported by a project after it has been installed, then PrjctConfig.h will be a copy of the public header config_prjct.h and will be included instead. Further, in a non-autotools based setup, PrjctConfig.h will include either config_default.h or config_prjct_default.h (as appropriate for internal building versus external linking). The distinction is made by two defines that may be specified as arguments to the compiler command line to distinguish between building and linking. In an autotools setup with configuration header files, the symbol HAVE_CONFIG_H is always defined. Further, the symbol Prjct_BUILD is defined whenever a file belonging to project Prjct is built.


As an example, before installation, the CoinUtilsConfig.h contains


#include "config.h"
#include "config_coinutils.h"

#else /* HAVE_CONFIG_H */

#include "config_default.h"
#include "config_coinutils_default.h"

#endif /* HAVE_CONFIG_H */

#endif /*__COINUTILSCONFIG_H__*/

The files config.h and config_coinutils.h are created by the autotools scripts at the end of configure from template files and, because CoinUtils' file contains the statement

AC_CONFIG_HEADER([inc/config.h inc/config_coinutils.h])

Further, the template file is generated automatically by autoheader when the project manager calls the autotools. Therefore, only the public header file config_coinutils.h needed to be setup, which can be done by copying interesting lines from the private header file. In case of CoinUtils, the public header is

/* inc/  */

/* Version number of project */

/* Major Version number of project */

/* Minor Version number of project */

/* Release Version number of project */

/* Define to 64bit integer type */
#undef COIN_INT64_T

/* Define to integer type capturing pointer */

/* Define to 64bit unsigned integer type */
#undef COIN_UINT64_T

After a user run configure, the #undef statements are replaced by corresponding #define statements, depending on the outcome of tests performed by configure.

For a non-autotools based setup, the files config_default.h and config_coinutils_default.h are provided. The public header config_coinutils_default.h is currently

/* Version number of project */
#define COINUTILS_VERSION  "trunk"

/* Major Version number of project */

/* Minor Version number of project */

/* Release Version number of project */

  Define to 64bit integer types. Note that MS does not provide __uint64.

  Microsoft defines types in BaseTsd.h, part of the Windows SDK. Given
  that this file only gets used in the Visual Studio environment, it
  seems to me we'll be better off simply including it and using the
  types MS defines. But since I have no idea of history here, I'll leave
  all of this inside the guard for MSC_VER >= 1200. If you're reading this
  and have been developing in MSVS long enough to know, fix it.  -- lh, 100915 --
#if _MSC_VER >= 1200
# include <BaseTsd.h>
# define COIN_INT64_T INT64
# define COIN_UINT64_T UINT64
  /* Define to integer type capturing pointer */
# define COIN_INT64_T long long
# define COIN_UINT64_T unsigned long long
# define COIN_INTPTR_T int*

and the private header file is config_default.h is

/* include the COIN-OR-wide system specific configure header */
#include "configall_system.h"

/* include the public project specific macros */
#include "config_coinutils_default.h"

/*             HERE DEFINE THE PROJECT SPECIFIC MACROS                     */
/*    These are only in effect in a setting that doesn't use configure     */

/* Define to the debug sanity check level (0 is no test) */

/* Define to the debug verbosity level (0 is no output) */

/* Define to 1 if bzlib is available */
/* #define COIN_HAS_BZLIB */

/* Define to 1 if zlib is available */
/* #define COIN_HAS_ZLIB */

#ifdef _MSC_VER
/* Define to be the name of C-function for Inf check */
#define COIN_C_FINITE _finite

/* Define to be the name of C-function for NaN check */
#define COIN_C_ISNAN _isnan

Since both files need to be setup by the user, here the private header includes the public header to avoid redundancy. Further, a header configall_system.h is included that tries to provide commonly used defines. Note that file config_coinutils.h is installed as CoinUtilsConfig.h for use by external users linking to the CoinUtils library after the fact. This occurs by addition of the following lines to src/

ConfigHeader = CoinUtilsConfig.h

        echo "#ifndef __CONFIG_COINUTILS_H__" > bla
        echo "#define __CONFIG_COINUTILS_H__" >> bla
        tail -n +3 ../inc/config_coinutils.h >> bla
        echo "#endif" >> bla
        $(install_sh_DATA) bla $(DESTDIR)$(includecoindir)/$(ConfigHeader)
        rm -f bla

        rm -f $(DESTDIR)$(includecoindir)/$(ConfigHeader)