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 17The __BOOST_CONFIG_HEADER__ header is used to pass configuration information 18to other boost files, allowing them to cope with platform dependencies such 19as arithmetic byte ordering, compiler pragmas, or compiler shortcomings. 20Without such configuration information, many current compilers would not work 21with the Boost libraries. 22 23Centralizing configuration information in this header reduces the number of 24files that must be modified when porting libraries to new platforms, or when 25compilers are updated. Ideally, no other files would have to be modified when 26porting to a new platform. 27 28Configuration headers are controversial because some view them as condoning 29broken compilers and encouraging non-standard subsets. Adding settings for 30additional platforms and maintaining existing settings can also be a problem. 31In other words, configuration headers are a necessary evil rather than a 32desirable feature. The boost config.hpp policy is designed to minimize the 33problems and maximize the benefits of a configuration header. 34 35Note that: 36 37* Boost library implementers are not required to "`#include <boost/config.hpp>`", 38and are not required in any way to support compilers that do not comply 39with the C++ Standard (ISO/IEC 14882). 40* If a library implementer wishes to support some non-conforming compiler, 41or to support some platform specific feature, "`#include <boost/config.hpp>`" 42is the preferred way to obtain configuration information not available from 43the 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 47sensible, standard conforming, default behavior if the macro is not defined. 48This means that the starting point for porting `<boost/config.hpp>` to a new 49platform is simply to define nothing at all specific to that platform. In 50the rare case where there is no sensible default behavior, an #error message 51should describe the problem. 52* If a Boost library implementer wants something added to `config.hpp`, post 53a request on the Boost mailing list. There is no guarantee such a request 54will 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 56becoming C++ Standard compliant, and only recent releases of those compilers 57at that. 58* The intent is not to disable mainstream features now well-supported by the 59majority of compilers, such as namespaces, exceptions, RTTI, or templates. 60 61 62[section:warnings Disabling Compiler Warnings] 63 64The header `<boost/config/warning_disable.hpp>` can be used to disable 65certain compiler warnings that are hard or impossible to otherwise remove. 66 67Note that: 68 69* This header [*['should never be included by another Boost header]], it should 70only 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 76Currently 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 90When you need to add a new defect macro - either to fix a problem with an 91existing library, or when adding a new library - distil the issue down to 92a simple test case; often, at this point other (possibly better) workarounds 93may become apparent. Secondly always post the test case code to the boost 94mailing list and invite comments; remember that C++ is complex and that 95sometimes what may appear a defect, may in fact turn out to be a problem 96with the authors understanding of the standard. 97 98When you name the macro, follow the `BOOST_NO_`['SOMETHING] naming 99convention, so that it's obvious that this is a macro reporting a defect. 100 101Finally, add the test program to the regression tests. You will need to 102place 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 108These comments are processed by the autoconf script, so make sure the format 109follows the one given. The file should be named "`boost_no_foo.ipp`", where foo 110is the defect description - try and keep the file name under the Mac 30 character 111filename 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, 113but 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 126Once the test code is in place in libs/config/test, updating the configuration 127test system proceeds as: 128 129* cd into `libs/config/tools` and run `bjam`. This generates the `.cpp` 130file test cases from the `.ipp` file, updates the 131libs/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 135compilers to test with.[br][br] 136The xxx_pass_test and the xxx_fail_test [*should both report `**passed**`].[br][br] 137If ['MACRONAME] is not defined when it should be defined, xxx_pass_test will not report `**passed**`. 138If ['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`] 142while `config_test` should fail for those that have the defect, and pass for those 143that do not. 144 145Then 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 151the addition. 152* Start using the macro. 153 154[endsect] 155 156[section Adding New Feature Test Macros] 157 158When you need to add a macro that describes a feature that the standard does 159not require, follow the convention for adding a new defect macro (above), but 160call the macro `BOOST_HAS_FOO`, and name the test file "`boost_has_foo.ipp`". 161Try not to add feature test macros unnecessarily, if there is a platform 162specific 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 164feature 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 166describes 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, 169remember that many of these features can be added by third party libraries, 170and are not therefore identified inside `<unistd.h>`). 171 172[endsect] 173 174[section Modifying the Boost Configuration Headers] 175 176The aim of boost's configuration setup is that the configuration headers should 177be relatively stable - a boost user should not have to recompile their code 178just because the configuration for some compiler that they're not interested 179in has changed. Separating the configuration into separate compiler/standard 180library/platform sections provides for part of this stability, but boost 181authors 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 186this 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 190modifying this file as it breaks dependencies for everyone. This file should 191include only "boilerplate" configuration code, and generally should change 192only when new macros are added. 193 194[@../../../../boost/config/detail/select_compiler_config.hpp <boost/config/detail/select_compiler_config.hpp>], 195[@../../../../boost/config/detail/select_platform_config.hpp <boost/config/detail/select_platform_config.hpp>] and 196[@../../../../boost/config/detail/select_stdlib_config.hpp <boost/config/detail/select_stdlib_config.hpp>] 197are included by default and should change only if support for a new 198compiler/standard library/platform is added. 199 200The compiler/platform/standard library selection code is set up so that unknown 201platforms are ignored and assumed to be fully standards compliant - this gives 202unknown platforms a "sporting chance" of working "as is" even without running 203the configure script. 204 205When adding or modifying the individual mini-configs, assume that future, as 206yet unreleased versions of compilers, have all the defects of the current 207version. Although this is perhaps unnecessarily pessimistic, it cuts down on 208the maintenance of these files, and experience suggests that pessimism is 209better placed than optimism here! 210 211[endsect] 212 213[endsect] 214 215 216 217 218 219 220