ceph/src/boost/libs/config/doc/guidelines.qbk

   1 [/
   2     Boost.Config
   3
   4     Copyright (c) 2001 Beman Dawes
   5     Copyright (c) 2001 Vesa Karvonen
   6     Copyright (c) 2001 John Maddock
   7
   8     Distributed under the Boost Software License, Version 1.0.
   9     (See accompanying file LICENSE_1_0.txt or copy at
  10     http://www.boost.org/LICENSE_1_0.txt)
  11 ]
  12
  13
  14
  15 [section Guidelines for Boost Authors]
  16
  17 The __BOOST_CONFIG_HEADER__ header is used to pass configuration information
  18 to other boost files, allowing them to cope with platform dependencies such
  19 as arithmetic byte ordering, compiler pragmas, or compiler shortcomings.
  20 Without such configuration information, many current compilers would not work
  21 with the Boost libraries.
  22
  23 Centralizing configuration information in this header reduces the number of
  24 files that must be modified when porting libraries to new platforms, or when
  25 compilers are updated. Ideally, no other files would have to be modified when
  26 porting to a new platform.
  27
  28 Configuration headers are controversial because some view them as condoning
  29 broken compilers and encouraging non-standard subsets. Adding settings for
  30 additional platforms and maintaining existing settings can also be a problem.
  31 In other words, configuration headers are a necessary evil rather than a
  32 desirable feature. The boost config.hpp policy is designed to minimize the
  33 problems and maximize the benefits of a configuration header.
  34
  35 Note that:
  36
  37 * Boost library implementers are not required to "`#include <boost/config.hpp>`",
  38 and are not required in any way to support compilers that do not comply
  39 with the C++ Standard (ISO/IEC 14882).
  40 * If a library implementer wishes to support some non-conforming compiler,
  41 or to support some platform specific feature, "`#include <boost/config.hpp>`"
  42 is the preferred way to obtain configuration information not available from
  43 the standard headers such as `<climits>`, etc.
  44 * If configuration information can be deduced from standard headers such as
  45 `<climits>`, use those standard headers rather than `<boost/config.hpp>`.
  46 * Boost files that use macros defined in `<boost/config.hpp>` should have
  47 sensible, standard conforming, default behavior if the macro is not defined.
  48 This means that the starting point for porting `<boost/config.hpp>` to a new
  49 platform is simply to define nothing at all specific to that platform. In
  50 the rare case where there is no sensible default behavior, an #error message
  51 should describe the problem.
  52 * If a Boost library implementer wants something added to `config.hpp`, post
  53 a request on the Boost mailing list. There is no guarantee such a request
  54 will be honored; the intent is to limit the complexity of config.hpp.
  55 * The intent is to support only compilers which appear on their way to
  56 becoming C++ Standard compliant, and only recent releases of those compilers
  57 at that.
  58 * The intent is not to disable mainstream features now well-supported by the
  59 majority of compilers, such as namespaces, exceptions, RTTI, or templates.
  60
  61
  62 [section:warnings Disabling Compiler Warnings]
  63
  64 The header `<boost/config/warning_disable.hpp>` can be used to disable
  65 certain compiler warnings that are hard or impossible to otherwise remove.
  66
  67 Note that:
  68
  69 * This header [*['should never be included by another Boost header]], it should
  70 only ever be used by a library source file or a test case.
  71 * The header should be included [*['before you include any other header]].
  72 * This header only disables warnings that are hard or impossible to otherwise
  73  deal with, and which are typically emitted by one compiler only, or
  74  in one compilers own standard library headers.
  75
  76 Currently it disables the following warnings:
  77
  78 [table
  79 [[Compiler][Warning]]
  80 [[Visual C++ 8 and later][[@http://msdn2.microsoft.com/en-us/library/ttcz0bys(VS.80).aspx C4996]: Error 'function': was declared deprecated]]
  81 [[Intel C++][Warning 1786: relates to the use of "deprecated" standard
  82    library functions rather like C4996 in Visual C++.]]
  83 ]
  84
  85 [endsect]
  86
  87
  88 [section Adding New Defect Macros]
  89
  90 When you need to add a new defect macro - either to fix a problem with an
  91 existing library, or when adding a new library - distil the issue down to
  92 a simple test case; often, at this point other (possibly better) workarounds
  93 may become apparent. Secondly always post the test case code to the boost
  94 mailing list and invite comments; remember that C++ is complex and that
  95 sometimes what may appear a defect, may in fact turn out to be a problem
  96 with the authors understanding of the standard.
  97
  98 When you name the macro, follow the `BOOST_NO_`['SOMETHING] naming
  99 convention, so that it's obvious that this is a macro reporting a defect.
 100
 101 Finally, add the test program to the regression tests. You will need to
 102 place the test case in a `.ipp` file with the following comments near the top:
 103
 104     //  MACRO:         BOOST_NO_FOO
 105     //  TITLE:         foo
 106     //  DESCRIPTION:   If the compiler fails to support foo
 107
 108 These comments are processed by the autoconf script, so make sure the format
 109 follows the one given. The file should be named "`boost_no_foo.ipp`", where foo
 110 is the defect description - try and keep the file name under the Mac 30 character
 111 filename limit though. You will also need to provide a function prototype
 112 "`int test()`" that is declared in a namespace with the same name as the macro,
 113 but in all lower case, and which returns zero on success:
 114
 115
 116     namespace boost_no_foo {
 117     int test()
 118     {
 119         // test code goes here:
 120         //
 121         return 0;
 122     }
 123
 124     }
 125
 126 Once the test code is in place in libs/config/test, updating the configuration
 127 test system proceeds as:
 128
 129 * cd into `libs/config/tools` and run `bjam`. This generates the `.cpp`
 130 file test cases from the `.ipp` file, updates the
 131 libs/config/test/all/Jamfile.v2, `config_test.cpp` and `config_info.cpp`.[br][br]
 132
 133 * cd into `libs/config/test/all` and run `bjam `['MACRONAME` compiler-list`], where
 134 ['MACRONAME] is the name of the new macro, and ['`compiler-list`] is a space separated list of
 135 compilers to test with.[br][br]
 136 The xxx_pass_test and the xxx_fail_test [*should both report `**passed**`].[br][br]
 137 If ['MACRONAME] is not defined when it should be defined, xxx_pass_test will not report `**passed**`.
 138 If ['MACRONAME] is defined when it should not be defined, xxx_fail_test will not report `**passed**`.[br][br]
 139
 140 * cd into `libs/config/test` and run `bjam config_info config_test `['`compiler-list`].
 141 `config_info` should build and run cleanly for all the compilers in ['`compiler-list`]
 142 while `config_test` should fail for those that have the defect, and pass for those
 143 that do not.
 144
 145 Then you should:
 146
 147 * Define the defect macro in those config headers that require it.
 148 * Document the macro in this documentation (please do not forget this step!!)
 149 * Commit everything.
 150 * Keep an eye on the regression tests for new failures in Boost.Config caused by
 151 the addition.
 152 * Start using the macro.
 153
 154 [endsect]
 155
 156 [section Adding New Feature Test Macros]
 157
 158 When you need to add a macro that describes a feature that the standard does
 159 not require, follow the convention for adding a new defect macro (above), but
 160 call the macro `BOOST_HAS_FOO`, and name the test file "`boost_has_foo.ipp`".
 161 Try not to add feature test macros unnecessarily, if there is a platform
 162 specific macro that can already be used (for example `_WIN32`, `__BEOS__`, or
 163 `__linux`) to identify the feature then use that. Try to keep the macro to a
 164 feature group, or header name, rather than one specific API (for example
 165 `BOOST_HAS_NL_TYPES_H` rather than `BOOST_HAS_CATOPEN`). If the macro
 166 describes a POSIX feature group, then add boilerplate code to
 167 __BOOST_CONFIG_SUFFIX_HEADER__ to auto-detect the feature where possible
 168 (if you are wondering why we can't use POSIX feature test macro directly,
 169 remember that many of these features can be added by third party libraries,
 170 and are not therefore identified inside `<unistd.h>`).
 171
 172 [endsect]
 173
 174 [section Modifying the Boost Configuration Headers]
 175
 176 The aim of boost's configuration setup is that the configuration headers should
 177 be relatively stable - a boost user should not have to recompile their code
 178 just because the configuration for some compiler that they're not interested
 179 in has changed. Separating the configuration into separate compiler/standard
 180 library/platform sections provides for part of this stability, but boost
 181 authors require some amount of restraint as well, in particular:
 182
 183 __BOOST_CONFIG_HEADER__ should never change, don't alter this file.
 184
 185 __BOOST_CONFIG_USER_HEADER__ is included by default, don't add extra code to
 186 this file unless you have to. If you do, please remember to update
 187 [@../../tools/configure.in libs/config/tools/configure.in] as well.
 188
 189 __BOOST_CONFIG_SUFFIX_HEADER__ is always included so be careful about
 190 modifying this file as it breaks dependencies for everyone. This file should
 191 include only "boilerplate" configuration code, and generally should change
 192 only when new macros are added.
 193
 194 [@../../../../boost/config/select_compiler_config.hpp <boost/config/select_compiler_config.hpp>],
 195 [@../../../../boost/config/select_platform_config.hpp <boost/config/select_platform_config.hpp>] and
 196 [@../../../../boost/config/select_stdlib_config.hpp <boost/config/select_stdlib_config.hpp>]
 197 are included by default and should change only if support for a new
 198 compiler/standard library/platform is added.
 199
 200 The compiler/platform/standard library selection code is set up so that unknown
 201 platforms are ignored and assumed to be fully standards compliant - this gives
 202 unknown platforms a "sporting chance" of working "as is" even without running
 203 the configure script.
 204
 205 When adding or modifying the individual mini-configs, assume that future, as
 206 yet unreleased versions of compilers, have all the defects of the current
 207 version. Although this is perhaps unnecessarily pessimistic, it cuts down on
 208 the maintenance of these files, and experience suggests that pessimism is
 209 better placed than optimism here!
 210
 211 [endsect]
 212
 213 [endsect]
 214
 215
 216
 217
 218
 219