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


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

move info on config headers to separate page

Legend:

Unmodified
Added
Removed
Modified
  • pm-autotools-intro

    v18 v19  
    6767  * 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.
    6868
    69 The {{{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 
    71 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}}} 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 
    73 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.
    74 
    75 The 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}}}.
    76 It 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}}}.
    77 The distinction is made by two defines that may be specified as arguments in the compiler command line.
    78 These 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 
    80 As 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 }}}
    104 The 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 {{{
    106 AC_CONFIG_HEADER([inc/config.h inc/config_coinutils.h])
    107 }}}
    108 Further, 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 }}}
    133 After a user run configure, the {{{#undef}}} statements are replaced by corresponding {{{#define}}} statements, depending on the outcome of tests performed by configure.
    134 
    135 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
    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 }}}
    171 and 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 }}}
    204 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.
    205 
     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. Information on how this is handled within COIN-OR projects is given on [wiki:pm-config-header this page].
    20670
    20771== {{{automake}}} ==