Changes between Initial Version and Version 1 of pm-config-header


Ignore:
Timestamp:
May 8, 2011 7:54:55 AM (10 years ago)
Author:
stefan
Comment:

new page for info on configuration header files

Legend:

Unmodified
Added
Removed
Modified
  • pm-config-header

    v1 v1  
     1= Configuration Header Files =
     2
     3Recall the [wiki:pm-autotools-intro#ConfigurationHeaderFiles introduction on configuration header files].
     4The {{{AC_CONFIG_HEADER}}} macro in {{{configure.ac}}} 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.
     5Since 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.
     6
     7== Private and public header files ==
     8
     9Therefore, 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.
     10
     11== Header files for non-autotools setups ==
     12
     13To 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.
     14
     15== Bringing them all together ==
     16
     17The 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}}}.
     18It 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}}}.
     19The distinction is made by two defines that may be specified as arguments in the compiler command line.
     20These 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.
     21
     22== Example ==
     23
     24As an example, the {{{CoinUtilsConfig.h}}} contains
     25{{{
     26#ifndef __COINUTILSCONFIG_H__
     27#define __COINUTILSCONFIG_H__
     28
     29#ifdef HAVE_CONFIG_H
     30#ifdef COINUTILS_BUILD
     31#include "config.h"
     32#else
     33#include "config_coinutils.h"
     34#endif
     35
     36#else /* HAVE_CONFIG_H */
     37
     38#ifdef COINUTILS_BUILD
     39#include "config_default.h"
     40#else
     41#include "config_coinutils_default.h"
     42#endif
     43
     44#endif /* HAVE_CONFIG_H */
     45
     46#endif /*__COINUTILSCONFIG_H__*/
     47}}}
     48The 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
     49{{{
     50AC_CONFIG_HEADER([inc/config.h inc/config_coinutils.h])
     51}}}
     52Further, 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
     53{{{
     54/* inc/config_coinutils.h.in.  */
     55
     56/* Version number of project */
     57#undef COINUTILS_VERSION
     58
     59/* Major Version number of project */
     60#undef COINUTILS_VERSION_MAJOR
     61
     62/* Minor Version number of project */
     63#undef COINUTILS_VERSION_MINOR
     64
     65/* Release Version number of project */
     66#undef COINUTILS_VERSION_RELEASE
     67
     68/* Define to 64bit integer type */
     69#undef COIN_INT64_T
     70
     71/* Define to integer type capturing pointer */
     72#undef COIN_INTPTR_T
     73
     74/* Define to 64bit unsigned integer type */
     75#undef COIN_UINT64_T
     76}}}
     77After a user run configure, the {{{#undef}}} statements are replaced by corresponding {{{#define}}} statements, depending on the outcome of tests performed by configure.
     78
     79For 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
     80{{{
     81/* Version number of project */
     82#define COINUTILS_VERSION  "trunk"
     83
     84/* Major Version number of project */
     85#define COINUTILS_VERSION_MAJOR   9999
     86
     87/* Minor Version number of project */
     88#define COINUTILS_VERSION_MINOR   9999
     89
     90/* Release Version number of project */
     91#define COINUTILS_VERSION_RELEASE 9999
     92
     93/*
     94  Define to 64bit integer types. Note that MS does not provide __uint64.
     95
     96  Microsoft defines types in BaseTsd.h, part of the Windows SDK. Given
     97  that this file only gets used in the Visual Studio environment, it
     98  seems to me we'll be better off simply including it and using the
     99  types MS defines. But since I have no idea of history here, I'll leave
     100  all of this inside the guard for MSC_VER >= 1200. If you're reading this
     101  and have been developing in MSVS long enough to know, fix it.  -- lh, 100915 --
     102*/
     103#if _MSC_VER >= 1200
     104# include <BaseTsd.h>
     105# define COIN_INT64_T INT64
     106# define COIN_UINT64_T UINT64
     107  /* Define to integer type capturing pointer */
     108# define COIN_INTPTR_T ULONG_PTR
     109#else
     110# define COIN_INT64_T long long
     111# define COIN_UINT64_T unsigned long long
     112# define COIN_INTPTR_T int*
     113#endif
     114}}}
     115and the private header file is {{{config_default.h}}} is
     116{{{
     117/* include the COIN-OR-wide system specific configure header */
     118#include "configall_system.h"
     119
     120/* include the public project specific macros */
     121#include "config_coinutils_default.h"
     122
     123/***************************************************************************/
     124/*             HERE DEFINE THE PROJECT SPECIFIC MACROS                     */
     125/*    These are only in effect in a setting that doesn't use configure     */
     126/***************************************************************************/
     127
     128/* Define to the debug sanity check level (0 is no test) */
     129#define COIN_COINUTILS_CHECKLEVEL 0
     130
     131/* Define to the debug verbosity level (0 is no output) */
     132#define COIN_COINUTILS_VERBOSITY 0
     133
     134/* Define to 1 if bzlib is available */
     135/* #define COIN_HAS_BZLIB */
     136
     137/* Define to 1 if zlib is available */
     138/* #define COIN_HAS_ZLIB */
     139
     140#ifdef _MSC_VER
     141/* Define to be the name of C-function for Inf check */
     142#define COIN_C_FINITE _finite
     143
     144/* Define to be the name of C-function for NaN check */
     145#define COIN_C_ISNAN _isnan
     146#endif
     147}}}
     148Since 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.