mirror of
https://github.com/boostorg/config.git
synced 2025-07-29 20:07:17 +02:00
quickbook config docs
[SVN r37818]
This commit is contained in:
Matias Capeletto
30
doc/Jamfile.v2
Normal file
30
doc/Jamfile.v2
Normal file
@ -0,0 +1,30 @@
|
||||
# Boost.Config
|
||||
#
|
||||
# Copyright (c) 2001 Beman Dawes
|
||||
# Copyright (c) 2001 Vesa Karvonen
|
||||
# Copyright (c) 2001 John Maddock
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0.
|
||||
# (See accompanying file LICENSE_1_0.txt or copy at
|
||||
# http://www.boost.org/LICENSE_1_0.txt)
|
||||
|
||||
|
||||
# Quickbook
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
import quickbook ;
|
||||
|
||||
xml config
|
||||
:
|
||||
config.qbk
|
||||
;
|
||||
|
||||
boostbook standalone
|
||||
:
|
||||
config
|
||||
:
|
||||
<xsl:param>toc.max.depth=2
|
||||
<xsl:param>toc.section.depth=2
|
||||
<xsl:param>chunk.section.depth=1
|
||||
;
|
||||
|
||||
29
doc/acknowledgements.qbk
Normal file
29
doc/acknowledgements.qbk
Normal file
@ -0,0 +1,29 @@
|
||||
[/
|
||||
Boost.Config
|
||||
|
||||
Copyright (c) 2001 Beman Dawes
|
||||
Copyright (c) 2001 Vesa Karvonen
|
||||
Copyright (c) 2001 John Maddock
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
[section Acknowledgements]
|
||||
|
||||
Beman Dawes provided the original `config.hpp` and part of this document.
|
||||
|
||||
Vesa Karvonen provided a description of the principles (see
|
||||
[link config_rationale rationale]) and put together an early version of
|
||||
the current configuration setup.
|
||||
|
||||
John Maddock put together the configuration current code, the test
|
||||
programs, the configuration script and the reference section of this
|
||||
document.
|
||||
|
||||
Numerous boost members, past and present, have contributed fixes to boost's
|
||||
configuration.
|
||||
|
||||
[endsect]
|
||||
|
||||
57
doc/config.qbk
Normal file
57
doc/config.qbk
Normal file
@ -0,0 +1,57 @@
|
||||
[library Boost.Config
|
||||
[quickbook 1.4]
|
||||
[authors [Beman Dawes, Vesa Karvonen, John Maddock] ]
|
||||
[copyright 2001-2007 Beman Dawes, Vesa Karvonen, John Maddock]
|
||||
[category broken compiler workarounds]
|
||||
[id config]
|
||||
[dirname config]
|
||||
[purpose
|
||||
Helps boost library developers adapt to compiler idiosyncrasies; not intended for library users.
|
||||
]
|
||||
[source-mode c++]
|
||||
[license
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
[@http://www.boost.org/LICENSE_1_0.txt])
|
||||
]
|
||||
]
|
||||
|
||||
|
||||
[/ Cited Boost resources ]
|
||||
|
||||
[def __BOOST_REGRESSION_TEST_DRIVER__ [@../../../../more/regression.html boost regression test driver]]
|
||||
[def __BOOST_CONFIG_HEADER__ [@../../../../boost/config.hpp <boost/config.hpp>]]
|
||||
[def __BOOST_CONFIG_USER_HEADER__ [@../../../../boost/config/user.hpp <boost/config/user.hpp>]]
|
||||
[def __BOOST_CONFIG_SUFFIX_HEADER__ [@../../../../boost/config/user.hpp <boost/config/suffix.hpp>]]
|
||||
[def __BOOST_CONFIG_DIR__ ['<boost-root>]`/boost/config/`]
|
||||
|
||||
|
||||
[/ Other web resources ]
|
||||
|
||||
[def __STL_PORT__ [@http://stlport.sourceforge.net STLport]]
|
||||
[def __BOOST_TRACKER__ [@http://sourceforge.net/tracker/?group_id=7586 Tracker]]
|
||||
[def __CORE_LANGUAGE_DR337__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#337 Core Language DR337]]
|
||||
[def __PRINCIPLES_AND_PATTERNS_ARTICLE__ [@http://www.objectmentor.com/resources/articles/ocp.pdf following article]]
|
||||
|
||||
|
||||
[/ Icons ]
|
||||
|
||||
[def __NOTE__ [$images/note.png]]
|
||||
[def __ALERT__ [$images/caution.png]]
|
||||
[def __DETAIL__ [$images/note.png]]
|
||||
[def __TIP__ [$images/tip.png]]
|
||||
[def __QUESTION_MARK__ [$images/question.png]]
|
||||
[def __SPACE__ [$images/space.png]]
|
||||
[def __GO_TO__ [$images/callouts/R.png]]
|
||||
|
||||
|
||||
[/ Document files ]
|
||||
|
||||
|
||||
[include configuring_boost.qbk]
|
||||
[include macro_reference.qbk]
|
||||
[include guidelines.qbk]
|
||||
[include rationale.qbk]
|
||||
[include acknowledgements.qbk]
|
||||
|
||||
|
||||
434
doc/configuring_boost.qbk
Normal file
434
doc/configuring_boost.qbk
Normal file
@ -0,0 +1,434 @@
|
||||
[/
|
||||
Boost.Config
|
||||
|
||||
Copyright (c) 2001 Beman Dawes
|
||||
Copyright (c) 2001 Vesa Karvonen
|
||||
Copyright (c) 2001 John Maddock
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
[section Configuring Boost for Your Platform]
|
||||
|
||||
|
||||
[section Using the default boost configuration]
|
||||
|
||||
Boost comes already configured for most common compilers and platforms; you
|
||||
should be able to use boost "as is". Since the compiler is configured
|
||||
separately from the standard library, the default configuration should work
|
||||
even if you replace the compiler's standard library with a third-party
|
||||
standard library (like __STL_PORT__).
|
||||
|
||||
Using boost "as is" without trying to reconfigure is the recommended method
|
||||
for using boost. You can, however, run the configure script if you want to,
|
||||
and there are regression tests provided that allow you to test the current
|
||||
boost configuration with your particular compiler setup.
|
||||
|
||||
Boost library users can request support for additional compilers or platforms
|
||||
by visiting our __BOOST_TRACKER__ and submitting a support request.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section The <boost/config.hpp> header]
|
||||
|
||||
Boost library implementations access configuration macros via
|
||||
|
||||
#include ``__BOOST_CONFIG_HEADER__``
|
||||
|
||||
While Boost library users are not required to include that file directly, or
|
||||
use those configuration macros, such use is acceptable. The configuration
|
||||
macros are documented as to their purpose, usage, and limitations which makes
|
||||
them usable by both Boost library and user code.
|
||||
|
||||
Boost [link config_info_macros informational] or [link config_helpers helper]
|
||||
macros are designed for use by Boost users as well as for our own internal use.
|
||||
Note however, that the [link config_features feature test] and
|
||||
[link config_defects defect test] macros were designed for internal use by
|
||||
Boost libraries, not user code, so they can change at any time (though no
|
||||
gratuitous changes are made to them). Boost library problems resulting from
|
||||
changes to the configuration macros are caught by the Boost regression tests,
|
||||
so the Boost libraries are updated to account for those changes. By contrast,
|
||||
Boost library user code can be adversely affected by changes to the macros
|
||||
without warning. The best way to keep abreast of changes to the macros used in
|
||||
user code is to monitor the discussions on the Boost developers list.
|
||||
|
||||
[endsect]
|
||||
|
||||
[#config_config_script]
|
||||
|
||||
[section Using the configure script]
|
||||
|
||||
[note
|
||||
This configure script only sets up the Boost headers for use with a particular
|
||||
compiler. It has no effect on Boost.Build, or how the libraries are built.
|
||||
]
|
||||
|
||||
If you know that boost is incorrectly configured for your particular setup, and
|
||||
you are on a UNIX like platform, then you may want to try and improve things by
|
||||
running the boost configure script. From a shell command prompt you will need to
|
||||
cd into ['<boost-root>]`/libs/config/` and type:
|
||||
|
||||
[: `sh ./configure` ]
|
||||
|
||||
you will see a list of the items being checked as the script works its way
|
||||
through the regression tests. Note that the configure script only really
|
||||
auto-detects your compiler if it's called g++, c++ or CC. If you are using
|
||||
some other compiler you will need to set one or more of the following
|
||||
environment variables:
|
||||
|
||||
|
||||
[table
|
||||
[[Variable][Description ]]
|
||||
[[CXX ][The name of the compiler, for example `c++`. ]]
|
||||
[[CXXFLAGS][The compiler flags to use, for example `-O2`. ]]
|
||||
[[LDFLAGS ][The linker flags to use, for example `-L/mypath`. ]]
|
||||
[[LIBS ][Any libraries to link in, for example `-lpthread`.]]
|
||||
]
|
||||
|
||||
For example to run the configure script with HP aCC, you might use something
|
||||
like:
|
||||
|
||||
export CXX="aCC"
|
||||
export CXXFLAGS="-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE \
|
||||
-DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE"
|
||||
export LDFLAGS="-DAportable"
|
||||
export LIBS="-lpthread"
|
||||
sh ./configure
|
||||
|
||||
However you run the configure script, when it finishes you will find a
|
||||
new header -`user.hpp`- located in the ['<boost-root>]`/libs/config/`
|
||||
directory. [*Note that configure does not install this header into your
|
||||
boost include path by default]. This header contains all the options
|
||||
generated by the configure script, plus a header-section that contains
|
||||
the user settable options from the default version of
|
||||
__BOOST_CONFIG_USER_HEADER__ (located under __BOOST_CONFIG_DIR__).
|
||||
There are two ways you can use this header:
|
||||
|
||||
* [*Option 1:] copy the header into __BOOST_CONFIG_DIR__ so that it replaces
|
||||
the default user.hpp provided by boost. This option allows only one
|
||||
configure-generated setup; boost developers should avoid this option,
|
||||
as it incurs the danger of accidentally committing a configure-modified
|
||||
__BOOST_CONFIG_USER_HEADER__ to the cvs repository (something you will not
|
||||
be thanked for!).
|
||||
|
||||
* [*Option 2:] give the header a more memorable name, and place it somewhere
|
||||
convenient; then, define the macro `BOOST_USER_CONFIG` to point to it. For
|
||||
example create a new sub-directory __BOOST_CONFIG_DIR__ `user/`, and copy
|
||||
the header there; for example as `multithread-gcc-config.hpp`. Then, when
|
||||
compiling add the command line option:
|
||||
`-DBOOST_USER_CONFIG="<boost/config/user/multithread-gcc-config.hpp>"`, and
|
||||
boost will use the new configuration header. This option allows you to
|
||||
generate more than one configuration header, and to keep them separate
|
||||
from the boost source - so that updates to the source do not interfere
|
||||
with your configuration.
|
||||
|
||||
[endsect]
|
||||
|
||||
[#config_user_settable]
|
||||
|
||||
[section User settable options]
|
||||
|
||||
There are some configuration-options that represent user choices, rather
|
||||
than compiler defects or platform specific options. These are listed in
|
||||
`<boost/config/user.hpp>` and at the start of a configure-generated `user.hpp`
|
||||
header. You can define these on the command line, or by editing
|
||||
`<boost/config/user.hpp>`, they are listed in the following table:
|
||||
|
||||
|
||||
|
||||
[table
|
||||
|
||||
[[Macro ][Description ]]
|
||||
|
||||
[[`BOOST_USER_CONFIG`][
|
||||
When defined, it should point to the name of the user configuration file
|
||||
to include prior to any boost configuration files. When not defined,
|
||||
defaults to [@../../../../boost/config/user.hpp `<boost/config/user.hpp>`].
|
||||
]]
|
||||
[[`BOOST_COMPILER_CONFIG`][
|
||||
When defined, it should point to the name of the compiler configuration
|
||||
file to use. Defining this cuts out the compiler selection logic, and
|
||||
eliminates the dependency on the header containing that logic. For
|
||||
example if you are using gcc, then you could define BOOST_COMPILER_CONFIG
|
||||
to [@../../../../boost/config/compiler/gcc.hpp `<boost/config/compiler/gcc.hpp>`].
|
||||
]]
|
||||
[[`BOOST_STDLIB_CONFIG`][
|
||||
When defined, it should point to the name of the standard library
|
||||
configuration file to use. Defining this cuts out the standard library
|
||||
selection logic, and eliminates the dependency on the header containing
|
||||
that logic. For example if you are using STLport, then you could define
|
||||
`BOOST_STDLIB_CONFIG` to
|
||||
[@../../../../boost/config/stdlib/stlport.hpp `<boost/config/stdlib/stlport.hpp>`].
|
||||
]]
|
||||
[[`BOOST_PLATFORM_CONFIG`][
|
||||
When defined, it should point to the name of the platform configuration
|
||||
file to use. Defining this cuts out the platform selection logic, and
|
||||
eliminates the dependency on the header containing that logic. For example
|
||||
if you are compiling on linux, then you could define `BOOST_PLATFORM_CONFIG`
|
||||
to [@../../../../boost/config/platform/linux.hpp `<boost/config/platform/linux.hpp>`].
|
||||
]]
|
||||
[[`BOOST_NO_COMPILER_CONFIG`][
|
||||
When defined, no compiler configuration file is selected or included,
|
||||
define when the compiler is fully conformant with the standard, or where
|
||||
the user header (see `BOOST_USER_CONFIG`), has had any options necessary
|
||||
added to it, for example by an autoconf generated configure script.
|
||||
]]
|
||||
[[`BOOST_NO_STDLIB_CONFIG` ][
|
||||
When defined, no standard library configuration file is selected or included,
|
||||
define when the standard library is fully conformant with the standard, or
|
||||
where the user header (see `BOOST_USER_CONFIG`), has had any options necessary
|
||||
added to it, for example by an autoconf generated configure script.
|
||||
]]
|
||||
[[`BOOST_NO_PLATFORM_CONFIG` ][
|
||||
When defined, no platform configuration file is selected or included,
|
||||
define when the platform is fully conformant with the standard (and has
|
||||
no useful extra features), or where the user header (see
|
||||
`BOOST_USER_CONFIG`), has had any options necessary added to it, for example
|
||||
by an autoconf generated configure script.
|
||||
]]
|
||||
[[`BOOST_NO_CONFIG` ][
|
||||
Equivalent to defining all of `BOOST_NO_COMPILER_CONFIG`,
|
||||
`BOOST_NO_STDLIB_CONFIG` and `BOOST_NO_PLATFORM_CONFIG`.
|
||||
]]
|
||||
[[`BOOST_STRICT_CONFIG` ][
|
||||
The normal behavior for compiler versions that are newer than the last
|
||||
known version, is to assume that they have all the same defects as the
|
||||
last known version. By setting this define, then compiler versions that
|
||||
are newer than the last known version are assumed to be fully conforming
|
||||
with the standard. This is probably most useful for boost developers or
|
||||
testers, and for those who want to use boost to test beta compiler versions.
|
||||
]]
|
||||
[[`BOOST_ASSERT_CONFIG` ][
|
||||
When this flag is set, if the config finds anything unknown, then it will
|
||||
stop with a #error rather than continue. Boost regression testers should
|
||||
set this define, as should anyone who wants to quickly check whether boost
|
||||
is supported on their platform.
|
||||
]]
|
||||
[[`BOOST_DISABLE_THREADS` ][
|
||||
When defined, disables threading support, even if the compiler in its
|
||||
current translation mode supports multiple threads.
|
||||
]]
|
||||
[[`BOOST_DISABLE_WIN32` ][
|
||||
When defined, disables the use of Win32 specific API's, even when these
|
||||
are available. Also has the effect of setting `BOOST_DISABLE_THREADS` unless
|
||||
`BOOST_HAS_PTHREADS` is set. This option may be set automatically by the
|
||||
config system when it detects that the compiler is in "strict mode".
|
||||
]]
|
||||
[[`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]
|
||||
|
||||
189
doc/guidelines.qbk
Normal file
189
doc/guidelines.qbk
Normal file
@ -0,0 +1,189 @@
|
||||
[/
|
||||
Boost.Config
|
||||
|
||||
Copyright (c) 2001 Beman Dawes
|
||||
Copyright (c) 2001 Vesa Karvonen
|
||||
Copyright (c) 2001 John Maddock
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
|
||||
[section Guidelines for Boost Authors]
|
||||
|
||||
The __BOOST_CONFIG_HEADER__ header is used to pass configuration information
|
||||
to other boost files, allowing them to cope with platform dependencies such
|
||||
as arithmetic byte ordering, compiler pragmas, or compiler shortcomings.
|
||||
Without such configuration information, many current compilers would not work
|
||||
with the Boost libraries.
|
||||
|
||||
Centralizing configuration information in this header reduces the number of
|
||||
files that must be modified when porting libraries to new platforms, or when
|
||||
compilers are updated. Ideally, no other files would have to be modified when
|
||||
porting to a new platform.
|
||||
|
||||
Configuration headers are controversial because some view them as condoning
|
||||
broken compilers and encouraging non-standard subsets. Adding settings for
|
||||
additional platforms and maintaining existing settings can also be a problem.
|
||||
In other words, configuration headers are a necessary evil rather than a
|
||||
desirable feature. The boost config.hpp policy is designed to minimize the
|
||||
problems and maximize the benefits of a configuration header.
|
||||
|
||||
Note that:
|
||||
|
||||
* Boost library implementers are not required to "`#include <boost/config.hpp>`",
|
||||
and are not required in any way to support compilers that do not comply
|
||||
with the C++ Standard (ISO/IEC 14882).
|
||||
* If a library implementer wishes to support some non-conforming compiler,
|
||||
or to support some platform specific feature, "`#include <boost/config.hpp>`"
|
||||
is the preferred way to obtain configuration information not available from
|
||||
the standard headers such as `<climits>`, etc.
|
||||
* If configuration information can be deduced from standard headers such as
|
||||
`<climits>`, use those standard headers rather than `<boost/config.hpp>`.
|
||||
* Boost files that use macros defined in `<boost/config.hpp>` should have
|
||||
sensible, standard conforming, default behavior if the macro is not defined.
|
||||
This means that the starting point for porting `<boost/config.hpp>` to a new
|
||||
platform is simply to define nothing at all specific to that platform. In
|
||||
the rare case where there is no sensible default behavior, an #error message
|
||||
should describe the problem.
|
||||
* If a Boost library implementer wants something added to `config.hpp`, post
|
||||
a request on the Boost mailing list. There is no guarantee such a request
|
||||
will be honored; the intent is to limit the complexity of config.hpp.
|
||||
* The intent is to support only compilers which appear on their way to
|
||||
becoming C++ Standard compliant, and only recent releases of those compilers
|
||||
at that.
|
||||
* The intent is not to disable mainstream features now well-supported by the
|
||||
majority of compilers, such as namespaces, exceptions, RTTI, or templates.
|
||||
|
||||
|
||||
[section Adding New Defect Macros]
|
||||
|
||||
When you need to add a new defect macro -either to fix a problem with an
|
||||
existing library, or when adding a new library- distil the issue down to
|
||||
a simple test case; often, at this point other (possibly better) workarounds
|
||||
may become apparent. Secondly always post the test case code to the boost
|
||||
mailing list and invite comments; remember that C++ is complex and that
|
||||
sometimes what may appear a defect, may in fact turn out to be a problem
|
||||
with the authors understanding of the standard.
|
||||
|
||||
When you name the macro, follow the `BOOST_NO_`['SOMETHING] naming
|
||||
convention, so that it's obvious that this is a macro reporting a defect.
|
||||
|
||||
Finally, add the test program to the regression tests. You will need to
|
||||
place the test case in a `.ipp` file with the following comments near the top:
|
||||
|
||||
// MACRO: BOOST_NO_FOO
|
||||
// TITLE: foo
|
||||
// DESCRIPTION: If the compiler fails to support foo
|
||||
|
||||
These comments are processed by the autoconf script, so make sure the format
|
||||
follows the one given. The file should be named "`boost_no_foo.ipp`", where foo
|
||||
is the defect description -try and keep the file name under the Mac 30 character
|
||||
filename limit though. You will also need to provide a function prototype
|
||||
"`int test()`" that is declared in a namespace with the same name as the macro,
|
||||
but in all lower case, and which returns zero on success:
|
||||
|
||||
namespace boost_no_foo {
|
||||
|
||||
int test()
|
||||
{
|
||||
// test code goes here:
|
||||
//
|
||||
return 0;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
Once the test code is in place in libs/config/test, updating the configuration
|
||||
test system proceeds as:
|
||||
|
||||
* cd into `libs/config/tools` and run `bjam --v2` : this generates the `.cpp`
|
||||
file test cases from the `.ipp` file, updates the Jamfile, `config_test.cpp` and
|
||||
`config_info.cpp`.
|
||||
* cd into `libs/config/test` and run `bjam --v2 `['MACRONAME]` compiler-list` : where
|
||||
['MACRONAME] is the name of the new macro, and `compiler-list` is the list of
|
||||
compilers to test with. You should see the tests pass with those compilers
|
||||
that don't have the defect, and fail with those that do.
|
||||
* cd into `libs/config/test` and `run bjam --v2 config_info config_test compiler-list` :
|
||||
`config_info` should build and run cleanly for all the compilers in `compiler-list`
|
||||
while `config_test` should fail for those that have the defect, and pass for those
|
||||
that do not.
|
||||
|
||||
Then you should:
|
||||
|
||||
* Define the defect macro in those config headers that require it.
|
||||
* Document the macro in this documentation (please do not forget this step!!)
|
||||
* Commit everything.
|
||||
* Keep an eye on the regression tests for new failures in Boost.Config caused by
|
||||
the addition.
|
||||
* Start using the macro.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Adding New Feature Test Macros]
|
||||
|
||||
When you need to add a macro that describes a feature that the standard does
|
||||
not require, follow the convention for adding a new defect macro (above), but
|
||||
call the macro `BOOST_HAS_FOO`, and name the test file "`boost_has_foo.ipp`".
|
||||
Try not to add feature test macros unnecessarily, if there is a platform
|
||||
specific macro that can already be used (for example `_WIN32`, `__BEOS__`, or
|
||||
`__linux`) to identify the feature then use that. Try to keep the macro to a
|
||||
feature group, or header name, rather than one specific API (for example
|
||||
`BOOST_HAS_NL_TYPES_H` rather than `BOOST_HAS_CATOPEN`). If the macro
|
||||
describes a POSIX feature group, then add boilerplate code to
|
||||
__BOOST_CONFIG_SUFFIX_HEADER__ to auto-detect the feature where possible
|
||||
(if you are wondering why we can't use POSIX feature test macro directly,
|
||||
remember that many of these features can be added by third party libraries,
|
||||
and are not therefore identified inside `<unistd.h>`).
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Modifying the Boost Configuration Headers]
|
||||
|
||||
The aim of boost's configuration setup is that the configuration headers should
|
||||
be relatively stable - a boost user should not have to recompile their code
|
||||
just because the configuration for some compiler that they're not interested
|
||||
in has changed. Separating the configuration into separate compiler/standard
|
||||
library/platform sections provides for part of this stability, but boost
|
||||
authors require some amount of restraint as well, in particular:
|
||||
|
||||
__BOOST_CONFIG_HEADER__ should never change, don't alter this file.
|
||||
|
||||
__BOOST_CONFIG_USER_HEADER__ is included by default, don't add extra code to
|
||||
this file unless you have to. If you do, please remember to update
|
||||
[@../../tools/configure.in libs/config/tools/configure.in] as well.
|
||||
|
||||
__BOOST_CONFIG_SUFFIX_HEADER__ is always included so be careful about
|
||||
modifying this file as it breaks dependencies for everyone. This file should
|
||||
include only "boilerplate" configuration code, and generally should change
|
||||
only when new macros are added.
|
||||
|
||||
[@../../../../boost/config/select_compiler_config.hpp <boost/config/select_compiler_config.hpp>],
|
||||
[@../../../../boost/config/select_platform_config.hpp <boost/config/select_platform_config.hpp>] and
|
||||
[@../../../../boost/config/select_stdlib_config.hpp <boost/config/select_stdlib_config.hpp>]
|
||||
are included by default and should change only if support for a new
|
||||
compiler/standard library/platform is added.
|
||||
|
||||
The compiler/platform/standard library selection code is set up so that unknown
|
||||
platforms are ignored and assumed to be fully standards compliant -this gives
|
||||
unknown platforms a "sporting chance" of working "as is" even without running
|
||||
the configure script.
|
||||
|
||||
When adding or modifying the individual mini-configs, assume that future, as
|
||||
yet unreleased versions of compilers, have all the defects of the current
|
||||
version. Although this is perhaps unnecessarily pessimistic, it cuts down on
|
||||
the maintenance of these files, and experience suggests that pessimism is
|
||||
better placed than optimism here!
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
5
doc/html/HTML.manifest
Normal file
5
doc/html/HTML.manifest
Normal file
@ -0,0 +1,5 @@
|
||||
index.html
|
||||
boost_config/boost_macro_reference.html
|
||||
boost_config/guidelines_for_boost_authors.html
|
||||
boost_config/rationale.html
|
||||
boost_config/acknowledgements.html
|
||||
54
doc/html/boost_config/acknowledgements.html
Normal file
54
doc/html/boost_config/acknowledgements.html
Normal file
@ -0,0 +1,54 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Acknowledgements</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Config">
|
||||
<link rel="prev" href="rationale.html" title="Rationale">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rationale.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.acknowledgements"></a><a href="acknowledgements.html" title="Acknowledgements">Acknowledgements</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
Beman Dawes provided the original <code class="computeroutput"><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code> and
|
||||
part of this document.
|
||||
</p>
|
||||
<p>
|
||||
Vesa Karvonen provided a description of the principles (see <a href="../index.html#config_rationale">rationale</a>)
|
||||
and put together an early version of the current configuration setup.
|
||||
</p>
|
||||
<p>
|
||||
John Maddock put together the configuration current code, the test programs,
|
||||
the configuration script and the reference section of this document.
|
||||
</p>
|
||||
<p>
|
||||
Numerous boost members, past and present, have contributed fixes to boost's
|
||||
configuration.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rationale.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
2803
doc/html/boost_config/boost_macro_reference.html
Normal file
2803
doc/html/boost_config/boost_macro_reference.html
Normal file
File diff suppressed because it is too large
Load Diff
295
doc/html/boost_config/guidelines_for_boost_authors.html
Normal file
295
doc/html/boost_config/guidelines_for_boost_authors.html
Normal file
@ -0,0 +1,295 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Guidelines for
|
||||
Boost Authors</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Config">
|
||||
<link rel="prev" href="boost_macro_reference.html" title="Boost Macro Reference">
|
||||
<link rel="next" href="rationale.html" title="Rationale">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="boost_macro_reference.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.guidelines_for_boost_authors"></a><a href="guidelines_for_boost_authors.html" title="Guidelines for
|
||||
Boost Authors">Guidelines for
|
||||
Boost Authors</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
|
||||
New Defect Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
|
||||
New Feature Test Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
|
||||
the Boost Configuration Headers</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
The <a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
header is used to pass configuration information to other boost files, allowing
|
||||
them to cope with platform dependencies such as arithmetic byte ordering, compiler
|
||||
pragmas, or compiler shortcomings. Without such configuration information,
|
||||
many current compilers would not work with the Boost libraries.
|
||||
</p>
|
||||
<p>
|
||||
Centralizing configuration information in this header reduces the number of
|
||||
files that must be modified when porting libraries to new platforms, or when
|
||||
compilers are updated. Ideally, no other files would have to be modified when
|
||||
porting to a new platform.
|
||||
</p>
|
||||
<p>
|
||||
Configuration headers are controversial because some view them as condoning
|
||||
broken compilers and encouraging non-standard subsets. Adding settings for
|
||||
additional platforms and maintaining existing settings can also be a problem.
|
||||
In other words, configuration headers are a necessary evil rather than a desirable
|
||||
feature. The boost config.hpp policy is designed to minimize the problems and
|
||||
maximize the benefits of a configuration header.
|
||||
</p>
|
||||
<p>
|
||||
Note that:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
Boost library implementers are not required to "<code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>",
|
||||
and are not required in any way to support compilers that do not comply with
|
||||
the C++ Standard (ISO/IEC 14882).
|
||||
</li>
|
||||
<li>
|
||||
If a library implementer wishes to support some non-conforming compiler,
|
||||
or to support some platform specific feature, "<code class="computeroutput"><span class="preprocessor">#include</span>
|
||||
<span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>"
|
||||
is the preferred way to obtain configuration information not available from
|
||||
the standard headers such as <code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>,
|
||||
etc.
|
||||
</li>
|
||||
<li>
|
||||
If configuration information can be deduced from standard headers such as
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">climits</span><span class="special">></span></code>, use those standard headers rather than
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>.
|
||||
</li>
|
||||
<li>
|
||||
Boost files that use macros defined in <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
should have sensible, standard conforming, default behavior if the macro
|
||||
is not defined. This means that the starting point for porting <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
to a new platform is simply to define nothing at all specific to that platform.
|
||||
In the rare case where there is no sensible default behavior, an #error message
|
||||
should describe the problem.
|
||||
</li>
|
||||
<li>
|
||||
If a Boost library implementer wants something added to <code class="computeroutput"><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code>, post
|
||||
a request on the Boost mailing list. There is no guarantee such a request
|
||||
will be honored; the intent is to limit the complexity of config.hpp.
|
||||
</li>
|
||||
<li>
|
||||
The intent is to support only compilers which appear on their way to becoming
|
||||
C++ Standard compliant, and only recent releases of those compilers at that.
|
||||
</li>
|
||||
<li>
|
||||
The intent is not to disable mainstream features now well-supported by the
|
||||
majority of compilers, such as namespaces, exceptions, RTTI, or templates.
|
||||
</li>
|
||||
</ul></div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.adding_new_defect_macros"></a><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros" title="Adding
|
||||
New Defect Macros">Adding
|
||||
New Defect Macros</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
When you need to add a new defect macro -either to fix a problem with an
|
||||
existing library, or when adding a new library- distil the issue down to
|
||||
a simple test case; often, at this point other (possibly better) workarounds
|
||||
may become apparent. Secondly always post the test case code to the boost
|
||||
mailing list and invite comments; remember that C++ is complex and that sometimes
|
||||
what may appear a defect, may in fact turn out to be a problem with the authors
|
||||
understanding of the standard.
|
||||
</p>
|
||||
<p>
|
||||
When you name the macro, follow the <code class="computeroutput"><span class="identifier">BOOST_NO_</span></code><span class="emphasis"><em>SOMETHING</em></span>
|
||||
naming convention, so that it's obvious that this is a macro reporting a
|
||||
defect.
|
||||
</p>
|
||||
<p>
|
||||
Finally, add the test program to the regression tests. You will need to place
|
||||
the test case in a <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code>
|
||||
file with the following comments near the top:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="comment">// MACRO: BOOST_NO_FOO
|
||||
</span><span class="comment">// TITLE: foo
|
||||
</span><span class="comment">// DESCRIPTION: If the compiler fails to support foo
|
||||
</span></pre>
|
||||
<p>
|
||||
These comments are processed by the autoconf script, so make sure the format
|
||||
follows the one given. The file should be named "<code class="computeroutput"><span class="identifier">boost_no_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>",
|
||||
where foo is the defect description -try and keep the file name under the
|
||||
Mac 30 character filename limit though. You will also need to provide a function
|
||||
prototype "<code class="computeroutput"><span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span></code>" that is declared in a namespace with
|
||||
the same name as the macro, but in all lower case, and which returns zero
|
||||
on success:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">namespace</span> <span class="identifier">boost_no_foo</span> <span class="special">{</span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">test</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// test code goes here:
|
||||
</span> <span class="comment">//
|
||||
</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Once the test code is in place in libs/config/test, updating the configuration
|
||||
test system proceeds as:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">tools</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
|
||||
<span class="special">--</span><span class="identifier">v2</span></code>
|
||||
: this generates the <code class="computeroutput"><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
file test cases from the <code class="computeroutput"><span class="special">.</span><span class="identifier">ipp</span></code> file, updates the Jamfile, <code class="computeroutput"><span class="identifier">config_test</span><span class="special">.</span><span class="identifier">cpp</span></code> and <code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>.
|
||||
</li>
|
||||
<li>
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span></code> and run <code class="computeroutput"><span class="identifier">bjam</span>
|
||||
<span class="special">--</span><span class="identifier">v2</span>
|
||||
</code><span class="emphasis"><em>MACRONAME</em></span><code class="computeroutput"> <span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code>
|
||||
: where <span class="emphasis"><em>MACRONAME</em></span> is the name of the new macro, and
|
||||
<code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code> is the list of compilers to test
|
||||
with. You should see the tests pass with those compilers that don't have
|
||||
the defect, and fail with those that do.
|
||||
</li>
|
||||
<li>
|
||||
cd into <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">test</span></code> and <code class="computeroutput"><span class="identifier">run</span>
|
||||
<span class="identifier">bjam</span> <span class="special">--</span><span class="identifier">v2</span> <span class="identifier">config_info</span>
|
||||
<span class="identifier">config_test</span> <span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code>
|
||||
: <code class="computeroutput"><span class="identifier">config_info</span></code> should build
|
||||
and run cleanly for all the compilers in <code class="computeroutput"><span class="identifier">compiler</span><span class="special">-</span><span class="identifier">list</span></code>
|
||||
while <code class="computeroutput"><span class="identifier">config_test</span></code> should
|
||||
fail for those that have the defect, and pass for those that do not.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Then you should:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
Define the defect macro in those config headers that require it.
|
||||
</li>
|
||||
<li>
|
||||
Document the macro in this documentation (please do not forget this step!!)
|
||||
</li>
|
||||
<li>
|
||||
Commit everything.
|
||||
</li>
|
||||
<li>
|
||||
Keep an eye on the regression tests for new failures in Boost.Config caused
|
||||
by the addition.
|
||||
</li>
|
||||
<li>
|
||||
Start using the macro.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros"></a><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros" title="Adding
|
||||
New Feature Test Macros">Adding
|
||||
New Feature Test Macros</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
When you need to add a macro that describes a feature that the standard does
|
||||
not require, follow the convention for adding a new defect macro (above),
|
||||
but call the macro <code class="computeroutput"><span class="identifier">BOOST_HAS_FOO</span></code>,
|
||||
and name the test file "<code class="computeroutput"><span class="identifier">boost_has_foo</span><span class="special">.</span><span class="identifier">ipp</span></code>".
|
||||
Try not to add feature test macros unnecessarily, if there is a platform
|
||||
specific macro that can already be used (for example <code class="computeroutput"><span class="identifier">_WIN32</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">__BEOS__</span></code>, or <code class="computeroutput"><span class="identifier">__linux</span></code>) to identify the feature then use
|
||||
that. Try to keep the macro to a feature group, or header name, rather than
|
||||
one specific API (for example <code class="computeroutput"><span class="identifier">BOOST_HAS_NL_TYPES_H</span></code>
|
||||
rather than <code class="computeroutput"><span class="identifier">BOOST_HAS_CATOPEN</span></code>).
|
||||
If the macro describes a POSIX feature group, then add boilerplate code to
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>
|
||||
to auto-detect the feature where possible (if you are wondering why we can't
|
||||
use POSIX feature test macro directly, remember that many of these features
|
||||
can be added by third party libraries, and are not therefore identified inside
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">unistd</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code>).
|
||||
</p>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers"></a><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers" title="Modifying
|
||||
the Boost Configuration Headers">Modifying
|
||||
the Boost Configuration Headers</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The aim of boost's configuration setup is that the configuration headers
|
||||
should be relatively stable - a boost user should not have to recompile their
|
||||
code just because the configuration for some compiler that they're not interested
|
||||
in has changed. Separating the configuration into separate compiler/standard
|
||||
library/platform sections provides for part of this stability, but boost
|
||||
authors require some amount of restraint as well, in particular:
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
should never change, don't alter this file.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
is included by default, don't add extra code to this file unless you have
|
||||
to. If you do, please remember to update <a href="../../../tools/configure.in" target="_top">libs/config/tools/configure.in</a>
|
||||
as well.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>
|
||||
is always included so be careful about modifying this file as it breaks dependencies
|
||||
for everyone. This file should include only "boilerplate" configuration
|
||||
code, and generally should change only when new macros are added.
|
||||
</p>
|
||||
<p>
|
||||
<a href="../../../../../boost/config/select_compiler_config.hpp" target="_top"><boost/config/select_compiler_config.hpp></a>,
|
||||
<a href="../../../../../boost/config/select_platform_config.hpp" target="_top"><boost/config/select_platform_config.hpp></a>
|
||||
and <a href="../../../../../boost/config/select_stdlib_config.hpp" target="_top"><boost/config/select_stdlib_config.hpp></a>
|
||||
are included by default and should change only if support for a new compiler/standard
|
||||
library/platform is added.
|
||||
</p>
|
||||
<p>
|
||||
The compiler/platform/standard library selection code is set up so that unknown
|
||||
platforms are ignored and assumed to be fully standards compliant -this gives
|
||||
unknown platforms a "sporting chance" of working "as is"
|
||||
even without running the configure script.
|
||||
</p>
|
||||
<p>
|
||||
When adding or modifying the individual mini-configs, assume that future,
|
||||
as yet unreleased versions of compilers, have all the defects of the current
|
||||
version. Although this is perhaps unnecessarily pessimistic, it cuts down
|
||||
on the maintenance of these files, and experience suggests that pessimism
|
||||
is better placed than optimism here!
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="boost_macro_reference.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
132
doc/html/boost_config/rationale.html
Normal file
132
doc/html/boost_config/rationale.html
Normal file
@ -0,0 +1,132 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Rationale</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Config">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Config">
|
||||
<link rel="prev" href="guidelines_for_boost_authors.html" title="Guidelines for
|
||||
Boost Authors">
|
||||
<link rel="next" href="acknowledgements.html" title="Acknowledgements">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="guidelines_for_boost_authors.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.rationale"></a><a href="rationale.html" title="Rationale">Rationale</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="rationale.html#boost_config.rationale.the_problem">The problem</a></span></dt>
|
||||
<dt><span class="section"><a href="rationale.html#boost_config.rationale.the_solution">The solution</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
The problem with many traditional "textbook" implementations of configuration
|
||||
headers (where all the configuration options are in a single "monolithic"
|
||||
header) is that they violate certain fundamental software engineering principles
|
||||
which would have the effect of making boost more fragile, more difficult to
|
||||
maintain and more difficult to use safely. You can find a description of the
|
||||
principles from the <a href="http://www.objectmentor.com/resources/articles/ocp.pdf" target="_top">following
|
||||
article</a>.
|
||||
</p>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.rationale.the_problem"></a><a href="rationale.html#boost_config.rationale.the_problem" title="The problem">The problem</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Consider a situation in which you are concurrently developing on multiple
|
||||
platforms. Then consider adding a new platform or changing the platform definitions
|
||||
of an existing platform. What happens? Everything, and this does literally
|
||||
mean everything, recompiles. Isn't it quite absurd that adding a new platform,
|
||||
which has absolutely nothing to do with previously existing platforms, means
|
||||
that all code on all existing platforms needs to be recompiled?
|
||||
</p>
|
||||
<p>
|
||||
Effectively, there is an imposed physical dependency between platforms that
|
||||
have nothing to do with each other. Essentially, the traditional solution
|
||||
employed by configuration headers does not conform to the Open-Closed Principle:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote">
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
<span class="bold"><strong>"A module should be open for extension but
|
||||
closed for modification."</strong></span>
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
</blockquote></div>
|
||||
<p>
|
||||
Extending a traditional configuration header implies modifying existing code.
|
||||
</p>
|
||||
<p>
|
||||
Furthermore, consider the complexity and fragility of the platform detection
|
||||
code. What if a simple change breaks the detection on some minor platform?
|
||||
What if someone accidentally or on purpose (as a workaround for some other
|
||||
problem) defines some platform dependent macros that are used by the detection
|
||||
code? A traditional configuration header is one of the most volatile headers
|
||||
of the entire library, and more stable elements of Boost would depend on
|
||||
it. This violates the Stable Dependencies Principle:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote">
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
<span class="bold"><strong>"Depend in the direction of stability."</strong></span>
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
</blockquote></div>
|
||||
<p>
|
||||
After even a minor change to a traditional configuration header on one minor
|
||||
platform, almost everything on every platform should be tested if we follow
|
||||
sound software engineering practice.
|
||||
</p>
|
||||
<p>
|
||||
Another important issue is that it is not always possible to submit changes
|
||||
to <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>.
|
||||
Some boost users are currently working on platforms using tools and libraries
|
||||
that are under strict Non-Disclosure Agreements. In this situation it is
|
||||
impossible to submit changes to a traditional monolithic configuration header,
|
||||
instead some method by which the user can insert their own configuration
|
||||
code must be provided.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.rationale.the_solution"></a><a href="rationale.html#boost_config.rationale.the_solution" title="The solution">The solution</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The approach taken by boost's configuration headers is to separate configuration
|
||||
into three orthogonal parts: the compiler, the standard library and the platform.
|
||||
Each compiler/standard library/platform gets its own mini-configuration header,
|
||||
so that changes to one compiler's configuration (for example) does not affect
|
||||
other compilers. In addition there are measures that can be taken both to
|
||||
omit the compiler/standard library/platform detection code (so that adding
|
||||
support to a new platform does not break dependencies), or to freeze the
|
||||
configuration completely; providing almost complete protection against dependency
|
||||
changes.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="guidelines_for_boost_authors.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgements.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
582
doc/html/boostbook.css
Executable file
582
doc/html/boostbook.css
Executable file
@ -0,0 +1,582 @@
|
||||
/*=============================================================================
|
||||
Copyright (c) 2004 Joel de Guzman
|
||||
http://spirit.sourceforge.net/
|
||||
|
||||
Use, modification and distribution is subject to the Boost Software
|
||||
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
=============================================================================*/
|
||||
|
||||
/*=============================================================================
|
||||
Body defaults
|
||||
=============================================================================*/
|
||||
|
||||
body
|
||||
{
|
||||
margin: 1em;
|
||||
font-family: sans-serif;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Paragraphs
|
||||
=============================================================================*/
|
||||
|
||||
p
|
||||
{
|
||||
text-align: left;
|
||||
font-size: 10pt;
|
||||
line-height: 1.15;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Program listings
|
||||
=============================================================================*/
|
||||
|
||||
/* Code on paragraphs */
|
||||
p tt.computeroutput
|
||||
{
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
pre.synopsis
|
||||
{
|
||||
font-size: 10pt;
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
|
||||
}
|
||||
|
||||
.programlisting,
|
||||
.screen
|
||||
{
|
||||
font-size: 10pt;
|
||||
display: block;
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
|
||||
}
|
||||
|
||||
/* Program listings in tables don't get borders */
|
||||
td .programlisting,
|
||||
td .screen
|
||||
{
|
||||
margin: 0pc 0pc 0pc 0pc;
|
||||
padding: 0pc 0pc 0pc 0pc;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Headings
|
||||
=============================================================================*/
|
||||
|
||||
h1, h2, h3, h4, h5, h6
|
||||
{
|
||||
text-align: left;
|
||||
margin: 1em 0em 0.5em 0em;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
h1 { font: 140% }
|
||||
h2 { font: bold 140% }
|
||||
h3 { font: bold 130% }
|
||||
h4 { font: bold 120% }
|
||||
h5 { font: italic 110% }
|
||||
h6 { font: italic 100% }
|
||||
|
||||
/* Top page titles */
|
||||
title,
|
||||
h1.title,
|
||||
h2.title
|
||||
h3.title,
|
||||
h4.title,
|
||||
h5.title,
|
||||
h6.title,
|
||||
.refentrytitle
|
||||
{
|
||||
font-weight: bold;
|
||||
margin-bottom: 1pc;
|
||||
}
|
||||
|
||||
h1.title { font-size: 140% }
|
||||
h2.title { font-size: 140% }
|
||||
h3.title { font-size: 130% }
|
||||
h4.title { font-size: 120% }
|
||||
h5.title { font-size: 110% }
|
||||
h6.title { font-size: 100% }
|
||||
|
||||
.section h1
|
||||
{
|
||||
margin: 0em 0em 0.5em 0em;
|
||||
font-size: 140%;
|
||||
}
|
||||
|
||||
.section h2 { font-size: 140% }
|
||||
.section h3 { font-size: 130% }
|
||||
.section h4 { font-size: 120% }
|
||||
.section h5 { font-size: 110% }
|
||||
.section h6 { font-size: 100% }
|
||||
|
||||
/* Code on titles */
|
||||
h1 tt.computeroutput { font-size: 140% }
|
||||
h2 tt.computeroutput { font-size: 140% }
|
||||
h3 tt.computeroutput { font-size: 130% }
|
||||
h4 tt.computeroutput { font-size: 120% }
|
||||
h5 tt.computeroutput { font-size: 110% }
|
||||
h6 tt.computeroutput { font-size: 100% }
|
||||
|
||||
/*=============================================================================
|
||||
Author
|
||||
=============================================================================*/
|
||||
|
||||
h3.author
|
||||
{
|
||||
font-size: 100%
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Lists
|
||||
=============================================================================*/
|
||||
|
||||
li
|
||||
{
|
||||
font-size: 10pt;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
/* Unordered lists */
|
||||
ul
|
||||
{
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
/* Ordered lists */
|
||||
ol
|
||||
{
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Links
|
||||
=============================================================================*/
|
||||
|
||||
a
|
||||
{
|
||||
text-decoration: none; /* no underline */
|
||||
}
|
||||
|
||||
a:hover
|
||||
{
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Spirit style navigation
|
||||
=============================================================================*/
|
||||
|
||||
.spirit-nav
|
||||
{
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
.spirit-nav a
|
||||
{
|
||||
color: white;
|
||||
padding-left: 0.5em;
|
||||
}
|
||||
|
||||
.spirit-nav img
|
||||
{
|
||||
border-width: 0px;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Table of contents
|
||||
=============================================================================*/
|
||||
|
||||
.toc
|
||||
{
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.1pc 1pc 0.1pc 1pc;
|
||||
font-size: 10pt;
|
||||
line-height: 1.15;
|
||||
}
|
||||
|
||||
.toc-main
|
||||
{
|
||||
text-align: center;
|
||||
margin: 3pc 16% 3pc 16%;
|
||||
padding: 3pc 1pc 3pc 1pc;
|
||||
line-height: 0.1;
|
||||
}
|
||||
|
||||
.boost-toc
|
||||
{
|
||||
float: right;
|
||||
padding: 0.5pc;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Tables
|
||||
=============================================================================*/
|
||||
|
||||
.table-title,
|
||||
div.table p.title
|
||||
{
|
||||
margin-left: 4%;
|
||||
padding-right: 0.5em;
|
||||
padding-left: 0.5em;
|
||||
}
|
||||
|
||||
.informaltable table,
|
||||
.table table
|
||||
{
|
||||
width: 92%;
|
||||
margin-left: 4%;
|
||||
margin-right: 4%;
|
||||
}
|
||||
|
||||
div.informaltable table,
|
||||
div.table table
|
||||
{
|
||||
padding: 4px;
|
||||
}
|
||||
|
||||
/* Table Cells */
|
||||
div.informaltable table tr td,
|
||||
div.table table tr td
|
||||
{
|
||||
padding: 0.5em;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
div.informaltable table tr th,
|
||||
div.table table tr th
|
||||
{
|
||||
padding: 0.5em 0.5em 0.5em 0.5em;
|
||||
border: 1pt solid white;
|
||||
font-size: 120%;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Blurbs
|
||||
=============================================================================*/
|
||||
|
||||
div.note,
|
||||
div.tip,
|
||||
div.important,
|
||||
div.caution,
|
||||
div.warning,
|
||||
div.sidebar
|
||||
{
|
||||
font-size: 10pt;
|
||||
line-height: 1.2;
|
||||
display: block;
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
|
||||
}
|
||||
|
||||
div.sidebar img
|
||||
{
|
||||
padding: 1pt;
|
||||
}
|
||||
|
||||
|
||||
|
||||
/*=============================================================================
|
||||
Callouts
|
||||
=============================================================================*/
|
||||
.line_callout_bug img
|
||||
{
|
||||
float: left;
|
||||
position:relative;
|
||||
left: 4px;
|
||||
top: -12px;
|
||||
clear: left;
|
||||
margin-left:-22px;
|
||||
}
|
||||
|
||||
.callout_bug img
|
||||
{
|
||||
}
|
||||
|
||||
|
||||
|
||||
/*=============================================================================
|
||||
Variable Lists
|
||||
=============================================================================*/
|
||||
|
||||
/* Make the terms in definition lists bold */
|
||||
div.variablelist dl dt,
|
||||
span.term
|
||||
{
|
||||
font-weight: bold;
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
div.variablelist table tbody tr td
|
||||
{
|
||||
text-align: left;
|
||||
vertical-align: top;
|
||||
padding: 0em 2em 0em 0em;
|
||||
font-size: 10pt;
|
||||
margin: 0em 0em 0.5em 0em;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
/* Make the terms in definition lists bold */
|
||||
div.variablelist dl dt
|
||||
{
|
||||
margin-bottom: 0.2em;
|
||||
}
|
||||
|
||||
div.variablelist dl dd
|
||||
{
|
||||
margin: 0em 0em 0.5em 2em;
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
div.variablelist table tbody tr td p
|
||||
div.variablelist dl dd p
|
||||
{
|
||||
margin: 0em 0em 0.5em 0em;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Misc
|
||||
=============================================================================*/
|
||||
|
||||
/* Title of books and articles in bibliographies */
|
||||
span.title
|
||||
{
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
span.underline
|
||||
{
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
span.strikethrough
|
||||
{
|
||||
text-decoration: line-through;
|
||||
}
|
||||
|
||||
/* Copyright, Legal Notice */
|
||||
div div.legalnotice p
|
||||
{
|
||||
text-align: left
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Colors
|
||||
=============================================================================*/
|
||||
|
||||
@media screen
|
||||
{
|
||||
/* Links */
|
||||
a
|
||||
{
|
||||
color: #0C7445;
|
||||
}
|
||||
|
||||
a:visited
|
||||
{
|
||||
color: #663974;
|
||||
}
|
||||
|
||||
h1 a, h2 a, h3 a, h4 a, h5 a, h6 a,
|
||||
h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover,
|
||||
h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited
|
||||
{
|
||||
text-decoration: none; /* no underline */
|
||||
color: #000000;
|
||||
}
|
||||
|
||||
/* Syntax Highlighting */
|
||||
.keyword { color: #0000AA; }
|
||||
.identifier { color: #000000; }
|
||||
.special { color: #707070; }
|
||||
.preprocessor { color: #402080; }
|
||||
.char { color: teal; }
|
||||
.comment { color: #800000; }
|
||||
.string { color: teal; }
|
||||
.number { color: teal; }
|
||||
.white_bkd { background-color: #E8FBE9; }
|
||||
.dk_grey_bkd { background-color: #A0DAAC; }
|
||||
|
||||
/* Copyright, Legal Notice */
|
||||
.copyright
|
||||
{
|
||||
color: #666666;
|
||||
font-size: small;
|
||||
}
|
||||
|
||||
div div.legalnotice p
|
||||
{
|
||||
color: #666666;
|
||||
}
|
||||
|
||||
/* Program listing */
|
||||
pre.synopsis
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
.programlisting,
|
||||
.screen
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
td .programlisting,
|
||||
td .screen
|
||||
{
|
||||
border: 0px solid #DCDCDC;
|
||||
}
|
||||
|
||||
/* Blurbs */
|
||||
div.note,
|
||||
div.tip,
|
||||
div.important,
|
||||
div.caution,
|
||||
div.warning,
|
||||
div.sidebar
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc-main
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
|
||||
/* Tables */
|
||||
div.informaltable table tr td,
|
||||
div.table table tr td
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
div.informaltable table tr th,
|
||||
div.table table tr th
|
||||
{
|
||||
background-color: #E3F9E4;
|
||||
border: 1px solid #DCDCDC;
|
||||
}
|
||||
|
||||
/* Misc */
|
||||
span.highlight
|
||||
{
|
||||
color: #00A000;
|
||||
}
|
||||
}
|
||||
|
||||
@media print
|
||||
{
|
||||
/* Links */
|
||||
a
|
||||
{
|
||||
color: black;
|
||||
}
|
||||
|
||||
a:visited
|
||||
{
|
||||
color: black;
|
||||
}
|
||||
|
||||
.spirit-nav
|
||||
{
|
||||
display: none;
|
||||
}
|
||||
|
||||
/* Program listing */
|
||||
pre.synopsis
|
||||
{
|
||||
border: 1px solid gray;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
.programlisting,
|
||||
.screen
|
||||
{
|
||||
border: 1px solid gray;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
td .programlisting,
|
||||
td .screen
|
||||
{
|
||||
border: 0px solid #DCDCDC;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc-main
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
.informaltable table,
|
||||
.table table
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
border-collapse: collapse;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
div.informaltable table tr td,
|
||||
div.table table tr td
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
div.informaltable table tr th,
|
||||
div.table table tr th
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Misc */
|
||||
span.highlight
|
||||
{
|
||||
font-weight: bold;
|
||||
}
|
||||
}
|
||||
BIN
doc/html/images/callouts/1.png
Normal file
BIN
doc/html/images/callouts/1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 391 B |
BIN
doc/html/images/callouts/10.png
Normal file
BIN
doc/html/images/callouts/10.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 485 B |
BIN
doc/html/images/callouts/11.png
Normal file
BIN
doc/html/images/callouts/11.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 410 B |
BIN
doc/html/images/callouts/12.png
Normal file
BIN
doc/html/images/callouts/12.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 488 B |
BIN
doc/html/images/callouts/13.png
Normal file
BIN
doc/html/images/callouts/13.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 509 B |
BIN
doc/html/images/callouts/14.png
Normal file
BIN
doc/html/images/callouts/14.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 499 B |
BIN
doc/html/images/callouts/15.png
Normal file
BIN
doc/html/images/callouts/15.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 507 B |
BIN
doc/html/images/callouts/2.png
Normal file
BIN
doc/html/images/callouts/2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 446 B |
BIN
doc/html/images/callouts/3.png
Normal file
BIN
doc/html/images/callouts/3.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 431 B |
BIN
doc/html/images/callouts/4.png
Normal file
BIN
doc/html/images/callouts/4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 441 B |
BIN
doc/html/images/callouts/5.png
Normal file
BIN
doc/html/images/callouts/5.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 423 B |
BIN
doc/html/images/callouts/6.png
Normal file
BIN
doc/html/images/callouts/6.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 431 B |
BIN
doc/html/images/callouts/7.png
Normal file
BIN
doc/html/images/callouts/7.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 397 B |
BIN
doc/html/images/callouts/8.png
Normal file
BIN
doc/html/images/callouts/8.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 434 B |
BIN
doc/html/images/callouts/9.png
Normal file
BIN
doc/html/images/callouts/9.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 420 B |
BIN
doc/html/images/caution.png
Executable file
BIN
doc/html/images/caution.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 4.2 KiB |
BIN
doc/html/images/home.png
Executable file
BIN
doc/html/images/home.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
BIN
doc/html/images/important.png
Executable file
BIN
doc/html/images/important.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 4.6 KiB |
BIN
doc/html/images/next.png
Executable file
BIN
doc/html/images/next.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 768 B |
BIN
doc/html/images/note.png
Executable file
BIN
doc/html/images/note.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 4.5 KiB |
BIN
doc/html/images/prev.png
Executable file
BIN
doc/html/images/prev.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 741 B |
BIN
doc/html/images/tip.png
Executable file
BIN
doc/html/images/tip.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 3.8 KiB |
BIN
doc/html/images/up.png
Executable file
BIN
doc/html/images/up.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 766 B |
BIN
doc/html/images/warning.png
Executable file
BIN
doc/html/images/warning.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 3.8 KiB |
983
doc/html/index.html
Normal file
983
doc/html/index.html
Normal file
@ -0,0 +1,983 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Chapter<EFBFBD>1.<2E>Boost.Config</title>
|
||||
<link rel="stylesheet" href="boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="index.html" title="Chapter<65>1.<2E>Boost.Config">
|
||||
<link rel="next" href="boost_config/boost_macro_reference.html" title="Boost Macro Reference">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
|
||||
<td align="center"><a href="../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_config/boost_macro_reference.html"><img src="images/next.png" alt="Next"></a></div>
|
||||
<div class="chapter" lang="en">
|
||||
<div class="titlepage"><div>
|
||||
<div><h2 class="title">
|
||||
<a name="config"></a>Chapter<EFBFBD>1.<2E>Boost.Config</h2></div>
|
||||
<div><div class="author"><h3 class="author">
|
||||
<span class="firstname">Vesa Karvonen, John Maddock</span> <span class="surname">Beman Dawes</span>
|
||||
</h3></div></div>
|
||||
<div><p class="copyright">Copyright <20> 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock</p></div>
|
||||
<div><div class="legalnotice">
|
||||
<a name="id2604803"></a><p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></div>
|
||||
</div></div>
|
||||
<div class="toc">
|
||||
<p><b>Table of Contents</b></p>
|
||||
<dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform">Configuring
|
||||
Boost for Your Platform</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration">Using
|
||||
the default boost configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header">The
|
||||
<boost/config.hpp> header</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script">Using
|
||||
the configure script</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options">User
|
||||
settable options</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage">Advanced
|
||||
configuration usage</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration">Testing
|
||||
the boost configuration</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html">Boost Macro Reference</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_defects">Macros
|
||||
that describe defects</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_optional_features">Macros
|
||||
that describe optional features</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_that_describe_c__0x_features">Macros
|
||||
that describe C++0x features</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_helper_macros">Boost
|
||||
Helper Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_informational_macros">Boost
|
||||
Informational Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.macros_for_libraries_with_separate_source_code">Macros
|
||||
for libraries with separate source code</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html">Guidelines for
|
||||
Boost Authors</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros">Adding
|
||||
New Defect Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros">Adding
|
||||
New Feature Test Macros</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers">Modifying
|
||||
the Boost Configuration Headers</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html">Rationale</a></span></dt>
|
||||
<dd><dl>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html#boost_config.rationale.the_problem">The problem</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_config/rationale.html#boost_config.rationale.the_solution">The solution</a></span></dt>
|
||||
</dl></dd>
|
||||
<dt><span class="section"><a href="boost_config/acknowledgements.html">Acknowledgements</a></span></dt>
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_config.configuring_boost_for_your_platform"></a><a href="index.html#boost_config.configuring_boost_for_your_platform" title="Configuring
|
||||
Boost for Your Platform">Configuring
|
||||
Boost for Your Platform</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration">Using
|
||||
the default boost configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header">The
|
||||
<boost/config.hpp> header</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script">Using
|
||||
the configure script</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options">User
|
||||
settable options</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage">Advanced
|
||||
configuration usage</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration">Testing
|
||||
the boost configuration</a></span></dt>
|
||||
</dl></div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration" title="Using
|
||||
the default boost configuration">Using
|
||||
the default boost configuration</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Boost comes already configured for most common compilers and platforms; you
|
||||
should be able to use boost "as is". Since the compiler is configured
|
||||
separately from the standard library, the default configuration should work
|
||||
even if you replace the compiler's standard library with a third-party standard
|
||||
library (like <a href="http://stlport.sourceforge.net" target="_top">STLport</a>).
|
||||
</p>
|
||||
<p>
|
||||
Using boost "as is" without trying to reconfigure is the recommended
|
||||
method for using boost. You can, however, run the configure script if you
|
||||
want to, and there are regression tests provided that allow you to test the
|
||||
current boost configuration with your particular compiler setup.
|
||||
</p>
|
||||
<p>
|
||||
Boost library users can request support for additional compilers or platforms
|
||||
by visiting our <a href="http://sourceforge.net/tracker/?group_id=7586" target="_top">Tracker</a>
|
||||
and submitting a support request.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.the__boost_config_hpp__header" title="The
|
||||
<boost/config.hpp> header">The
|
||||
<boost/config.hpp> header</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Boost library implementations access configuration macros via
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="preprocessor">#include</span> <a href="../../../../boost/config.hpp" target="_top"><boost/config.hpp></a>
|
||||
</pre>
|
||||
<p>
|
||||
While Boost library users are not required to include that file directly,
|
||||
or use those configuration macros, such use is acceptable. The configuration
|
||||
macros are documented as to their purpose, usage, and limitations which makes
|
||||
them usable by both Boost library and user code.
|
||||
</p>
|
||||
<p>
|
||||
Boost <a href="boost_config/boost_macro_reference.html#config_info_macros">informational</a> or <a href="boost_config/boost_macro_reference.html#config_helpers">helper</a>
|
||||
macros are designed for use by Boost users as well as for our own internal
|
||||
use. Note however, that the <a href="boost_config/boost_macro_reference.html#config_features">feature test</a>
|
||||
and <a href="boost_config/boost_macro_reference.html#config_defects">defect test</a> macros were designed
|
||||
for internal use by Boost libraries, not user code, so they can change at
|
||||
any time (though no gratuitous changes are made to them). Boost library problems
|
||||
resulting from changes to the configuration macros are caught by the Boost
|
||||
regression tests, so the Boost libraries are updated to account for those
|
||||
changes. By contrast, Boost library user code can be adversely affected by
|
||||
changes to the macros without warning. The best way to keep abreast of changes
|
||||
to the macros used in user code is to monitor the discussions on the Boost
|
||||
developers list.
|
||||
</p>
|
||||
</div>
|
||||
<a name="config_config_script"></a><p>
|
||||
</p>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.using_the_configure_script"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script" title="Using
|
||||
the configure script">Using
|
||||
the configure script</a>
|
||||
</h3></div></div></div>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top">
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
This configure script only sets up the Boost headers for use with a particular
|
||||
compiler. It has no effect on Boost.Build, or how the libraries are built.
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
</td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
If you know that boost is incorrectly configured for your particular setup,
|
||||
and you are on a UNIX like platform, then you may want to try and improve
|
||||
things by running the boost configure script. From a shell command prompt
|
||||
you will need to cd into <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
and type:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote">
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">sh</span> <span class="special">./</span><span class="identifier">configure</span></code>
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
</blockquote></div>
|
||||
<p>
|
||||
you will see a list of the items being checked as the script works its way
|
||||
through the regression tests. Note that the configure script only really
|
||||
auto-detects your compiler if it's called g++, c++ or CC. If you are using
|
||||
some other compiler you will need to set one or more of the following environment
|
||||
variables:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Variable
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
CXX
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The name of the compiler, for example <code class="computeroutput"><span class="identifier">c</span><span class="special">++</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
CXXFLAGS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The compiler flags to use, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">O2</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
LDFLAGS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The linker flags to use, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">L</span><span class="special">/</span><span class="identifier">mypath</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
LIBS
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Any libraries to link in, for example <code class="computeroutput"><span class="special">-</span><span class="identifier">lpthread</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
<p>
|
||||
For example to run the configure script with HP aCC, you might use something
|
||||
like:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">export</span> <span class="identifier">CXX</span><span class="special">=</span><span class="string">"aCC"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">CXXFLAGS</span><span class="special">=</span><span class="string">"-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE \
|
||||
-DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">LDFLAGS</span><span class="special">=</span><span class="string">"-DAportable"</span>
|
||||
<span class="keyword">export</span> <span class="identifier">LIBS</span><span class="special">=</span><span class="string">"-lpthread"</span>
|
||||
<span class="identifier">sh</span> <span class="special">./</span><span class="identifier">configure</span>
|
||||
</pre>
|
||||
<p>
|
||||
However you run the configure script, when it finishes you will find a new
|
||||
header -<code class="computeroutput"><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span></code>- located in the <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
directory. <span class="bold"><strong>Note that configure does not install this
|
||||
header into your boost include path by default</strong></span>. This header contains
|
||||
all the options generated by the configure script, plus a header-section
|
||||
that contains the user settable options from the default version of <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
(located under <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>).
|
||||
There are two ways you can use this header:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
<span class="bold"><strong>Option 1:</strong></span> copy the header into <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code> so that it replaces the default user.hpp
|
||||
provided by boost. This option allows only one configure-generated setup;
|
||||
boost developers should avoid this option, as it incurs the danger of accidentally
|
||||
committing a configure-modified <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
to the cvs repository (something you will not be thanked for!).
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Option 2:</strong></span> give the header a more memorable
|
||||
name, and place it somewhere convenient; then, define the macro <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code> to point to it. For
|
||||
example create a new sub-directory <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code><code class="computeroutput"><span class="identifier">user</span><span class="special">/</span></code>, and copy the header there; for example
|
||||
as <code class="computeroutput"><span class="identifier">multithread</span><span class="special">-</span><span class="identifier">gcc</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span></code>. Then, when compiling add the command
|
||||
line option: <code class="computeroutput"><span class="special">-</span><span class="identifier">DBOOST_USER_CONFIG</span><span class="special">=</span><span class="string">"<boost/config/user/multithread-gcc-config.hpp>"</span></code>,
|
||||
and boost will use the new configuration header. This option allows you
|
||||
to generate more than one configuration header, and to keep them separate
|
||||
from the boost source - so that updates to the source do not interfere
|
||||
with your configuration.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<a name="config_user_settable"></a><p>
|
||||
</p>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.user_settable_options"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.user_settable_options" title="User
|
||||
settable options">User
|
||||
settable options</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
There are some configuration-options that represent user choices, rather
|
||||
than compiler defects or platform specific options. These are listed in
|
||||
<code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>
|
||||
and at the start of a configure-generated <code class="computeroutput"><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span></code> header.
|
||||
You can define these on the command line, or by editing <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>, they are listed in the following table:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
Macro
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the user configuration
|
||||
file to include prior to any boost configuration files. When not
|
||||
defined, defaults to <a href="../../../../boost/config/user.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">user</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_COMPILER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the compiler configuration
|
||||
file to use. Defining this cuts out the compiler selection logic,
|
||||
and eliminates the dependency on the header containing that logic.
|
||||
For example if you are using gcc, then you could define BOOST_COMPILER_CONFIG
|
||||
to <a href="../../../../boost/config/compiler/gcc.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">compiler</span><span class="special">/</span><span class="identifier">gcc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_STDLIB_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the standard library
|
||||
configuration file to use. Defining this cuts out the standard library
|
||||
selection logic, and eliminates the dependency on the header containing
|
||||
that logic. For example if you are using STLport, then you could
|
||||
define <code class="computeroutput"><span class="identifier">BOOST_STDLIB_CONFIG</span></code>
|
||||
to <a href="../../../../boost/config/stdlib/stlport.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">stdlib</span><span class="special">/</span><span class="identifier">stlport</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_PLATFORM_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, it should point to the name of the platform configuration
|
||||
file to use. Defining this cuts out the platform selection logic,
|
||||
and eliminates the dependency on the header containing that logic.
|
||||
For example if you are compiling on linux, then you could define
|
||||
<code class="computeroutput"><span class="identifier">BOOST_PLATFORM_CONFIG</span></code>
|
||||
to <a href="../../../../boost/config/platform/linux.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">platform</span><span class="special">/</span><span class="identifier">linux</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no compiler configuration file is selected or included,
|
||||
define when the compiler is fully conformant with the standard, or
|
||||
where the user header (see <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>),
|
||||
has had any options necessary added to it, for example by an autoconf
|
||||
generated configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_STDLIB_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no standard library configuration file is selected
|
||||
or included, define when the standard library is fully conformant
|
||||
with the standard, or where the user header (see <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>),
|
||||
has had any options necessary added to it, for example by an autoconf
|
||||
generated configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_PLATFORM_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, no platform configuration file is selected or included,
|
||||
define when the platform is fully conformant with the standard (and
|
||||
has no useful extra features), or where the user header (see <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code>), has had any
|
||||
options necessary added to it, for example by an autoconf generated
|
||||
configure script.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Equivalent to defining all of <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>,
|
||||
<code class="computeroutput"><span class="identifier">BOOST_NO_STDLIB_CONFIG</span></code>
|
||||
and <code class="computeroutput"><span class="identifier">BOOST_NO_PLATFORM_CONFIG</span></code>.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_STRICT_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The normal behavior for compiler versions that are newer than the
|
||||
last known version, is to assume that they have all the same defects
|
||||
as the last known version. By setting this define, then compiler
|
||||
versions that are newer than the last known version are assumed to
|
||||
be fully conforming with the standard. This is probably most useful
|
||||
for boost developers or testers, and for those who want to use boost
|
||||
to test beta compiler versions.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ASSERT_CONFIG</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When this flag is set, if the config finds anything unknown, then
|
||||
it will stop with a #error rather than continue. Boost regression
|
||||
testers should set this define, as should anyone who wants to quickly
|
||||
check whether boost is supported on their platform.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_THREADS</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, disables threading support, even if the compiler in
|
||||
its current translation mode supports multiple threads.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_WIN32</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
When defined, disables the use of Win32 specific API's, even when
|
||||
these are available. Also has the effect of setting <code class="computeroutput"><span class="identifier">BOOST_DISABLE_THREADS</span></code> unless <code class="computeroutput"><span class="identifier">BOOST_HAS_PTHREADS</span></code> is set. This
|
||||
option may be set automatically by the config system when it detects
|
||||
that the compiler is in "strict mode".
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_DISABLE_ABI_HEADERS</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Stops boost headers from including any prefix/suffix headers that
|
||||
normally control things like struct packing and alignment.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ABI_PREFIX</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ABI_SUFFIX</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
A suffix header to include in place of whatever boost.config would
|
||||
normally select, any replacement should undo the effects of the prefix
|
||||
header.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ALL_DYN_LINK</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
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 <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span></code> 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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_</span></code><span class="emphasis"><em>WHATEVER</em></span><code class="computeroutput"><span class="identifier">_DYN_LINK</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Forces library "whatever" to be linked as a dll rather
|
||||
than a static library on Microsoft Windows: replace the <span class="emphasis"><em>WHATEVER</em></span>
|
||||
part of the macro name with the name of the library that you want
|
||||
to dynamically link to, for example use <code class="computeroutput"><span class="identifier">BOOST_DATE_TIME_DYN_LINK</span></code>
|
||||
or <code class="computeroutput"><span class="identifier">BOOST_REGEX_DYN_LINK</span></code>
|
||||
etc (this macro is used to turn on <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllimport</span><span class="special">)</span></code> 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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_ALL_NO_LIB</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_</span></code><span class="emphasis"><em>WHATEVER</em></span><code class="computeroutput"><span class="identifier">_NO_LIB</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tells the config system not to automatically select which library
|
||||
to link against for library "whatever", replace <span class="emphasis"><em>WHATEVER</em></span>
|
||||
in the macro name with the name of the library; for example <code class="computeroutput"><span class="identifier">BOOST_DATE_TIME_NO_LIB</span></code> or <code class="computeroutput"><span class="identifier">BOOST_REGEX_NO_LIB</span></code>. Normally if
|
||||
a compiler supports <code class="computeroutput"><span class="preprocessor">#pragma</span>
|
||||
<span class="identifier">lib</span></code>, 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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LIB_DIAGNOSTIC</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Causes the auto-linking code to output diagnostic messages indicating
|
||||
the name of the library that is selected for linking.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">BOOST_LIB_TOOLSET</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
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".
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage" title="Advanced
|
||||
configuration usage">Advanced
|
||||
configuration usage</a>
|
||||
</h3></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration">Example
|
||||
1, creating our own frozen configuration</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need">Example
|
||||
2: skipping files that you don't need</a></span></dt>
|
||||
<dt><span class="section"><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration">Example
|
||||
3: using configure script to freeze the boost configuration</a></span></dt>
|
||||
</dl></div>
|
||||
<p>
|
||||
By setting various macros on the compiler command line or by editing <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>,
|
||||
the boost configuration setup can be optimised in a variety of ways.
|
||||
</p>
|
||||
<p>
|
||||
Boost's configuration is structured so that the user-configuration is included
|
||||
first (defaulting to <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
if <code class="computeroutput"><span class="identifier">BOOST_USER_CONFIG</span></code> is not
|
||||
defined). This sets up any user-defined policies, and gives the user-configuration
|
||||
a chance to influence what happens next.
|
||||
</p>
|
||||
<p>
|
||||
Next the compiler, standard library, and platform configuration files are
|
||||
included. These are included via macros (<code class="computeroutput"><span class="identifier">BOOST_COMPILER_CONFIG</span></code>
|
||||
etc, <a href="index.html#config_user_settable">see user settable macros</a>),
|
||||
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 <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro is set (for example <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
to disable including any compiler configuration file - <a href="index.html#config_user_settable">see
|
||||
user settable macros</a>).
|
||||
</p>
|
||||
<p>
|
||||
Finally the boost configuration header, includes <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/suffix.hpp></a>;
|
||||
this header contains any boiler plate configuration code - for example where
|
||||
one boost macro being set implies that another must be set also.
|
||||
</p>
|
||||
<p>
|
||||
The following usage examples represent just a few of the possibilities:
|
||||
</p>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_1__creating_our_own_frozen_configuration" title="Example
|
||||
1, creating our own frozen configuration">Example
|
||||
1, creating our own frozen configuration</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
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: <a href="../../../../boost/config/compiler/visualc.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">compiler</span><span class="special">/</span><span class="identifier">visualc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the compiler, <a href="../../../../boost/config/stdlib/stlport.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">stdlib</span><span class="special">/</span><span class="identifier">stlport</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the standard library, and
|
||||
<a href="../../../../boost/config/platform/win32.hpp" target="_top"><code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">platform</span><span class="special">/</span><span class="identifier">win32</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code></a> for the platform. Next we'll
|
||||
create our own private configuration directory: <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span><span class="identifier">mysetup</span><span class="special">/</span></code>, and copy the configuration files into
|
||||
there. Finally, open up <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>
|
||||
and edit the following defines:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_COMPILER_CONFIG</span> <span class="string">"boost/config/mysetup/visualc.hpp"</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_STDLIB_CONFIG</span> <span class="string">"boost/config/mysetup/stlport.hpp"</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_USER_CONFIG</span> <span class="string">"boost/config/mysetup/win32.hpp"</span>
|
||||
</pre>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need" title="Example
|
||||
2: skipping files that you don't need">Example
|
||||
2: skipping files that you don't need</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
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 <code class="computeroutput"><span class="identifier">BOOST_NO_COMPILER_CONFIG</span></code>
|
||||
either on the command line, or in <a href="../../../../boost/config/user.hpp" target="_top"><boost/config/user.hpp></a>,
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h4 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration" title="Example
|
||||
3: using configure script to freeze the boost configuration">Example
|
||||
3: using configure script to freeze the boost configuration</a>
|
||||
</h4></div></div></div>
|
||||
<p>
|
||||
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 - <a href="index.html#config_config_script">see using the configure
|
||||
script for more details</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration"></a><a href="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration" title="Testing
|
||||
the boost configuration">Testing
|
||||
the boost configuration</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The boost configuration library provides a full set of regression test programs
|
||||
under the <span class="emphasis"><em><boost-root></em></span><code class="computeroutput"><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">/</span></code>
|
||||
<code class="computeroutput"><span class="identifier">test</span><span class="special">/</span></code>
|
||||
sub-directory:
|
||||
</p>
|
||||
<div class="informaltable"><table class="table">
|
||||
<colgroup>
|
||||
<col>
|
||||
<col>
|
||||
</colgroup>
|
||||
<thead><tr>
|
||||
<th>
|
||||
<p>
|
||||
File
|
||||
</p>
|
||||
</th>
|
||||
<th>
|
||||
<p>
|
||||
Description
|
||||
</p>
|
||||
</th>
|
||||
</tr></thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">config_test</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">limits_test</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Tests your standard library's <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code>
|
||||
implementation (or its boost provided replacement if <code class="computeroutput"><span class="identifier">BOOST_NO_LIMITS</span></code> 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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">no_</span><span class="special">*</span><span class="identifier">pass</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual compiler defect test files. Each of these should compile,
|
||||
if one does not then the corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro needs to be defined - see each test file for specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">no_</span><span class="special">*</span><span class="identifier">fail</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual compiler defect test files. Each of these should not compile,
|
||||
if one does then the corresponding <code class="computeroutput"><span class="identifier">BOOST_NO_XXX</span></code>
|
||||
macro is defined when it need not be - see each test file for specific
|
||||
details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">has_</span><span class="special">*</span><span class="identifier">pass</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual feature test files. If one of these does not compile then
|
||||
the corresponding <code class="computeroutput"><span class="identifier">BOOST_HAS_XXX</span></code>
|
||||
macro is defined when it should not be - see each test file for specific
|
||||
details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">has_</span><span class="special">*</span><span class="identifier">fail</span><span class="special">.</span><span class="identifier">cpp</span></code>
|
||||
</p>
|
||||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Individual feature test files. If one of these does compile then
|
||||
the corresponding <code class="computeroutput"><span class="identifier">BOOST_HAS_XXX</span></code>
|
||||
macro can be safely defined - see each test file for specific details.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table></div>
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
<p>
|
||||
If you have built the <a href="../../../../more/regression.html" target="_top">boost
|
||||
regression test driver</a>, then you can use this to produce a nice html
|
||||
formatted report of the results using the supplied test file.
|
||||
</p>
|
||||
<p>
|
||||
Alternatively you can run the configure script like this:
|
||||
</p>
|
||||
<div class="blockquote"><blockquote class="blockquote">
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="special">./</span><span class="identifier">configure</span>
|
||||
<span class="special">--</span><span class="identifier">enable</span><span class="special">-</span><span class="identifier">test</span></code>
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
</blockquote></div>
|
||||
<p>
|
||||
in which case the script will test the current configuration rather than
|
||||
creating a new one from scratch.
|
||||
</p>
|
||||
<p>
|
||||
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 <code class="computeroutput"><span class="identifier">config_info</span><span class="special">.</span><span class="identifier">cpp</span></code>, and the pass/fail test results.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<a name="config_rationale"></a><p>
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"><small><p>Last revised: May 30, 2007 at 04:42:31 GMT</p></small></td>
|
||||
<td align="right"><small></small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_config/boost_macro_reference.html"><img src="images/next.png" alt="Next"></a></div>
|
||||
</body>
|
||||
</html>
|
||||
827
doc/macro_reference.qbk
Normal file
827
doc/macro_reference.qbk
Normal file
@ -0,0 +1,827 @@
|
||||
[/
|
||||
Boost.Config
|
||||
|
||||
Copyright (c) 2001 Beman Dawes
|
||||
Copyright (c) 2001 Vesa Karvonen
|
||||
Copyright (c) 2001 John Maddock
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
|
||||
[section Boost Macro Reference]
|
||||
|
||||
[#config_defects]
|
||||
|
||||
[section Macros that describe defects]
|
||||
|
||||
The following macros all describe features that are required by the C++ standard,
|
||||
if one of the following macros is defined, then it represents a defect in the
|
||||
compiler's conformance with the standard.
|
||||
|
||||
|
||||
[table
|
||||
[[Macro ][Section ][ Description ]]
|
||||
|
||||
|
||||
[[`BOOST_BCB_PARTIAL_SPECIALIZATION_BUG`][Compiler][
|
||||
The compiler exibits certain partial specialisation bug - probably Borland
|
||||
C++ Builder specific.
|
||||
]]
|
||||
[[`BOOST_FUNCTION_SCOPE_USING_DECLARATION_BREAKS_ADL`][Compiler][
|
||||
Argument dependent lookup fails if there is a using declaration for the
|
||||
symbol being looked up in the current scope. For example, using
|
||||
`boost::get_pointer`; prevents ADL from finding overloads of `get_pointer`
|
||||
in namespaces nested inside boost (but not elsewhere). Probably
|
||||
Borland specific.
|
||||
]]
|
||||
[[`BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP`][Compiler][
|
||||
Compiler does not implement argument-dependent lookup (also named
|
||||
Koenig lookup); see std::3.4.2 \[basic.koenig.lookup\]
|
||||
]]
|
||||
[[`BOOST_NO_AUTO_PTR`][Standard library][
|
||||
If the compiler / library supplies non-standard or broken `std::auto_ptr`.
|
||||
]]
|
||||
[[`BOOST_NO_CTYPE_FUNCTIONS`][Platform][
|
||||
The Platform does not provide functions for the character-classifying
|
||||
operations `<ctype.h>` and `<cctype>`, only macros.
|
||||
]]
|
||||
[[`BOOST_NO_CV_SPECIALIZATIONS`][Compiler][
|
||||
If template specialisations for cv-qualified types conflict with a
|
||||
specialisation for a cv-unqualififed type.
|
||||
]]
|
||||
[[`BOOST_NO_CV_VOID_SPECIALIZATIONS`][Compiler][
|
||||
If template specialisations for cv-void types conflict with a specialisation
|
||||
for void.
|
||||
]]
|
||||
[[`BOOST_NO_CWCHAR`][Platform][
|
||||
The Platform does not provide `<wchar.h>` and `<cwchar>`.
|
||||
]]
|
||||
[[`BOOST_NO_CWCTYPE`][Platform][
|
||||
The Platform does not provide `<wctype.h>` and `<cwctype>`.
|
||||
]]
|
||||
[[`BOOST_NO_DEPENDENT_NESTED_DERIVATIONS`][Compiler][
|
||||
The compiler fails to compile a nested class that has a dependent base class:
|
||||
``
|
||||
template<typename T>
|
||||
struct foo : {
|
||||
template<typename U>
|
||||
struct bar : public U {};
|
||||
``
|
||||
};
|
||||
]]
|
||||
[[`BOOST_NO_DEPENDENT_TYPES_IN_TEMPLATE_VALUE_PARAMETERS`][Compiler][
|
||||
Template value parameters cannot have a dependent type, for example:
|
||||
``
|
||||
template<class T, typename T::type value>
|
||||
class X { ... };
|
||||
``
|
||||
]]
|
||||
[[`BOOST_NO_EXCEPTION_STD_NAMESPACE`][Standard Library][
|
||||
The standard library does not put some or all of the contents of
|
||||
`<exception>` in namespace std.
|
||||
]]
|
||||
[[`BOOST_NO_EXCEPTIONS`][Compiler][
|
||||
The compiler does not support exception handling (this setting is typically
|
||||
required by many C++ compilers for embedded platforms). Note that there is
|
||||
no requirement for boost libraries to honor this configuration setting -
|
||||
indeed doing so may be impossible in some cases. Those libraries that do
|
||||
honor this will typically abort if a critical error occurs - you have been
|
||||
warned!
|
||||
]]
|
||||
[[`BOOST_NO_EXPLICIT_FUNCTION_TEMPLATE_ARGUMENTS`][Compiler][
|
||||
Can only use deduced template arguments when calling function template
|
||||
instantiations.
|
||||
]]
|
||||
[[`BOOST_NO_FUNCTION_TEMPLATE_ORDERING`][Compiler][
|
||||
The compiler does not perform function template ordering or its function
|
||||
template ordering is incorrect.
|
||||
``
|
||||
// #1
|
||||
template<class T> void f(T);
|
||||
|
||||
// #2
|
||||
template<class T,class U> void f(T(*)(U));
|
||||
|
||||
void bar(int);
|
||||
|
||||
f(&bar); // should choose #2.
|
||||
``
|
||||
]]
|
||||
[[`BOOST_NO_INCLASS_MEMBER_INITIALIZATION`][Compiler][
|
||||
Compiler violates std::9.4.2/4.
|
||||
]]
|
||||
[[`BOOST_NO_INTRINSIC_WCHAR_T`][Compiler][
|
||||
The C++ implementation does not provide `wchar_t`, or it is really a synonym
|
||||
for another integral type. Use this symbol to decide whether it is appropriate
|
||||
to explicitly specialize a template on `wchar_t` if there is already a
|
||||
specialization for other integer types.
|
||||
]]
|
||||
[[`BOOST_NO_IS_ABSTRACT`][Compiler][
|
||||
The C++ compiler does not support SFINAE with abstract types, this is covered
|
||||
by __CORE_LANGUAGE_DR337__, but is not part of the current standard. Fortunately
|
||||
most compilers that support SFINAE also support this DR.
|
||||
]]
|
||||
[[`BOOST_NO_LIMITS`][Standard library][
|
||||
The C++ implementation does not provide the `<limits>` header. Never check for
|
||||
this symbol in library code; always include `<boost/limits.hpp>`, which
|
||||
guarantees to provide `std::numeric_limits`.
|
||||
]]
|
||||
[[`BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS`][Standard library][
|
||||
Constants such as `numeric_limits<T>::is_signed` are not available for use
|
||||
at compile-time.
|
||||
]]
|
||||
[[`BOOST_NO_LONG_LONG_NUMERIC_LIMITS`][Standard library][
|
||||
There is no specialization for `numeric_limits<long long>` and
|
||||
`numeric_limits<unsigned long long>`. `<boost/limits.hpp>` will then add these
|
||||
specializations as a standard library "fix" only if the compiler supports the
|
||||
`long long` datatype.
|
||||
]]
|
||||
[[`BOOST_NO_MEMBER_FUNCTION_SPECIALIZATIONS`][Compiler][
|
||||
The compiler does not support the specialization of individual member
|
||||
functions of template classes.
|
||||
]]
|
||||
[[`BOOST_NO_MEMBER_TEMPLATE_KEYWORD`][Compiler][
|
||||
If the compiler supports member templates, but not the template keyword
|
||||
when accessing member template classes.
|
||||
]]
|
||||
[[`BOOST_NO_MEMBER_TEMPLATE_FRIENDS`][Compiler][
|
||||
Member template friend syntax (`template<class P> friend class frd;`)
|
||||
described in the C++ Standard, 14.5.3, not supported.
|
||||
]]
|
||||
[[`BOOST_NO_MEMBER_TEMPLATES`][Compiler][
|
||||
Member template functions not fully supported.
|
||||
]]
|
||||
[[`BOOST_NO_MS_INT64_NUMERIC_LIMITS`][Standard library][
|
||||
There is no specialization for `numeric_limits<__int64>` and
|
||||
`numeric_limits<unsigned __int64>`. `<boost/limits.hpp>` will then add these
|
||||
specializations as a standard library "fix", only if the compiler supports
|
||||
the `__int64` datatype.
|
||||
]]
|
||||
[[`BOOST_NO_OPERATORS_IN_NAMESPACE`][Compiler][
|
||||
Compiler requires inherited operator friend functions to be defined at
|
||||
namespace scope, then using'ed to boost. Probably GCC specific. See
|
||||
[@../../../../boost/operators.hpp `<boost/operators.hpp>`] for example.
|
||||
]]
|
||||
[[`BOOST_NO_POINTER_TO_MEMBER_CONST`][Compiler][
|
||||
The compiler does not correctly handle pointers to const member functions,
|
||||
preventing use of these in overloaded function templates. See
|
||||
[@../../../../boost/functional.hpp `<boost/functional.hpp>`] for example.
|
||||
]]
|
||||
[[`BOOST_NO_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS`][Compiler][
|
||||
Pointers to members don't work when used as template parameters.
|
||||
]]
|
||||
[[`BOOST_NO_PRIVATE_IN_AGGREGATE`][Compiler][
|
||||
The compiler misreads 8.5.1, treating classes as non-aggregate if they
|
||||
contain private or protected member functions.
|
||||
]]
|
||||
[[`BOOST_NO_SFINAE`][Compiler][
|
||||
The compiler does not support the "Substitution Failure Is Not An Error"
|
||||
meta-programming idiom.
|
||||
]]
|
||||
[[`BOOST_NO_STD_ALLOCATOR`][Standard library][
|
||||
The C++ standard library does not provide a standards conforming
|
||||
`std::allocator`.
|
||||
]]
|
||||
[[`BOOST_NO_STD_DISTANCE`][Standard library][
|
||||
The platform does not have a conforming version of `std::distance`.
|
||||
]]
|
||||
[[`BOOST_NO_STD_ITERATOR`][Standard library][
|
||||
The C++ implementation fails to provide the `std::iterator` class.
|
||||
]]
|
||||
[[`BOOST_NO_STD_ITERATOR_TRAITS`][Standard library][
|
||||
The compiler does not provide a standard compliant implementation of
|
||||
`std::iterator_traits`. Note that the compiler may still have a
|
||||
non-standard implementation.
|
||||
]]
|
||||
[[`BOOST_NO_STD_LOCALE`][Standard library][
|
||||
The standard library lacks `std::locale`.
|
||||
]]
|
||||
[[`BOOST_NO_STD_MESSAGES`][Standard library][
|
||||
The standard library lacks a conforming `std::messages` facet.
|
||||
]]
|
||||
[[`BOOST_NO_STD_MIN_MAX`][Standard library][
|
||||
The C++ standard library does not provide the `min()` and `max()` template
|
||||
functions that should be in `<algorithm>`.
|
||||
]]
|
||||
[[`BOOST_NO_STD_OUTPUT_ITERATOR_ASSIGN`][Standard library][
|
||||
Defined if the standard library's output iterators are not assignable.
|
||||
]]
|
||||
[[`BOOST_NO_STD_USE_FACET`][Standard library][
|
||||
The standard library lacks a conforming `std::use_facet`.
|
||||
]]
|
||||
[[`BOOST_NO_STD_WSTREAMBUF`][Standard library][
|
||||
The standard library's implementation of `std::basic_streambuf<wchar_t>`
|
||||
is either missing, incomplete, or buggy.
|
||||
]]
|
||||
[[`BOOST_NO_STD_WSTRING`][Standard library][
|
||||
The standard library lacks `std::wstring`.
|
||||
]]
|
||||
[[`BOOST_NO_STDC_NAMESPACE`][Compiler, Platform][
|
||||
The contents of C++ standard headers for C library functions
|
||||
(the `<c...>` headers) have not been placed in namespace std. This test is
|
||||
difficult - some libraries "fake" the std C functions by adding using
|
||||
declarations to import them into namespace std, unfortunately they don't
|
||||
necessarily catch all of them...
|
||||
]]
|
||||
[[`BOOST_NO_STRINGSTREAM`][Standard library][
|
||||
The C++ implementation does not provide the `<sstream>` header.
|
||||
]]
|
||||
[[`BOOST_NO_SWPRINTF`][Platform][
|
||||
The platform does not have a conforming version of `swprintf`.
|
||||
]]
|
||||
[[`BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION`][Compiler][
|
||||
Class template partial specialization (14.5.4 \[temp.class.spec\]) not
|
||||
supported.
|
||||
]]
|
||||
[[`BOOST_NO_TEMPLATED_ITERATOR_CONSTRUCTORS`][Standard library][
|
||||
The standard library does not provide templated iterator constructors
|
||||
for its containers.
|
||||
]]
|
||||
[[`BOOST_NO_TEMPLATE_TEMPLATES`][Compiler][
|
||||
The compiler does not support template template parameters.
|
||||
]]
|
||||
[[`BOOST_NO_UNREACHABLE_RETURN_DETECTION`][Compiler][
|
||||
If a return is unreachable, then no return statement should be required,
|
||||
however some compilers insist on it, while other issue a bunch of warnings
|
||||
if it is in fact present.
|
||||
]]
|
||||
[[`BOOST_NO_USING_DECLARATION_OVERLOADS_FROM_TYPENAME_BASE`][Compiler][
|
||||
The compiler will not accept a using declaration that brings a function
|
||||
from a typename used as a base class into a derived class if functions of
|
||||
the same name are present in the derived class.
|
||||
]]
|
||||
[[`BOOST_NO_USING_TEMPLATE`][Compiler][
|
||||
The compiler will not accept a using declaration that imports a template
|
||||
class or function from another namespace. Originally a Borland specific
|
||||
problem with imports to/from the global namespace, extended to MSVC6
|
||||
which has a specific issue with importing template classes (but not
|
||||
functions).
|
||||
]]
|
||||
[[`BOOST_NO_VOID_RETURNS`][Compiler][
|
||||
The compiler does not allow a void function to return the result of calling
|
||||
another void function.
|
||||
``
|
||||
void f() {}
|
||||
void g() { return f(); }
|
||||
``
|
||||
]]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
[#config_features]
|
||||
|
||||
[section Macros that describe optional features]
|
||||
|
||||
The following macros describe features that are not required by the C++
|
||||
standard. The macro is only defined if the feature is present.
|
||||
|
||||
|
||||
[table
|
||||
[[Macro ][Section ][Description ]]
|
||||
|
||||
[[`BOOST_HAS_BETHREADS`][Platform][
|
||||
The platform supports BeOS style threads.
|
||||
]]
|
||||
[[`BOOST_HAS_CLOCK_GETTIME`][Platform][
|
||||
The platform has the POSIX API `clock_gettime`.
|
||||
]]
|
||||
[[`BOOST_HAS_DECLSPEC`][Compiler][
|
||||
The compiler uses `__declspec(dllexport)` and `__declspec(dllimport)` to
|
||||
export/import symbols from dll's.
|
||||
]]
|
||||
[[`BOOST_HAS_DIRENT_H`][Platform][
|
||||
The platform has the POSIX header `<dirent.h>`.
|
||||
]]
|
||||
[[`BOOST_HAS_EXPM1`][Platform][
|
||||
The platform has the functions `expm1`, `expm1f` and `expm1l` in `<math.h>`
|
||||
]]
|
||||
[[`BOOST_HAS_FTIME`][Platform][
|
||||
The platform has the Win32 API `GetSystemTimeAsFileTime`.
|
||||
]]
|
||||
[[`BOOST_HAS_GETTIMEOFDAY`][Platform][
|
||||
The platform has the POSIX API `gettimeofday`.
|
||||
]]
|
||||
[[`BOOST_HAS_HASH`][Standard library][
|
||||
The C++ implementation provides the (SGI) hash_set and hash_map classes.
|
||||
When defined, `BOOST_HASH_SET_HEADER` and `BOOST_HASH_LIST_HEADER` will contain
|
||||
the names of the header needed to access hash_set and hash_map;
|
||||
`BOOST_STD_EXTENSION_NAMESPACE` will provide the namespace in which the two
|
||||
class templates reside.
|
||||
]]
|
||||
[[`BOOST_HAS_LOG1P`][Platform][
|
||||
The platform has the functions `log1p`, `log1pf` and `log1pl` in `<math.h>`.
|
||||
]]
|
||||
[[`BOOST_HAS_MACRO_USE_FACET`][Standard library][
|
||||
The standard library lacks a conforming `std::use_facet`, but has a macro
|
||||
`_USE(loc, Type)` that does the job. This is primarily for the Dinkumware
|
||||
std lib.
|
||||
]]
|
||||
[[`BOOST_HAS_MS_INT64`][Compiler][
|
||||
The compiler supports the `__int64` data type.
|
||||
]]
|
||||
[[`BOOST_HAS_NANOSLEEP`][Platform][
|
||||
The platform has the POSIX API nanosleep.
|
||||
]]
|
||||
[[`BOOST_HAS_NL_TYPES_H`][Platform][
|
||||
The platform has an `<nl_types.h>`.
|
||||
]]
|
||||
[[`BOOST_HAS_NRVO`][Compiler][
|
||||
Indicated that the compiler supports the named return value optimization
|
||||
(NRVO). Used to select the most efficient implementation for some function.
|
||||
See [@../../../../boost/operators.hpp `<boost/operators.hpp>`] for example.
|
||||
]]
|
||||
[[`BOOST_HAS_PARTIAL_STD_ALLOCATOR`][Standard Library][
|
||||
The standard library has a partially conforming `std::allocator` class, but
|
||||
without any of the member templates.
|
||||
]]
|
||||
[[`BOOST_HAS_PTHREAD_DELAY_NP`][Platform][
|
||||
The platform has the POSIX API `pthread_delay_np`.
|
||||
]]
|
||||
[[`BOOST_HAS_PTHREAD_MUTEXATTR_SETTYPE`][Platform][
|
||||
The platform has the POSIX API `pthread_mutexattr_settype`.
|
||||
]]
|
||||
[[`BOOST_HAS_PTHREAD_YIELD`][Platform][
|
||||
The platform has the POSIX API `pthread_yield`.
|
||||
]]
|
||||
[[`BOOST_HAS_PTHREADS`][Platform][
|
||||
The platform support POSIX style threads.
|
||||
]]
|
||||
[[`BOOST_HAS_SCHED_YIELD`][Platform][
|
||||
The platform has the POSIX API `sched_yield`.
|
||||
]]
|
||||
[[`BOOST_HAS_SGI_TYPE_TRAITS`][Compiler, Standard library][
|
||||
The compiler has native support for SGI style type traits.
|
||||
]]
|
||||
[[`BOOST_HAS_STDINT_H`][Platform][
|
||||
The platform has a `<stdint.h>`
|
||||
]]
|
||||
[[`BOOST_HAS_SLIST`][Standard library][
|
||||
The C++ implementation provides the (SGI) slist class. When defined,
|
||||
`BOOST_SLIST_HEADER` will contain the name of the header needed to access
|
||||
`slist` and `BOOST_STD_EXTENSION_NAMESPACE` will provide the namespace in
|
||||
which `slist` resides.
|
||||
]]
|
||||
[[`BOOST_HAS_STLP_USE_FACET`][Standard library][
|
||||
The standard library lacks a conforming `std::use_facet`, but has a workaround
|
||||
class-version that does the job. This is primarily for the STLport std lib.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_ARRAY`][Standard library][
|
||||
The library has a TR1 conforming version of `<array>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_COMPLEX_OVERLOADS`][Standard library][
|
||||
The library has a version of `<complex>` that supports passing scalars to the
|
||||
complex number algorithms.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_COMPLEX_INVERSE_TRIG`][Standard library][
|
||||
The library has a version of `<complex>` that includes the new inverse trig
|
||||
functions from TR1.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_REFERENCE_WRAPPER`][Standard library][
|
||||
The library has TR1 conforming reference wrappers in `<functional>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_RESULT_OF`][Standard library][
|
||||
The library has a TR1 conforming result_of template in `<functional>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_MEM_FN`][Standard library][
|
||||
The library has a TR1 conforming mem_fn function template in `<functional>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_BIND`][Standard library][
|
||||
The library has a TR1 conforming bind function template in `<functional>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_FUNCTION`][Standard library][
|
||||
The library has a TR1 conforming function class template in `<functional>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_HASH`][Standard library][
|
||||
The library has a TR1 conforming hash function template in `<functional>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_SHARED_PTR`][Standard library][
|
||||
The library has a TR1 conforming `shared_ptr` class template in `<memory>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_RANDOM`][Standard library][
|
||||
The library has a TR1 conforming version of `<random>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_REGEX`][Standard library][
|
||||
The library has a TR1 conforming version of `<regex>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_TUPLE`][Standard library][
|
||||
The library has a TR1 conforming version of `<tuple>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_TYPE_TRAITS`][Standard library][
|
||||
The library has a TR1 conforming version of `<type_traits>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_UTILITY`][Standard library][
|
||||
The library has the TR1 additions to `<utility>` (tuple interface to `std::pair`).
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_UNORDERED_MAP`][Standard library][
|
||||
The library has a TR1 conforming version of `<unordered_map>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1_UNORDERED_SET`][Standard library][
|
||||
The library has a TR1 conforming version of `<unordered_set>`.
|
||||
]]
|
||||
[[`BOOST_HAS_TR1`][Standard library][
|
||||
Implies all the other `BOOST_HAS_TR1_*` macros should be set.
|
||||
]]
|
||||
[[`BOOST_HAS_THREADS`][Platform, Compiler][
|
||||
Defined if the compiler, in its current translation mode, supports multiple
|
||||
threads of execution.
|
||||
]]
|
||||
[[`BOOST_HAS_TWO_ARG_USE_FACET`][Standard library][
|
||||
The standard library lacks a conforming std::use_facet, but has a two
|
||||
argument version that does the job. This is primarily for the Rogue Wave
|
||||
std lib.
|
||||
]]
|
||||
[[`BOOST_HAS_UNISTD_H`][Platform][
|
||||
The Platform provides `<unistd.h>`.
|
||||
]]
|
||||
[[`BOOST_HAS_WINTHREADS`][Platform][
|
||||
The platform supports MS Windows style threads.
|
||||
]]
|
||||
[[`BOOST_MSVC_STD_ITERATOR`][Standard library][
|
||||
Microsoft's broken version of `std::iterator` is being used. This implies that
|
||||
`std::iterator` takes no more than two template parameters.
|
||||
]]
|
||||
[[`BOOST_MSVC6_MEMBER_TEMPLATES`][Compiler][
|
||||
Microsoft Visual C++ 6.0 has enough member template idiosyncrasies
|
||||
(being polite) that `BOOST_NO_MEMBER_TEMPLATES` is defined for this compiler.
|
||||
`BOOST_MSVC6_MEMBER_TEMPLATES` is defined to allow compiler specific workarounds.
|
||||
This macro gets defined automatically if `BOOST_NO_MEMBER_TEMPLATES` is not
|
||||
defined - in other words this is treated as a strict subset of the features
|
||||
required by the standard.
|
||||
]]
|
||||
[[`BOOST_HAS_STDINT_H`][Platform][
|
||||
There are no 1998 C++ Standard headers `<stdint.h>` or `<cstdint>`, although the
|
||||
1999 C Standard does include `<stdint.h>`. If `<stdint.h>` is present,
|
||||
`<boost/stdint.h>` can make good use of it, so a flag is supplied (signalling
|
||||
presence; thus the default is not present, conforming to the current C++
|
||||
standard).
|
||||
]]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Macros that describe C++0x features]
|
||||
|
||||
The following macros describe features that are likely to be included in the
|
||||
upcoming ISO C++ standard, C++0x.
|
||||
|
||||
|
||||
[table
|
||||
[[Macro ][Description ]]
|
||||
|
||||
[[`BOOST_HAS_CONCEPTS`][
|
||||
The compiler supports concepts. Note: concepts have been proposed for C++0x,
|
||||
but have not yet been approved for inclusion in the language.
|
||||
]]
|
||||
[[`BOOST_HAS_LONG_LONG`][
|
||||
The compiler supports the long long data type.
|
||||
]]
|
||||
[[`BOOST_HAS_RVALUE_REFS`][
|
||||
The compiler supports rvalue references.
|
||||
]]
|
||||
[[`BOOST_HAS_STATIC_ASSERT`][
|
||||
The compiler supports static assertions.
|
||||
]]
|
||||
[[`BOOST_HAS_VARIADIC_TMPL`][
|
||||
The compiler supports variadic templates. Note: variadic templates have been
|
||||
proposed for C++0x, but have not yet been approved for inclusion in the
|
||||
language.
|
||||
]]
|
||||
]
|
||||
|
||||
|
||||
[endsect]
|
||||
|
||||
[#config_helpers]
|
||||
|
||||
[section Boost Helper Macros]
|
||||
|
||||
The following macros are either simple helpers, or macros that provide
|
||||
workarounds for compiler/standard library defects.
|
||||
|
||||
|
||||
[table
|
||||
[[Macro ][Description ]]
|
||||
|
||||
[[`BOOST_DEDUCED_TYPENAME`][
|
||||
Some compilers don't support the use of typename for dependent types in deduced
|
||||
contexts. This macro expands to nothing on those compilers, and typename
|
||||
elsewhere. For example, replace:
|
||||
`template <class T> void f(T, typename T::type);`
|
||||
with:
|
||||
`template <class T> void f(T, BOOST_DEDUCED_TYPENAME T::type);`
|
||||
]]
|
||||
[[`BOOST_HASH_MAP_HEADER`][
|
||||
The header to include to get the SGI `hash_map` class. This macro is only
|
||||
available if `BOOST_HAS_HASH` is defined.
|
||||
]]
|
||||
[[`BOOST_HASH_SET_HEADER`][
|
||||
The header to include to get the SGI `hash_set` class. This macro is only
|
||||
available if `BOOST_HAS_HASH` is defined.
|
||||
]]
|
||||
[[`BOOST_SLIST_HEADER`][
|
||||
The header to include to get the SGI `slist` class. This macro is only
|
||||
available if `BOOST_HAS_SLIST` is defined.
|
||||
]]
|
||||
[[`BOOST_STD_EXTENSION_NAMESPACE`][
|
||||
The namespace used for std library extensions (hashtable classes etc).
|
||||
]]
|
||||
[[`BOOST_STATIC_CONSTANT(Type, assignment)`][
|
||||
On compilers which don't allow in-class initialization of static integral
|
||||
constant members, we must use enums as a workaround if we want the constants
|
||||
to be available at compile-time. This macro gives us a convenient way to
|
||||
declare such constants.
|
||||
For example instead of:
|
||||
``
|
||||
struct foo{
|
||||
static const int value = 2;
|
||||
};
|
||||
``
|
||||
use:
|
||||
``
|
||||
struct foo{
|
||||
BOOST_STATIC_CONSTANT(int, value = 2);
|
||||
};
|
||||
``
|
||||
]]
|
||||
[[`BOOST_UNREACHABLE_RETURN(result)`][
|
||||
Normally evaluates to nothing, but evaluates to return x; if the compiler
|
||||
requires a return, even when it can never be reached.
|
||||
]]
|
||||
[[`BOOST_EXPLICIT_TEMPLATE_TYPE(t)`
|
||||
`BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t,v)`
|
||||
`BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t)`
|
||||
`BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t,v)`][
|
||||
Some compilers silently "fold" different function template instantiations if
|
||||
some of the template parameters don't appear in the function parameter list.
|
||||
For instance:
|
||||
``
|
||||
#include <iostream>
|
||||
#include <ostream>
|
||||
#include <typeinfo>
|
||||
|
||||
template <int n>
|
||||
void f() { std::cout << n << ' '; }
|
||||
|
||||
template <typename T>
|
||||
void g() { std::cout << typeid(T).name() << ' '; }
|
||||
|
||||
int main() {
|
||||
f<1>();
|
||||
f<2>();
|
||||
|
||||
g<int>();
|
||||
g<double>();
|
||||
}
|
||||
``
|
||||
incorrectly outputs [^2 2 double double] on VC++ 6. These macros, to be used
|
||||
in the function parameter list, fix the problem without effects on the calling
|
||||
syntax. For instance, in the case above write:
|
||||
``
|
||||
template <int n>
|
||||
void f(BOOST_EXPLICIT_TEMPLATE_NON_TYPE(int, n)) { ... }
|
||||
|
||||
template <typename T>
|
||||
void g(BOOST_EXPLICIT_TEMPLATE_TYPE(T)) { ... }
|
||||
``
|
||||
Beware that they can declare (for affected compilers) a dummy defaulted
|
||||
parameter, so they
|
||||
|
||||
[*a)] should be always invoked [*at the end] of the parameter list
|
||||
|
||||
[*b)] can't be used if your function template is multiply declared.
|
||||
|
||||
Furthermore, in order to add any needed comma separator, an `APPEND_*` version
|
||||
must be used when the macro invocation appears after a normal parameter
|
||||
declaration or after the invocation of another macro of this same group.
|
||||
]]
|
||||
[[`BOOST_USE_FACET(Type, loc)`][
|
||||
When the standard library does not have a comforming `std::use_facet` there
|
||||
are various workarounds available, but they differ from library to library.
|
||||
This macro provides a consistent way to access a locale's facets. For example,
|
||||
replace:
|
||||
`std::use_facet<Type>(loc);`
|
||||
with:
|
||||
`BOOST_USE_FACET(Type, loc);`
|
||||
Note do not add a `std::` prefix to the front of `BOOST_USE_FACET`.
|
||||
]]
|
||||
[[`BOOST_HAS_FACET(Type, loc)`][
|
||||
When the standard library does not have a comforming `std::has_facet` there
|
||||
are various workarounds available, but they differ from library to library.
|
||||
This macro provides a consistent way to check a locale's facets. For example,
|
||||
replace:
|
||||
`std::has_facet<Type>(loc);`
|
||||
with:
|
||||
`BOOST_HAS_FACET(Type, loc);`
|
||||
Note do not add a `std::` prefix to the front of `BOOST_HAS_FACET`.
|
||||
]]
|
||||
[[`BOOST_NESTED_TEMPLATE`][
|
||||
Member templates are supported by some compilers even though they can't use
|
||||
the `A::template member<U>` syntax, as a workaround replace:
|
||||
`typedef typename A::template rebind<U> binder;`
|
||||
with:
|
||||
`typedef typename A::BOOST_NESTED_TEMPLATE rebind<U> binder;`
|
||||
]]
|
||||
[[`BOOST_STRINGIZE(X)`][
|
||||
Converts the parameter `X` to a string after macro replacement on `X` has
|
||||
been performed.
|
||||
]]
|
||||
[[`BOOST_JOIN(X,Y)`][
|
||||
This piece of macro magic joins the two arguments together, even when one of
|
||||
the arguments is itself a macro (see 16.3.1 in C++ standard). This is normally
|
||||
used to create a mangled name in combination with a predefined macro such a
|
||||
\_\_LINE__.
|
||||
]]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
[#config_info_macros]
|
||||
|
||||
[section Boost Informational Macros]
|
||||
|
||||
The following macros describe boost features; these are, generally speaking
|
||||
the only boost macros that should be tested in user code.
|
||||
|
||||
[table
|
||||
|
||||
[[Macro ][Header ][Description ]]
|
||||
|
||||
[[`BOOST_VERSION`][`<boost/version.hpp>`][
|
||||
Describes the boost version number in XXYYZZ format such that:
|
||||
`(BOOST_VERSION % 100)` is the sub-minor version, `((BOOST_VERSION / 100) % 1000)`
|
||||
is the minor version, and `(BOOST_VERSION / 100000)` is the major version.
|
||||
]]
|
||||
[[`BOOST_NO_INT64_T`][`<boost/cstdint.hpp>` `<boost/stdint.h>`][
|
||||
Defined if there are no 64-bit integral types: `int64_t`, `uint64_t` etc.
|
||||
]]
|
||||
[[`BOOST_NO_INTEGRAL_INT64_T`][`<boost/cstdint.hpp>` `<boost/stdint.h>`][
|
||||
Defined if `int64_t` as defined by `<boost/cstdint.hpp>` is not usable in
|
||||
integral constant expressions.
|
||||
]]
|
||||
[[`BOOST_MSVC`][`<boost/config.hpp>`][
|
||||
Defined if the compiler is really Microsoft Visual C++, as opposed to one
|
||||
of the many other compilers that also define `_MSC_VER`.
|
||||
]]
|
||||
[[`BOOST_INTEL`][`<boost/config.hpp>`][
|
||||
Defined if the compiler is an Intel compiler, takes the same value as the
|
||||
compiler version macro.
|
||||
]]
|
||||
[[`BOOST_WINDOWS`][`<boost/config.hpp>`][
|
||||
Defined if the Windows platfrom API is available.
|
||||
]]
|
||||
[[`BOOST_DINKUMWARE_STDLIB`][`<boost/config.hpp>`][
|
||||
Defined if the dinkumware standard library is in use, takes the same value
|
||||
as the Dinkumware library version macro `_CPPLIB_VER` if defined, otherwise 1.
|
||||
]]
|
||||
[[`BOOST_NO_WREGEX`][`<boost/regex.hpp>`][
|
||||
Defined if the regex library does not support wide character regular
|
||||
expressions.
|
||||
]]
|
||||
[[`BOOST_COMPILER`][`<boost/config.hpp>`][
|
||||
Defined as a string describing the name and version number of the compiler
|
||||
in use. Mainly for debugging the configuration.
|
||||
]]
|
||||
[[`BOOST_STDLIB`][`<boost/config.hpp>`][
|
||||
Defined as a string describing the name and version number of the standard
|
||||
library in use. Mainly for debugging the configuration.
|
||||
]]
|
||||
[[`BOOST_PLATFORM`][`<boost/config.hpp>`][
|
||||
Defined as a string describing the name of the platform. Mainly for debugging
|
||||
the configuration.
|
||||
]]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Macros for libraries with separate source code]
|
||||
|
||||
The following macros and helper headers are of use to authors whose libraries
|
||||
include separate source code, and are intended to address two issues: fixing
|
||||
the ABI of the compiled library, and selecting which compiled library to link
|
||||
against based upon the compilers settings.
|
||||
|
||||
[section ABI Fixing]
|
||||
|
||||
When linking against a pre-compiled library it vital that the ABI used by the
|
||||
compiler when building the library ['matches exactly] the ABI used by the code
|
||||
using the library. In this case ABI means things like the struct packing
|
||||
arrangement used, the name mangling scheme used, or the size of some types
|
||||
(enum types for example). This is separate from things like threading support,
|
||||
or runtime library variations, which have to be dealt with by build variants.
|
||||
To put this in perspective there is one compiler (Borland's) that has so many
|
||||
compiler options that make subtle changes to the ABI, that at least in theory
|
||||
there 3200 combinations, and that's without considering runtime library
|
||||
variations. Fortunately these variations can be managed by `#pragma`'s that
|
||||
tell the compiler what ABI to use for the types declared in your library.
|
||||
In order to avoid sprinkling `#pragma`'s all over the boost headers, there are
|
||||
some prefix and suffix headers that do the job. Typical usage is:
|
||||
|
||||
[*my_library.hpp]
|
||||
|
||||
#ifndef MY_INCLUDE_GUARD
|
||||
#define MY_INCLUDE_GUARD
|
||||
|
||||
// all includes go here:
|
||||
``[^[*#include <boost/config.hpp>]]``
|
||||
#include <whatever>
|
||||
|
||||
``[^[*#include <boost/config/abi_prefix.hpp>]]`` // must be the last #include
|
||||
|
||||
namespace boost {
|
||||
|
||||
// your code goes here
|
||||
|
||||
}
|
||||
|
||||
``[^[*#include <boost/config/abi_suffix.hpp>]]`` // pops abi_prefix.hpp pragmas
|
||||
|
||||
#endif // include guard
|
||||
|
||||
[*my_library.cpp]
|
||||
|
||||
...
|
||||
// nothing special need be done in the implementation file
|
||||
...
|
||||
|
||||
The user can disable this mechanism by defining `BOOST_DISABLE_ABI_HEADERS`, or
|
||||
they can define `BOOST_ABI_PREFIX` and/or `BOOST_ABI_SUFFIX` to point to their
|
||||
own prefix/suffix headers if they so wish.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Automatic library selection]
|
||||
|
||||
It is essential that users link to a build of a library which was built against
|
||||
the same runtime library that their application will be built against -if this
|
||||
does not happen then the library will not be binary compatible with their own
|
||||
code- and there is a high likelihood that their application will experience
|
||||
runtime crashes. These kinds of problems can be extremely time consuming and
|
||||
difficult to debug, and often lead to frustrated users and authors alike (simply
|
||||
selecting the right library to link against is not as easy as it seems when
|
||||
their are 6-8 of them to chose from, and some users seem to be blissfully
|
||||
unaware that there even are different runtimes available to them).
|
||||
|
||||
To solve this issue, some compilers allow source code to contain `#pragma`'s that
|
||||
instruct the linker which library to link against, all the user need do is
|
||||
include the headers they need, place the compiled libraries in their library
|
||||
search path, and the compiler and linker do the rest. Boost.config supports
|
||||
this via the header `<boost/config/auto_link.hpp>`, before including this header
|
||||
one or more of the following macros need to be defined:
|
||||
|
||||
[variablelist
|
||||
[[`BOOST_LIB_NAME`][
|
||||
Required: An identifier containing the basename of the library, for
|
||||
example 'boost_regex'.
|
||||
]]
|
||||
[[`BOOST_DYN_LINK`][
|
||||
Optional: when set link to dll rather than static library.
|
||||
]]
|
||||
[[`BOOST_LIB_DIAGNOSTIC`][
|
||||
Optional: when set the header will print out the name of the library selected
|
||||
(useful for debugging).
|
||||
]]
|
||||
]
|
||||
|
||||
If the compiler supports this mechanism, then it will be told to link against
|
||||
the appropriately named library, the actual algorithm used to mangle the name
|
||||
of the library is documented inside `<boost/config/auto_link.hpp>` and has to
|
||||
match that used to create the libraries via bjam 's install rules.
|
||||
|
||||
|
||||
[*my_library.hpp]
|
||||
|
||||
...
|
||||
//
|
||||
// Don't include auto-linking code if the user has disabled it by
|
||||
// defining BOOST_ALL_NO_LIB, or BOOST_MY_LIBRARY_NO_LIB, or if this
|
||||
// is one of our own source files (signified by BOOST_MY_LIBRARY_SOURCE):
|
||||
//
|
||||
#if !defined(BOOST_ALL_NO_LIB) && !defined(BOOST_MY_LIBRARY_NO_LIB) && !defined(BOOST_MY_LIBRARY_SOURCE)
|
||||
# define BOOST_LIB_NAME boost_my_library
|
||||
# ifdef BOOST_MY_LIBRARY_DYN_LINK
|
||||
# define BOOST_DYN_LINK
|
||||
# endif
|
||||
# include <boost/config/auto_link.hpp>
|
||||
#endif
|
||||
...
|
||||
|
||||
[*my_library.cpp]
|
||||
|
||||
// define BOOST_MY_LIBRARY_SOURCE so that the header knows that the
|
||||
// library is being built (possibly exporting rather than importing code)
|
||||
//
|
||||
#define BOOST_MY_LIBRARY_SOURCE
|
||||
|
||||
#include <boost/my_library/my_library.hpp>
|
||||
...
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
82
doc/rationale.qbk
Normal file
82
doc/rationale.qbk
Normal file
@ -0,0 +1,82 @@
|
||||
[/
|
||||
Boost.Config
|
||||
|
||||
Copyright (c) 2001 Beman Dawes
|
||||
Copyright (c) 2001 Vesa Karvonen
|
||||
Copyright (c) 2001 John Maddock
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
[#config_rationale]
|
||||
|
||||
[section Rationale]
|
||||
|
||||
The problem with many traditional "textbook" implementations of configuration
|
||||
headers (where all the configuration options are in a single "monolithic"
|
||||
header) is that they violate certain fundamental software engineering
|
||||
principles which would have the effect of making boost more fragile, more
|
||||
difficult to maintain and more difficult to use safely. You can find a
|
||||
description of the principles from the __PRINCIPLES_AND_PATTERNS_ARTICLE__.
|
||||
|
||||
[section The problem]
|
||||
|
||||
Consider a situation in which you are concurrently developing on multiple
|
||||
platforms. Then consider adding a new platform or changing the platform
|
||||
definitions of an existing platform. What happens? Everything, and this does
|
||||
literally mean everything, recompiles. Isn't it quite absurd that adding a
|
||||
new platform, which has absolutely nothing to do with previously existing
|
||||
platforms, means that all code on all existing platforms needs to be
|
||||
recompiled?
|
||||
|
||||
Effectively, there is an imposed physical dependency between platforms that
|
||||
have nothing to do with each other. Essentially, the traditional solution
|
||||
employed by configuration headers does not conform to the Open-Closed
|
||||
Principle:
|
||||
|
||||
[: [*"A module should be open for extension but closed for modification."]]
|
||||
|
||||
Extending a traditional configuration header implies modifying existing code.
|
||||
|
||||
Furthermore, consider the complexity and fragility of the platform detection
|
||||
code. What if a simple change breaks the detection on some minor platform?
|
||||
What if someone accidentally or on purpose (as a workaround for some other
|
||||
problem) defines some platform dependent macros that are used by the
|
||||
detection code? A traditional configuration header is one of the most
|
||||
volatile headers of the entire library, and more stable elements of
|
||||
Boost would depend on it. This violates the Stable Dependencies Principle:
|
||||
|
||||
[: [*"Depend in the direction of stability."]]
|
||||
|
||||
After even a minor change to a traditional configuration header on one minor
|
||||
platform, almost everything on every platform should be tested if we follow
|
||||
sound software engineering practice.
|
||||
|
||||
Another important issue is that it is not always possible to submit changes
|
||||
to `<boost/config.hpp>`. Some boost users are currently working on platforms
|
||||
using tools and libraries that are under strict Non-Disclosure Agreements.
|
||||
In this situation it is impossible to submit changes to a traditional
|
||||
monolithic configuration header, instead some method by which the user
|
||||
can insert their own configuration code must be provided.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section The solution]
|
||||
|
||||
The approach taken by boost's configuration headers is to separate
|
||||
configuration into three orthogonal parts: the compiler, the standard
|
||||
library and the platform. Each compiler/standard library/platform gets
|
||||
its own mini-configuration header, so that changes to one compiler's
|
||||
configuration (for example) does not affect other compilers. In addition
|
||||
there are measures that can be taken both to omit the compiler/standard
|
||||
library/platform detection code (so that adding support to a new platform
|
||||
does not break dependencies), or to freeze the configuration completely;
|
||||
providing almost complete protection against dependency changes.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
Reference in New Issue
Block a user