configuring_boost.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

]]
[[`BOOST_DISABLE_ABI_HEADERS`][
Stops boost headers from including any prefix/suffix headers that normally
control things like struct packing and alignment.
]]
[[`BOOST_ABI_PREFIX`][
A prefix header to include in place of whatever boost.config would normally
select, any replacement should set up struct packing and alignment options
as required.
]]
[[`BOOST_ABI_SUFFIX` ][
A suffix header to include in place of whatever boost.config would normally
select, any replacement should undo the effects of the prefix header.
]]
[[`BOOST_ALL_DYN_LINK`][
Forces all libraries that have separate source, to be linked as dll's rather
than static libraries on Microsoft Windows (this macro is used to turn on
`__declspec(dllimport)` modifiers, so that the compiler knows which symbols
to look for in a dll rather than in a static library).
Note that there may be some libraries that can only be statically linked
(Boost.Test for example) and others which may only be dynamically linked
(Boost.Threads for example), in these cases this macro has no effect.
]]
[[`BOOST_`['WHATEVER]`_DYN_LINK`][
Forces library "whatever" to be linked as a dll rather than a static library
on Microsoft Windows: replace the ['WHATEVER] part of the macro name with the
name of the library that you want to dynamically link to, for example use
`BOOST_DATE_TIME_DYN_LINK` or `BOOST_REGEX_DYN_LINK` etc (this macro is used
to turn on `__declspec(dllimport)` modifiers, so that the compiler knows
which symbols to look for in a dll rather than in a static library).
Note that there may be some libraries that can only be statically linked
(Boost.Test for example) and others which may only be dynamically linked
(Boost.Threads for example), in these cases this macro is unsupported.
]]
[[`BOOST_ALL_NO_LIB`][
Tells the config system not to automatically select which libraries to link
against.
Normally if a compiler supports #pragma lib, then the correct library build
variant will be automatically selected and linked against, simply by the act
of including one of that library's headers. This macro turns that
feature off.
]]
[[`BOOST_`['WHATEVER]`_NO_LIB`][
Tells the config system not to automatically select which library to link
against for library "whatever", replace ['WHATEVER] in the macro name with the
name of the library; for example `BOOST_DATE_TIME_NO_LIB` or `BOOST_REGEX_NO_LIB`.
Normally if a compiler supports `#pragma lib`, then the correct library build
variant will be automatically selected and linked against, simply by the
act of including one of that library's headers.  This macro turns that
feature off.
]]
[[`BOOST_LIB_DIAGNOSTIC`][
Causes the auto-linking code to output diagnostic messages indicating the
name of the library that is selected for linking.
]]
[[`BOOST_LIB_TOOLSET`][
Overrides the name of the toolset part of the name of library being linked
to; note if defined this must be defined to a quoted string literal, for
example "abc".
]]
]

[endsect]

[section Advanced configuration usage]

By setting various macros on the compiler command line or by editing
__BOOST_CONFIG_USER_HEADER__, the boost configuration setup can be optimised
in a variety of ways.

Boost's configuration is structured so that the user-configuration is
included first (defaulting to __BOOST_CONFIG_USER_HEADER__ if `BOOST_USER_CONFIG`
is not defined). This sets up any user-defined policies, and gives the
user-configuration a chance to influence what happens next.

Next the compiler, standard library, and platform configuration files are
included. These are included via macros (`BOOST_COMPILER_CONFIG` etc,
[link config_user_settable see user settable macros]), and if the corresponding
macro is undefined then a separate header that detects which compiler/standard
library/platform is in use is included in order to set these. The config
can be told to ignore these headers altogether if the corresponding
`BOOST_NO_XXX` macro is set (for example `BOOST_NO_COMPILER_CONFIG` to
disable including any compiler configuration file -
[link config_user_settable see user settable macros]).

Finally the boost configuration header, includes __BOOST_CONFIG_SUFFIX_HEADER__;
this header contains any boiler plate configuration code - for example where one
boost macro being set implies that another must be set also.

The following usage examples represent just a few of the possibilities:

[section Example 1, creating our own frozen configuration]

Lets suppose that we're building boost with Visual C++ 6, and STLport 4.0. Lets
suppose also that we don't intend to update our compiler or standard library
any time soon. In order to avoid breaking dependencies when we update boost,
we may want to "freeze" our configuration headers, so that we only have to
rebuild our project if the boost code itself has changed, and not because the
boost config has been updated for more recent versions of Visual C++ or STLport.
We'll start by realising that the configuration files in use are:
[@../../../../boost/config/compiler/visualc.hpp `<boost/config/compiler/visualc.hpp>`]
for the compiler,
[@../../../../boost/config/stdlib/stlport.hpp `<boost/config/stdlib/stlport.hpp>`]
for the standard library, and
[@../../../../boost/config/platform/win32.hpp `<boost/config/platform/win32.hpp>`]
for the platform. Next we'll create our own private configuration directory:
`boost/config/mysetup/`, and copy the configuration files into there. Finally,
open up __BOOST_CONFIG_USER_HEADER__ and edit the following defines:

    #define BOOST_COMPILER_CONFIG "boost/config/mysetup/visualc.hpp"
    #define BOOST_STDLIB_CONFIG "boost/config/mysetup/stlport.hpp"
    #define BOOST_USER_CONFIG "boost/config/mysetup/win32.hpp"

Now when you use boost, its configuration header will go straight to our "frozen"
versions, and ignore the default versions, you will now be insulated from any
configuration changes when you update boost. This technique is also useful if
you want to modify some of the boost configuration files; for example if you are
working with a beta compiler release not yet supported by boost.

[endsect]

[section Example 2: skipping files that you don't need]

Lets suppose that you're using boost with a compiler that is fully conformant with
the standard; you're not interested in the fact that older versions of your compiler
may have had bugs, because you know that your current version does not need any
configuration macros setting. In a case like this, you can define
`BOOST_NO_COMPILER_CONFIG` either on the command line, or in __BOOST_CONFIG_USER_HEADER__,
and miss out the compiler configuration header altogether (actually you miss out
two headers, one which works out what the compiler is, and one that configures
boost for it). This has two consequences: the first is that less code has to be c
ompiled, and the second that you have removed a dependency on two boost headers.

[endsect]

[section Example 3: using configure script to freeze the boost configuration]

If you are working on a unix-like platform then you can use the configure script to
generate a "frozen" configuration based on your current compiler setup -
[link config_config_script see using the configure script for more details].

[endsect]

[endsect]

[section Testing the boost configuration]

The boost configuration library provides a full set of regression test programs
under the __BOOST_CONFIG_DIR__ `test/` sub-directory:


[table
[[File][Description]]
[[`config_info.cpp`][
Prints out a detailed description of your compiler/standard library/platform
setup, plus your current boost configuration. The information provided by this
program useful in setting up the boost configuration files. If you report that
boost is incorrectly configured for your compiler/library/platform then please
include the output from this program when reporting the changes required.
]]
[[`config_test.cpp`][
A monolithic test program that includes most of the individual test cases.
This provides a quick check to see if boost is correctly configured for your
compiler/library/platform.
]]
[[`limits_test.cpp`][
Tests your standard library's `std::numeric_limits` implementation (or its boost
provided replacement if `BOOST_NO_LIMITS` is defined). This test file fails with
most versions of numeric_limits, mainly due to the way that some compilers
treat NAN's and infinity.
]]
[[`no_*pass.cpp`][
Individual compiler defect test files. Each of these should compile, if one
does not then the corresponding `BOOST_NO_XXX` macro needs to be defined - see
each test file for specific details.
]]
[[`no_*fail.cpp`][
Individual compiler defect test files. Each of these should not compile, if
one does then the corresponding `BOOST_NO_XXX` macro is defined when it need
not be - see each test file for specific details.
]]
[[`has_*pass.cpp`][
Individual feature test files. If one of these does not compile then the
corresponding `BOOST_HAS_XXX` macro is defined when it should not be - see
each test file for specific details.
]]
[[`has_*fail.cpp`][
Individual feature test files. If one of these does compile then the
corresponding `BOOST_HAS_XXX` macro can be safely defined - see each test
file for specific details.
]]
]

Although you can run the configuration regression tests as individual test
files, there are rather a lot of them, so there are a couple of shortcuts to
help you out:

If you have built the __BOOST_REGRESSION_TEST_DRIVER__, then you can use this to
produce a nice html formatted report of the results using the supplied test file.

Alternatively you can run the configure script like this:

[: `./configure --enable-test`]

in which case the script will test the current configuration rather than
creating a new one from scratch.

If you are reporting the results of these tests for a new
platform/library/compiler then please include a log of the full compiler output,
the output from `config_info.cpp`, and the pass/fail test results.


[endsect]

[endsect]