Changes between Version 17 and Version 18 of pm-autotools-intro


Ignore:
Timestamp:
May 8, 2011 7:35:38 AM (9 years ago)
Author:
stefan
Comment:

update on configuration header files

Legend:

Unmodified
Added
Removed
Modified
  • pm-autotools-intro

    v17 v18  
    5858=== Configuration Header Files ===
    5959
    60 One output file generated by the {{{configure}}} script is worth separate mention. The configuration header file (you may have noticed the {{{config.h}}} file in GNU packages) can be used to '''convey information about the configuration run to the source code''' of the package. Some examples:
     60Some output files generated by the {{{configure}}} script are worth separate mention. The configuration header file (you may have noticed the {{{config.h}}} file in GNU packages) can be used to '''convey information about the configuration run to the source code''' of the package. Some examples:
    6161  * System calls, such as those for obtaining the CPU time, are different on different platforms, and the header files in which they are declared are also different. The {{{configure}}} script can '''test for the presence of header files and functions'''. 
    6262
     
    6565  * The '''user of a package can specify certain aspects of the configuration when {{{configure}}} is run''', for example, the set of available linear programming solvers, and where their libraries and header files reside.
    6666
    67 The {{{configure}}} script will place {{{#define}}} statements in the configuration header file. These can simply define a symbol or set a symbol to a specific value (such as the path to a default directory).  In COIN-OR, '''the convention is to
    68 use the name {{{config_}}}''prjct''{{{.h}}} for the configuration header file for ''Prjct''.''' However, to make it possible to compile the COIN-OR code in environments which do not support autotools (''e.g.'', MS Developer Studio), this file should not be included directly in your source code.  Instead, a '''"wrapper" header file ''Prjct''{{{Config.h}}} should be used'''. On UNIX-like machines this wrapper should include {{{config_}}}''prjct''{{{.h}}}. On other systems, it should include a system specific header file for platform dependencies, plus definitions for other symbols which may need to be changed by the user. Look to existing COIN-OR projects for examples.
     67  * The {{{AC_INIT}}} macro in the {{{configure.ac}}} file leads information about the package name and package version number in the header file, so these parameters to be maintained only in the {{{configure.ac}}} file.
     68
     69The {{{configure}}} script will place {{{#define}}} statements in the configuration header files. These can simply define a symbol or set a symbols to a specific value (such as the path to a default directory). However, since the define statements in different projects may define the same symbols (e.g., {{{PACKAGE_NAME}}} or {{{HAVE_ZLIB}}}), it is undesirable to install the config header files and requiring 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.
     70
     71Therefore, 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}}} and can be installed'''. However, it is important that the public header '''defines only symbols with unique names''', so conflicts from including several header files are avoided.
     72
     73To 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.
     74
     75The logic which of the four header files to include in which situation is implemented in a fifth header file ''Prjct''{{{Config.h}}}. In any source code, none of the {{{config*.h}}} files should be included, but always the file ''Prjct''{{{Config.h}}}.
     76It ensures that in an autotools based setup, the file {{{config.h}}} is included whenever the project itself is build and otherwise (i.e., someone builds against the project) the file {{{config_}}}''prjct''{{{.h}}} is included. Further, in a non-autotools based setup, it includes either {{{config_default.h}}} or {{{config_}}}''prjct''{{{default.h}}}.
     77The distinction is made by two defines that may be specified as arguments in the compiler command line.
     78These ensure that in an autotools setup with configuration header files, always the symbol {{{HAVE_CONFIG_H}}} is defined. Further, the symbol ''Prjct''{{{_BUILD}}} is defined whenever a file belonging to project ''Prjct'' is build.
     79
     80As an example, the {{{CoinUtilsConfig.h}}} contains
     81{{{
     82#ifndef __COINUTILSCONFIG_H__
     83#define __COINUTILSCONFIG_H__
     84
     85#ifdef HAVE_CONFIG_H
     86#ifdef COINUTILS_BUILD
     87#include "config.h"
     88#else
     89#include "config_coinutils.h"
     90#endif
     91
     92#else /* HAVE_CONFIG_H */
     93
     94#ifdef COINUTILS_BUILD
     95#include "config_default.h"
     96#else
     97#include "config_coinutils_default.h"
     98#endif
     99
     100#endif /* HAVE_CONFIG_H */
     101
     102#endif /*__COINUTILSCONFIG_H__*/
     103}}}
     104The files {{{config.h}}} and {{{config_coinutils.h}}} are created by the autotools scripts at the end of configure from template files {{{config.h.in}}} and {{{config_coinutils.h.in}}}, because !CoinUtils' {{{configure.ac}}} file contains the statement
     105{{{
     106AC_CONFIG_HEADER([inc/config.h inc/config_coinutils.h])
     107}}}
     108Further, the template file {{{config.h.in}}} 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
     109{{{
     110/* inc/config_coinutils.h.in.  */
     111
     112/* Version number of project */
     113#undef COINUTILS_VERSION
     114
     115/* Major Version number of project */
     116#undef COINUTILS_VERSION_MAJOR
     117
     118/* Minor Version number of project */
     119#undef COINUTILS_VERSION_MINOR
     120
     121/* Release Version number of project */
     122#undef COINUTILS_VERSION_RELEASE
     123
     124/* Define to 64bit integer type */
     125#undef COIN_INT64_T
     126
     127/* Define to integer type capturing pointer */
     128#undef COIN_INTPTR_T
     129
     130/* Define to 64bit unsigned integer type */
     131#undef COIN_UINT64_T
     132}}}
     133After a user run configure, the {{{#undef}}} statements are replaced by corresponding {{{#define}}} statements, depending on the outcome of tests performed by configure.
     134
     135For 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
     136{{{
     137/* Version number of project */
     138#define COINUTILS_VERSION  "trunk"
     139
     140/* Major Version number of project */
     141#define COINUTILS_VERSION_MAJOR   9999
     142
     143/* Minor Version number of project */
     144#define COINUTILS_VERSION_MINOR   9999
     145
     146/* Release Version number of project */
     147#define COINUTILS_VERSION_RELEASE 9999
     148
     149/*
     150  Define to 64bit integer types. Note that MS does not provide __uint64.
     151
     152  Microsoft defines types in BaseTsd.h, part of the Windows SDK. Given
     153  that this file only gets used in the Visual Studio environment, it
     154  seems to me we'll be better off simply including it and using the
     155  types MS defines. But since I have no idea of history here, I'll leave
     156  all of this inside the guard for MSC_VER >= 1200. If you're reading this
     157  and have been developing in MSVS long enough to know, fix it.  -- lh, 100915 --
     158*/
     159#if _MSC_VER >= 1200
     160# include <BaseTsd.h>
     161# define COIN_INT64_T INT64
     162# define COIN_UINT64_T UINT64
     163  /* Define to integer type capturing pointer */
     164# define COIN_INTPTR_T ULONG_PTR
     165#else
     166# define COIN_INT64_T long long
     167# define COIN_UINT64_T unsigned long long
     168# define COIN_INTPTR_T int*
     169#endif
     170}}}
     171and the private header file is {{{config_default.h}}} is
     172{{{
     173/* include the COIN-OR-wide system specific configure header */
     174#include "configall_system.h"
     175
     176/* include the public project specific macros */
     177#include "config_coinutils_default.h"
     178
     179/***************************************************************************/
     180/*             HERE DEFINE THE PROJECT SPECIFIC MACROS                     */
     181/*    These are only in effect in a setting that doesn't use configure     */
     182/***************************************************************************/
     183
     184/* Define to the debug sanity check level (0 is no test) */
     185#define COIN_COINUTILS_CHECKLEVEL 0
     186
     187/* Define to the debug verbosity level (0 is no output) */
     188#define COIN_COINUTILS_VERBOSITY 0
     189
     190/* Define to 1 if bzlib is available */
     191/* #define COIN_HAS_BZLIB */
     192
     193/* Define to 1 if zlib is available */
     194/* #define COIN_HAS_ZLIB */
     195
     196#ifdef _MSC_VER
     197/* Define to be the name of C-function for Inf check */
     198#define COIN_C_FINITE _finite
     199
     200/* Define to be the name of C-function for NaN check */
     201#define COIN_C_ISNAN _isnan
     202#endif
     203}}}
     204Since 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.
     205
    69206
    70207== {{{automake}}} ==