Changes between Version 2 and Version 3 of pm-config-header


Ignore:
Timestamp:
May 31, 2011 9:28:32 AM (9 years ago)
Author:
tkr
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pm-config-header

    v2 v3  
    99== Private and public header files ==
    1010
    11 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.
     11Therefore, 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 ''Prjct''{{{Config.h}}}'''. It is important that the public header '''defines only symbols with unique names''', so conflicts from including several header files are avoided.
    1212
    1313== Header files for non-autotools setups ==
     
    1717== Bringing them all together ==
    1818
    19 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}}}.
    20 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}}}.
    21 The distinction is made by two defines that may be specified as arguments in the compiler command line.
    22 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.
     19The logic which of the four header files to include in which situation is implemented in a fifth header file ''Prjct''{{{Config.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 ''Prjct''{{{Config.h}}} should be include instead.
     20In an autotools build of the project itself, the file {{{config.h}}} will be included (through inclusion in ''Prjct''{{{Config.h}}}. When someone builds against the library exported by a project after it has been installed, then ''Prjct''{{{Config.h}}} will be a copy of the public header {{{config_}}}''prjct''{{{.h}}} and will be included instead. Further, in a non-autotools based setup, ''Prjct''{{{Config.h}}} will include either {{{config_default.h}}} or {{{config_}}}''prjct''{{{default.h}}} (as appropriate for internal building versus external linking).
     21The distinction is made by two defines that may be specified as arguments to the compiler command line to distinguish between building and linking.
     22In 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.
    2323
    2424== Example ==
    2525
    26 As an example, the {{{CoinUtilsConfig.h}}} contains
     26As an example, before installation, the {{{CoinUtilsConfig.h}}} contains
    2727{{{
    2828#ifndef __COINUTILSCONFIG_H__
     
    148148#endif
    149149}}}
    150 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.
     150Since 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.