]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |