]>
Commit | Line | Data |
---|---|---|
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 | [section Configuring Boost for Your Platform] | |
15 | ||
16 | ||
17 | [section Using the default boost configuration] | |
18 | ||
19 | Boost comes already configured for most common compilers and platforms; you | |
20 | should be able to use boost "as is". Since the compiler is configured | |
21 | separately from the standard library, the default configuration should work | |
22 | even if you replace the compiler's standard library with a third-party | |
23 | standard library (like __STL_PORT__). | |
24 | ||
25 | Using boost "as is" without trying to reconfigure is the recommended method | |
26 | for using boost. You can, however, run the configure script if you want to, | |
27 | and there are regression tests provided that allow you to test the current | |
28 | boost configuration with your particular compiler setup. | |
29 | ||
30 | Boost library users can request support for additional compilers or platforms | |
31 | by visiting our __BOOST_TRACKER__ and submitting a support request. | |
32 | ||
33 | [endsect] | |
34 | ||
35 | [section The <boost/config.hpp> header] | |
36 | ||
37 | Boost library implementations access configuration macros via | |
38 | ||
39 | #include ``__BOOST_CONFIG_HEADER__`` | |
40 | ||
41 | While Boost library users are not required to include that file directly, or | |
42 | use those configuration macros, such use is acceptable. The configuration | |
43 | macros are documented as to their purpose, usage, and limitations which makes | |
44 | them usable by both Boost library and user code. | |
45 | ||
46 | Boost [link config_info_macros informational] or [link config_helpers helper] | |
47 | macros are designed for use by Boost users as well as for our own internal use. | |
48 | Note however, that the [link config_features feature test] and | |
49 | [link config_defects defect test] macros were designed for internal use by | |
50 | Boost libraries, not user code, so they can change at any time (though no | |
51 | gratuitous changes are made to them). Boost library problems resulting from | |
52 | changes to the configuration macros are caught by the Boost regression tests, | |
53 | so the Boost libraries are updated to account for those changes. By contrast, | |
54 | Boost library user code can be adversely affected by changes to the macros | |
55 | without warning. The best way to keep abreast of changes to the macros used in | |
56 | user code is to monitor the discussions on the Boost developers list. | |
57 | ||
58 | [endsect] | |
59 | ||
60 | [#config_config_script] | |
61 | ||
62 | [section Using the configure script] | |
63 | ||
64 | [important | |
65 | This configure script only sets up the Boost headers for use with a particular | |
66 | compiler. It has no effect on Boost.Build, or how the libraries are built. | |
67 | ] | |
68 | ||
69 | If you know that boost is incorrectly configured for your particular setup, and | |
70 | you are on a UNIX like platform, then you may want to try and improve things by | |
71 | running the boost configure script. From a shell command prompt you will need to | |
72 | cd into ['<boost-root>]`/libs/config/` and type: | |
73 | ||
74 | [: `sh ./configure` ] | |
75 | ||
76 | you will see a list of the items being checked as the script works its way | |
77 | through the regression tests. Note that the configure script only really | |
78 | auto-detects your compiler if it's called g++, c++ or CC. If you are using | |
79 | some other compiler you will need to set one or more of the following | |
80 | environment variables: | |
81 | ||
82 | ||
83 | [table | |
84 | [[Variable][Description ]] | |
85 | [[CXX ][The name of the compiler, for example `c++`. ]] | |
86 | [[CXXFLAGS][The compiler flags to use, for example `-O2`. ]] | |
87 | [[LDFLAGS ][The linker flags to use, for example `-L/mypath`. ]] | |
88 | [[LIBS ][Any libraries to link in, for example `-lpthread`.]] | |
89 | ] | |
90 | ||
91 | For example to run the configure script with HP aCC, you might use something | |
92 | like: | |
93 | ||
94 | export CXX="aCC" | |
95 | export CXXFLAGS="-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE \ | |
96 | -DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE" | |
97 | export LDFLAGS="-DAportable" | |
98 | export LIBS="-lpthread" | |
99 | sh ./configure | |
100 | ||
101 | However you run the configure script, when it finishes you will find a | |
102 | new header -`user.hpp`- located in the ['<boost-root>]`/libs/config/` | |
103 | directory. [*Note that configure does not install this header into your | |
104 | boost include path by default]. This header contains all the options | |
105 | generated by the configure script, plus a header-section that contains | |
106 | the user settable options from the default version of | |
107 | __BOOST_CONFIG_USER_HEADER__ (located under __BOOST_CONFIG_DIR__). | |
108 | There are two ways you can use this header: | |
109 | ||
110 | * [*Option 1:] copy the header into __BOOST_CONFIG_DIR__ so that it replaces | |
111 | the default user.hpp provided by boost. This option allows only one | |
112 | configure-generated setup; boost developers should avoid this option, | |
113 | as it incurs the danger of accidentally committing a configure-modified | |
114 | __BOOST_CONFIG_USER_HEADER__ to the svn repository (something you will not | |
115 | be thanked for!). | |
116 | ||
117 | * [*Option 2:] give the header a more memorable name, and place it somewhere | |
118 | convenient; then, define the macro `BOOST_USER_CONFIG` to point to it. For | |
119 | example create a new sub-directory __BOOST_CONFIG_DIR__ `user/`, and copy | |
120 | the header there; for example as `multithread-gcc-config.hpp`. Then, when | |
121 | compiling add the command line option: | |
122 | `-DBOOST_USER_CONFIG="<boost/config/user/multithread-gcc-config.hpp>"`, and | |
123 | boost will use the new configuration header. This option allows you to | |
124 | generate more than one configuration header, and to keep them separate | |
125 | from the boost source - so that updates to the source do not interfere | |
126 | with your configuration. | |
127 | ||
128 | [endsect] | |
129 | ||
130 | [#config_user_settable] | |
131 | ||
132 | [section User settable options] | |
133 | ||
134 | There are some configuration-options that represent user choices, rather | |
135 | than compiler defects or platform specific options. These are listed in | |
136 | `<boost/config/user.hpp>` and at the start of a configure-generated `user.hpp` | |
137 | header. You can define these on the command line, or by editing | |
138 | `<boost/config/user.hpp>`, they are listed in the following table: | |
139 | ||
140 | ||
141 | ||
142 | [table | |
143 | ||
144 | [[Macro ][Description ]] | |
145 | ||
146 | [[`BOOST_USER_CONFIG`][ | |
147 | When defined, it should point to the name of the user configuration file | |
148 | to include prior to any boost configuration files. When not defined, | |
149 | defaults to [@../../../../boost/config/user.hpp `<boost/config/user.hpp>`]. | |
150 | ]] | |
151 | [[`BOOST_COMPILER_CONFIG`][ | |
152 | When defined, it should point to the name of the compiler configuration | |
153 | file to use. Defining this cuts out the compiler selection logic, and | |
154 | eliminates the dependency on the header containing that logic. For | |
155 | example if you are using gcc, then you could define BOOST_COMPILER_CONFIG | |
156 | to [@../../../../boost/config/compiler/gcc.hpp `<boost/config/compiler/gcc.hpp>`]. | |
157 | ]] | |
158 | [[`BOOST_STDLIB_CONFIG`][ | |
159 | When defined, it should point to the name of the standard library | |
160 | configuration file to use. Defining this cuts out the standard library | |
161 | selection logic, and eliminates the dependency on the header containing | |
162 | that logic. For example if you are using STLport, then you could define | |
163 | `BOOST_STDLIB_CONFIG` to | |
164 | [@../../../../boost/config/stdlib/stlport.hpp `<boost/config/stdlib/stlport.hpp>`]. | |
165 | ]] | |
166 | [[`BOOST_PLATFORM_CONFIG`][ | |
167 | When defined, it should point to the name of the platform configuration | |
168 | file to use. Defining this cuts out the platform selection logic, and | |
169 | eliminates the dependency on the header containing that logic. For example | |
170 | if you are compiling on linux, then you could define `BOOST_PLATFORM_CONFIG` | |
171 | to [@../../../../boost/config/platform/linux.hpp `<boost/config/platform/linux.hpp>`]. | |
172 | ]] | |
173 | [[`BOOST_NO_COMPILER_CONFIG`][ | |
174 | When defined, no compiler configuration file is selected or included, | |
175 | define when the compiler is fully conformant with the standard, or where | |
176 | the user header (see `BOOST_USER_CONFIG`), has had any options necessary | |
177 | added to it, for example by an autoconf generated configure script. | |
178 | ]] | |
179 | [[`BOOST_NO_STDLIB_CONFIG` ][ | |
180 | When defined, no standard library configuration file is selected or included, | |
181 | define when the standard library is fully conformant with the standard, or | |
182 | where the user header (see `BOOST_USER_CONFIG`), has had any options necessary | |
183 | added to it, for example by an autoconf generated configure script. | |
184 | ]] | |
185 | [[`BOOST_NO_PLATFORM_CONFIG` ][ | |
186 | When defined, no platform configuration file is selected or included, | |
187 | define when the platform is fully conformant with the standard (and has | |
188 | no useful extra features), or where the user header (see | |
189 | `BOOST_USER_CONFIG`), has had any options necessary added to it, for example | |
190 | by an autoconf generated configure script. | |
191 | ]] | |
192 | [[`BOOST_NO_CONFIG` ][ | |
193 | Equivalent to defining all of `BOOST_NO_COMPILER_CONFIG`, | |
194 | `BOOST_NO_STDLIB_CONFIG` and `BOOST_NO_PLATFORM_CONFIG`. | |
195 | ]] | |
196 | [[`BOOST_STRICT_CONFIG` ][ | |
197 | The normal behavior for compiler versions that are newer than the last | |
198 | known version, is to assume that they have all the same defects as the | |
199 | last known version. By setting this define, then compiler versions that | |
200 | are newer than the last known version are assumed to be fully conforming | |
201 | with the standard. This is probably most useful for boost developers or | |
202 | testers, and for those who want to use boost to test beta compiler versions. | |
203 | ]] | |
204 | [[`BOOST_ASSERT_CONFIG` ][ | |
205 | When this flag is set, if the config finds anything unknown, then it will | |
206 | stop with a #error rather than continue. Boost regression testers should | |
207 | set this define, as should anyone who wants to quickly check whether boost | |
208 | is supported on their platform. | |
209 | ]] | |
210 | [[`BOOST_DISABLE_THREADS` ][ | |
211 | When defined, disables threading support, even if the compiler in its | |
212 | current translation mode supports multiple threads. | |
213 | ]] | |
214 | [[`BOOST_DISABLE_WIN32` ][ | |
215 | When defined, disables the use of Win32 specific API's, even when these | |
216 | are available. Also has the effect of setting `BOOST_DISABLE_THREADS` unless | |
217 | `BOOST_HAS_PTHREADS` is set. This option may be set automatically by the | |
218 | config system when it detects that the compiler is in "strict mode". | |
219 | ]] | |
220 | [[`BOOST_DISABLE_ABI_HEADERS`][ | |
221 | Stops boost headers from including any prefix/suffix headers that normally | |
222 | control things like struct packing and alignment. | |
223 | ]] | |
224 | [[`BOOST_ABI_PREFIX`][ | |
225 | A prefix header to include in place of whatever boost.config would normally | |
226 | select, any replacement should set up struct packing and alignment options | |
227 | as required. | |
228 | ]] | |
229 | [[`BOOST_ABI_SUFFIX` ][ | |
230 | A suffix header to include in place of whatever boost.config would normally | |
231 | select, any replacement should undo the effects of the prefix header. | |
232 | ]] | |
233 | [[`BOOST_ALL_DYN_LINK`][ | |
234 | Forces all libraries that have separate source, to be linked as dll's rather | |
235 | than static libraries on Microsoft Windows (this macro is used to turn on | |
236 | `__declspec(dllimport)` modifiers, so that the compiler knows which symbols | |
237 | to look for in a dll rather than in a static library). | |
238 | Note that there may be some libraries that can only be statically linked | |
239 | (Boost.Test for example) and others which may only be dynamically linked | |
240 | (Boost.Thread for example), in these cases this macro has no effect. | |
241 | ]] | |
242 | [[`BOOST_`['WHATEVER]`_DYN_LINK`][ | |
243 | Forces library "whatever" to be linked as a dll rather than a static library | |
244 | on Microsoft Windows: replace the ['WHATEVER] part of the macro name with the | |
245 | name of the library that you want to dynamically link to, for example use | |
246 | `BOOST_DATE_TIME_DYN_LINK` or `BOOST_REGEX_DYN_LINK` etc (this macro is used | |
247 | to turn on `__declspec(dllimport)` modifiers, so that the compiler knows | |
248 | which symbols to look for in a dll rather than in a static library). | |
249 | Note that there may be some libraries that can only be statically linked | |
250 | (Boost.Test for example) and others which may only be dynamically linked | |
251 | (Boost.Thread for example), in these cases this macro is unsupported. | |
252 | ]] | |
253 | [[`BOOST_ALL_NO_LIB`][ | |
254 | Tells the config system not to automatically select which libraries to link | |
255 | against. | |
256 | Normally if a compiler supports #pragma lib, then the correct library build | |
257 | variant will be automatically selected and linked against, simply by the act | |
258 | of including one of that library's headers. This macro turns that | |
259 | feature off. | |
260 | ]] | |
261 | [[`BOOST_`['WHATEVER]`_NO_LIB`][ | |
262 | Tells the config system not to automatically select which library to link | |
263 | against for library "whatever", replace ['WHATEVER] in the macro name with the | |
264 | name of the library; for example `BOOST_DATE_TIME_NO_LIB` or `BOOST_REGEX_NO_LIB`. | |
265 | Normally if a compiler supports `#pragma lib`, then the correct library build | |
266 | variant will be automatically selected and linked against, simply by the | |
267 | act of including one of that library's headers. This macro turns that | |
268 | feature off. | |
269 | ]] | |
270 | [[`BOOST_LIB_DIAGNOSTIC`][ | |
271 | Causes the auto-linking code to output diagnostic messages indicating the | |
272 | name of the library that is selected for linking. | |
273 | ]] | |
274 | [[`BOOST_LIB_BUILDID`][ | |
275 | If you built Boost using the `--buildid` option then set this macro to the same value | |
276 | as you passed to bjam. For example if you built using `bjam address-model=64 --buildid=amd64` | |
277 | then compile your code with `-DBOOST_LIB_BUILDID=amd64` to ensure the correct libraries | |
278 | are selected at link time. | |
279 | ]] | |
280 | [[`BOOST_LIB_TOOLSET`][ | |
281 | Overrides the name of the toolset part of the name of library being linked | |
282 | to; note if defined this must be defined to a quoted string literal, for | |
283 | example "abc". | |
284 | ]] | |
285 | ] | |
286 | ||
287 | [endsect] | |
288 | ||
289 | [section Advanced configuration usage] | |
290 | ||
291 | By setting various macros on the compiler command line or by editing | |
292 | __BOOST_CONFIG_USER_HEADER__, the boost configuration setup can be optimised | |
293 | in a variety of ways. | |
294 | ||
295 | Boost's configuration is structured so that the user-configuration is | |
296 | included first (defaulting to __BOOST_CONFIG_USER_HEADER__ if `BOOST_USER_CONFIG` | |
297 | is not defined). This sets up any user-defined policies, and gives the | |
298 | user-configuration a chance to influence what happens next. | |
299 | ||
300 | Next the compiler, standard library, and platform configuration files are | |
301 | included. These are included via macros (`BOOST_COMPILER_CONFIG` etc, | |
302 | [link config_user_settable see user settable macros]), and if the corresponding | |
303 | macro is undefined then a separate header that detects which compiler/standard | |
304 | library/platform is in use is included in order to set these. The config | |
305 | can be told to ignore these headers altogether if the corresponding | |
306 | `BOOST_NO_XXX` macro is set (for example `BOOST_NO_COMPILER_CONFIG` to | |
307 | disable including any compiler configuration file - | |
308 | [link config_user_settable see user settable macros]). | |
309 | ||
310 | Finally the boost configuration header, includes __BOOST_CONFIG_SUFFIX_HEADER__; | |
311 | this header contains any boiler plate configuration code - for example where one | |
312 | boost macro being set implies that another must be set also. | |
313 | ||
314 | The following usage examples represent just a few of the possibilities: | |
315 | ||
316 | [section Example 1: creating our own frozen configuration] | |
317 | ||
318 | Lets suppose that we're building boost with Visual C++ 6, and STLport 4.0. Lets | |
319 | suppose also that we don't intend to update our compiler or standard library | |
320 | any time soon. In order to avoid breaking dependencies when we update boost, | |
321 | we may want to "freeze" our configuration headers, so that we only have to | |
322 | rebuild our project if the boost code itself has changed, and not because the | |
323 | boost config has been updated for more recent versions of Visual C++ or STLport. | |
324 | We'll start by realising that the configuration files in use are: | |
325 | [@../../../../boost/config/compiler/visualc.hpp `<boost/config/compiler/visualc.hpp>`] | |
326 | for the compiler, | |
327 | [@../../../../boost/config/stdlib/stlport.hpp `<boost/config/stdlib/stlport.hpp>`] | |
328 | for the standard library, and | |
329 | [@../../../../boost/config/platform/win32.hpp `<boost/config/platform/win32.hpp>`] | |
330 | for the platform. Next we'll create our own private configuration directory: | |
331 | `boost/config/mysetup/`, and copy the configuration files into there. Finally, | |
332 | open up __BOOST_CONFIG_USER_HEADER__ and edit the following defines: | |
333 | ||
334 | #define BOOST_COMPILER_CONFIG "boost/config/mysetup/visualc.hpp" | |
335 | #define BOOST_STDLIB_CONFIG "boost/config/mysetup/stlport.hpp" | |
336 | #define BOOST_USER_CONFIG "boost/config/mysetup/win32.hpp" | |
337 | ||
338 | Now when you use boost, its configuration header will go straight to our "frozen" | |
339 | versions, and ignore the default versions, you will now be insulated from any | |
340 | configuration changes when you update boost. This technique is also useful if | |
341 | you want to modify some of the boost configuration files; for example if you are | |
342 | working with a beta compiler release not yet supported by boost. | |
343 | ||
344 | [endsect] | |
345 | ||
346 | [section Example 2: skipping files that you don't need] | |
347 | ||
348 | Lets suppose that you're using boost with a compiler that is fully conformant with | |
349 | the standard; you're not interested in the fact that older versions of your compiler | |
350 | may have had bugs, because you know that your current version does not need any | |
351 | configuration macros setting. In a case like this, you can define | |
352 | `BOOST_NO_COMPILER_CONFIG` either on the command line, or in __BOOST_CONFIG_USER_HEADER__, | |
353 | and miss out the compiler configuration header altogether (actually you miss out | |
354 | two headers, one which works out what the compiler is, and one that configures | |
355 | boost for it). This has two consequences: the first is that less code has to be | |
356 | compiled, and the second that you have removed a dependency on two boost headers. | |
357 | ||
358 | [endsect] | |
359 | ||
360 | [section Example 3: using configure script to freeze the boost configuration] | |
361 | ||
362 | If you are working on a unix-like platform then you can use the configure script to | |
363 | generate a "frozen" configuration based on your current compiler setup - | |
364 | [link config_config_script see using the configure script for more details]. | |
365 | ||
366 | [endsect] | |
367 | ||
368 | [endsect] | |
369 | ||
370 | [section Testing the boost configuration] | |
371 | ||
372 | The boost configuration library provides a full set of regression test programs | |
373 | under the __BOOST_CONFIG_DIR__ `test/` sub-directory: | |
374 | ||
375 | ||
376 | [table | |
377 | [[File][Description]] | |
378 | [[`config_info.cpp`][ | |
379 | Prints out a detailed description of your compiler/standard library/platform | |
380 | setup, plus your current boost configuration. The information provided by this | |
381 | program is useful in setting up the boost configuration files. If you report that | |
382 | boost is incorrectly configured for your compiler/library/platform then please | |
383 | include the output from this program when reporting the changes required. | |
384 | ]] | |
385 | [[`config_test.cpp`][ | |
386 | A monolithic test program that includes most of the individual test cases. | |
387 | This provides a quick check to see if boost is correctly configured for your | |
388 | compiler/library/platform. | |
389 | ]] | |
390 | [[`limits_test.cpp`][ | |
391 | Tests your standard library's `std::numeric_limits` implementation (or its boost | |
392 | provided replacement if `BOOST_NO_LIMITS` is defined). This test file fails with | |
393 | most versions of numeric_limits, mainly due to the way that some compilers | |
394 | treat NAN's and infinity. | |
395 | ]] | |
396 | [[`no_*pass.cpp`][ | |
397 | Individual compiler defect test files. Each of these should compile, if one | |
398 | does not then the corresponding `BOOST_NO_XXX` macro needs to be defined - see | |
399 | each test file for specific details. | |
400 | ]] | |
401 | [[`no_*fail.cpp`][ | |
402 | Individual compiler defect test files. Each of these should not compile, if | |
403 | one does then the corresponding `BOOST_NO_XXX` macro is defined when it need | |
404 | not be - see each test file for specific details. | |
405 | ]] | |
406 | [[`has_*pass.cpp`][ | |
407 | Individual feature test files. If one of these does not compile then the | |
408 | corresponding `BOOST_HAS_XXX` macro is defined when it should not be - see | |
409 | each test file for specific details. | |
410 | ]] | |
411 | [[`has_*fail.cpp`][ | |
412 | Individual feature test files. If one of these does compile then the | |
413 | corresponding `BOOST_HAS_XXX` macro can be safely defined - see each test | |
414 | file for specific details. | |
415 | ]] | |
416 | ] | |
417 | ||
418 | Although you can run the configuration regression tests as individual test | |
419 | files, there are rather a lot of them, so there are a couple of shortcuts to | |
420 | help you out: | |
421 | ||
422 | If you have built the __BOOST_REGRESSION_TEST_DRIVER__, then you can use this to | |
423 | produce a nice html formatted report of the results using the supplied test file. | |
424 | ||
425 | Alternatively you can run the configure script like this: | |
426 | ||
427 | [: `./configure --enable-test`] | |
428 | ||
429 | in which case the script will test the current configuration rather than | |
430 | creating a new one from scratch. | |
431 | ||
432 | If you are reporting the results of these tests for a new | |
433 | platform/library/compiler then please include a log of the full compiler output, | |
434 | the output from `config_info.cpp`, and the pass/fail test results. | |
435 | ||
436 | ||
437 | [endsect] | |
438 | ||
439 | [endsect] | |
440 |