mirror of
https://github.com/boostorg/config.git
synced 2025-11-02 16:52:20 +01:00
1275 lines
55 KiB
HTML
1275 lines
55 KiB
HTML
<html>
|
||
|
||
<head>
|
||
<meta http-equiv="Content-Type"
|
||
content="text/html; charset=iso-8859-1">
|
||
<meta name="Template"
|
||
content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
|
||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||
<title></title>
|
||
</head>
|
||
|
||
<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080">
|
||
|
||
<p align="left"><img src="../../c++boost.gif" width="277" height="86"></p>
|
||
|
||
<h1 align="center">Boost Configuration Reference</h1>
|
||
|
||
<h2>Contents</h2>
|
||
|
||
<pre><a href="#configuring">Configuring Boost for Your Platform</a>
|
||
<a href="#default_config">Using the default boost configuration
|
||
</a> <a href="#header">The <boost\config.hpp> header</a>
|
||
<a href="#config_script">Using the configure script</a>
|
||
<a href="#user_settable">User settable options</a>
|
||
<a href="#advanced_config">Advanced configuration usage</a>
|
||
<a href="#testing">Testing the boost configuration</a>
|
||
<a href="#macro_ref">Boost Macro Reference</a>
|
||
<a href="#defects">Macros that describe defects</a>
|
||
<a href="#features">Macros that describe optional features</a>
|
||
<a href="#helpers">Boost Helper Macros</a>
|
||
<a href="#info_macros">Boost Informational Macros</a>
|
||
<a href="#guidelines">Guidelines for Boost Authors</a>
|
||
<a href="#defect_guidelines">Adding New Defect Macros</a>
|
||
<a href="#feature_guidelines">Adding New Feature Test Macros</a>
|
||
<a href="#modify_guidelines">Modifying the Boost Configuration Headers</a>
|
||
<a href="#rationale">Rationale</a>
|
||
<a href="#Acknowledgements">Acknowledgements</a></pre>
|
||
|
||
<h2><a name="configuring"></a>Configuring Boost for Your Platform</h2>
|
||
|
||
<h4><a name="default_config"></a>Using the default boost
|
||
configuration</h4>
|
||
|
||
<p>Boost is 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://www.stlport.org"> 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">
|
||
Tracker</a> and submitting a support request. </p>
|
||
|
||
<h4>The <a href="../../boost/config.hpp"><boost/config.hpp></a> <a name="header">header</a></h4>
|
||
|
||
<p>Boost library implementations access configuration macros via <code> #include <boost/config.hpp></code>. </p>
|
||
|
||
<p>Boost library users are never required to <code> #include <boost/config.hpp></code>,
|
||
and are discouraged from doing so on their own. It is an implementation detail
|
||
which is subject to change, and thus should not be depended upon by users. </p>
|
||
|
||
<h4><a name="config_script">Using the configure script</a></h4>
|
||
|
||
<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
|
||
<boost-root>/libs/config/ and type:</p>
|
||
|
||
<pre>./configure</pre>
|
||
|
||
<p>you will see a list of the items being checked as the script
|
||
works it 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 then
|
||
you will need to set one or more of the following environment
|
||
variables:</p>
|
||
|
||
<table border="1" cellpadding="7" cellspacing="1" width="624">
|
||
<tr>
|
||
<td valign="top" width="50%"><p align="center"><b>Variable</b></p>
|
||
</td>
|
||
<td valign="top" width="50%"><p align="center"><b>Description</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">CXX</td>
|
||
<td valign="top" width="50%">The name of the compiler,
|
||
for example "c++".</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">CXXFLAGS</td>
|
||
<td valign="top" width="50%">The compiler flags to use,
|
||
for example "-O2".</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">LDFLAGS</td>
|
||
<td valign="top" width="50%">The linker flags to use, for
|
||
example "-L/mypath".</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">LIBS</td>
|
||
<td valign="top" width="50%">Any libraries to link in,
|
||
for example -lpthread.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p>For example to run the configure script with HP aCC, you might
|
||
use something like:</p>
|
||
|
||
<pre>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"
|
||
./configure</pre>
|
||
|
||
<p>However you run the configure script, when it finishes you
|
||
will find a new header - user.hpp - located in the <a
|
||
href="user.hpp"><boost-root>/libs/config/</a> directory. <b><i>Note
|
||
that configure does not install this header into your boost
|
||
include path by default.</i></b> 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">user.hpp</a> (located
|
||
under <boost-root>/boost/config/). There are two ways you
|
||
can use this header:</p>
|
||
|
||
<p>Option 1: copy the header into <boost-root>/boost/config/
|
||
so that it replaces the default <a
|
||
href="../../boost/config/user.hpp">user.hpp</a> 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 user.hpp to the cvs
|
||
repository (something you will not be thanked for!).</p>
|
||
|
||
<p>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-root>/boost/config/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.</p>
|
||
|
||
<h4><a name="user_settable"></a>User settable options</h4>
|
||
|
||
<p>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: </p>
|
||
|
||
<table border="1" cellpadding="7" cellspacing="1" width="100%">
|
||
<tr>
|
||
<td valign="top" width="48%"><p align="center"><b>Macro</b></p>
|
||
</td>
|
||
<td valign="top" width="52%"><p align="center"><b>Description</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_USER_CONFIG</td>
|
||
<td valign="top" width="52%">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">boost/config/user.hpp</a>>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_COMPILER_CONFIG</td>
|
||
<td valign="top" width="52%">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">boost/config/compiler/gcc.hpp</a>".</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_STDLIB_CONFIG</td>
|
||
<td valign="top" width="52%">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 "<a href="../../boost/config/stdlib/stlport.hpp">boost/config/stdlib/stlport.hpp</a>".</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_PLATFORM_CONFIG</td>
|
||
<td valign="top" width="52%">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 "<a
|
||
href="../../boost/config/platform/linux.hpp">boost/config/platform/linux.hpp</a>".</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_NO_COMPILER_CONFIG</td>
|
||
<td valign="top" width="52%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_NO_STDLIB_CONFIG</td>
|
||
<td valign="top" width="52%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_NO_PLATFORM_CONFIG</td>
|
||
<td valign="top" width="52%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_NO_CONFIG</td>
|
||
<td valign="top" width="52%">Equivalent to defining all
|
||
of BOOST_NO_COMPILER_CONFIG, BOOST_NO_STDLIB_CONFIG and
|
||
BOOST_NO_PLATFORM_CONFIG.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">BOOST_STRICT_CONFIG</td>
|
||
<td>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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">BOOST_ASSERT_CONFIG</td>
|
||
<td>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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_DISABLE_THREADS</td>
|
||
<td valign="top" width="52%">When defined, disables
|
||
threading support, even if the compiler in its current
|
||
translation mode supports multiple threads.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h4><a name="advanced_config"></a>Advanced configuration usage</h4>
|
||
|
||
<p>By setting various macros on the compiler command line or by
|
||
editing <<a href="../../boost/config/user.hpp">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">boost/config/user.hpp</a>>
|
||
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. </p>
|
||
|
||
<p>Next the compiler, standard library, and platform
|
||
configuration files are included. These are included via macros (BOOST_COMPILER_CONFIG
|
||
etc, <a href="#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 BOOST_NO_XXX
|
||
macro is set (for example BOOST_NO_COMPILER_CONFIG to disable
|
||
including any compiler configuration file - <a
|
||
href="#user_settable">see user settable macros</a>). </p>
|
||
|
||
<p>Finally the boost configuration header, includes <<a
|
||
href="../../boost/config/suffix.hpp">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>
|
||
|
||
<p><u>Example 1, creating our own frozen configuration.</u></p>
|
||
|
||
<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">boost/config/compiler/visualc.hpp</a>>
|
||
for the compiler, <<a
|
||
href="../../boost/config/stdlib/stlport.hpp">boost/config/stdlib/stlport.hpp</a>>
|
||
for the standard library, and <<a
|
||
href="../../boost/config/platform/win32.hpp">boost/config/platform/win32.hpp</a>>
|
||
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 <<a
|
||
href="../../boost/config/user.hpp">boost/config/user.hpp</a>>
|
||
and edit the following defines:</p>
|
||
|
||
<pre>#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"</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>
|
||
|
||
<p><u>Example 2: skipping files that you don't need.</u></p>
|
||
|
||
<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
|
||
BOOST_NO_COMPILER_CONFIG either on the command line, or in
|
||
<boost/config/user.hpp>, 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 compiled, and the second that you have
|
||
removed a dependency on two boost headers.</p>
|
||
|
||
<p><u>Example 3: using configure script to freeze the boost
|
||
configuration.</u></p>
|
||
|
||
<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="#config_script">see using the configure script</a> for more
|
||
details.</p>
|
||
|
||
<h4><a name="testing"></a>Testing the boost configuration</h4>
|
||
|
||
<p>The boost configuration library provides a full set of
|
||
regression test programs under the <boost-root>/libs/config/test/
|
||
sub-directory:</p>
|
||
|
||
<table border="1" cellpadding="7" cellspacing="1" width="100%">
|
||
<tr>
|
||
<td valign="top" width="50%"><p align="center"><b>File</b></p>
|
||
</td>
|
||
<td valign="top" width="50%"><p align="center"><b>Description</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">config_info.cpp</td>
|
||
<td valign="top" width="50%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">config_test.cpp</td>
|
||
<td valign="top" width="50%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">limits_test.cpp</td>
|
||
<td valign="top" width="50%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">no_*pass.cpp</td>
|
||
<td valign="top" width="50%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">no_*fail.cpp</td>
|
||
<td valign="top" width="50%">Individual compiler defect
|
||
test files. Each of these should <i>not</i> 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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">has_*pass.cpp</td>
|
||
<td valign="top" width="50%">Individual feature test
|
||
files. If one of these does <i>not</i> compile then the
|
||
corresponding BOOST_HAS_XXX macro is defined when it
|
||
should not be - see each test file for specific details.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">has_*fail.cpp</td>
|
||
<td valign="top" width="50%">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.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<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">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>
|
||
|
||
<pre>./configure --enable-test</pre>
|
||
|
||
<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 config_info.cpp, and the pass/fail
|
||
test results.</p>
|
||
|
||
<h2><a name="macro_ref"></a>Boost Macro Reference</h2>
|
||
|
||
<h4><a name="defects"></a>Macros that describe defects:</h4>
|
||
|
||
<p>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.</p>
|
||
|
||
<table border="1" cellpadding="7" cellspacing="1" width="100%">
|
||
<tr>
|
||
<td valign="top" width="51%"><p align="center"><b>Macro</b></p>
|
||
</td>
|
||
<td valign="top" width="16%"><p align="center"><b>Section</b></p>
|
||
</td>
|
||
<td valign="top" width="33%"><p align="center"><b>Description</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Compiler does not implement
|
||
argument-dependent lookup (also named Koenig lookup); see
|
||
std::3.4.2 [basic.koenig.lookup]</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_AUTO_PTR</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">If the compiler / library
|
||
supplies non-standard or broken std::auto_ptr.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_CTYPE_FUNCTIONS</td>
|
||
<td valign="top" width="16%">Platform</td>
|
||
<td valign="top" width="33%">The Platform does not
|
||
provide functions for the character-classifying operations
|
||
<ctype.h> and <cctype>, only macros.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_CV_SPECIALIZATIONS</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">If template specialisations
|
||
for cv-qualified types conflict with a specialisation for
|
||
a cv-unqualififed type.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_CV_VOID_SPECIALIZATIONS</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">If template specialisations
|
||
for cv-void types conflict with a specialisation for void.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_CWCHAR</td>
|
||
<td valign="top" width="16%">Platform</td>
|
||
<td valign="top" width="33%">The Platform does not
|
||
provide <wchar.h> and <cwchar>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_CWCTYPE</td>
|
||
<td valign="top" width="16%">Platform</td>
|
||
<td valign="top" width="33%">The Platform does not
|
||
provide <wctype.h> and <cwctype>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_DEPENDENT_NESTED_DERIVATIONS</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">The compiler fails to
|
||
compile a nested class that has a dependent base class:<pre>template<typename T>
|
||
struct foo : {
|
||
template<typename U>
|
||
struct bar : public U {};
|
||
};</pre>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_DEPENDENT_TYPES_IN_TEMPLATE_VALUE_PARAMETERS</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Template value parameters
|
||
cannot have a dependent type, for example:<pre>template<class T, typename T::type value>
|
||
class X { ... };</pre>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_EXPLICIT_FUNCTION_TEMPLATE_ARGUMENTS</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Can only use deduced
|
||
template arguments when calling function template
|
||
instantiations.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_INCLASS_MEMBER_INITIALIZATION</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Compiler violates std::9.4.2/4.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_INTRINSIC_WCHAR_T</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_LIMITS</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The C++ implementation does
|
||
not provide the <limits> header.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">Constants such as
|
||
numeric_limits<T>::is_signed are not available for
|
||
use at compile-time.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_MEMBER_TEMPLATE_KEYWORD</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">If the compiler supports
|
||
member templates, but not the template keyword when
|
||
accessing member template classes.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_MEMBER_TEMPLATE_FRIENDS</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Member template friend
|
||
syntax ("template<class P> friend class frd;")
|
||
described in the C++ Standard, 14.5.3, not supported.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_MEMBER_TEMPLATES</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Member template functions
|
||
not fully supported.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_OPERATORS_IN_NAMESPACE</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Compiler requires inherited
|
||
operator friend functions to be defined at namespace
|
||
scope, then using'ed to boost. Probably GCC specific. See
|
||
<a href="../../boost/operators.hpp">boost/operators.hpp</a>
|
||
for example.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_POINTER_TO_MEMBER_CONST</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">The compiler does not
|
||
correctly handle pointers to const member functions,
|
||
preventing use of these in overloaded function templates.
|
||
See <a href="../../boost/functional.hpp">boost/functional.hpp</a>
|
||
for example.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_PRIVATE_IN_AGGREGATE</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">The compiler misreads 8.5.1,
|
||
treating classes as non-aggregate if they contain private
|
||
or protected member functions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_ALLOCATOR</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The C++ standard library
|
||
does not provide a standards conforming std::allocator.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_DISTANCE</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The platform does not have a
|
||
conforming version of std::distance.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_ITERATOR</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The C++ implementation fails
|
||
to provide the std::iterator class.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_ITERATOR_TRAITS</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The compiler does not
|
||
provide a standard compliant implementation of std::iterator_traits.
|
||
Note that the compiler may still have a non-standard
|
||
implementation.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_LOCALE</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The standard library lacks
|
||
std::locale.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_MESSAGES</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The standard library lacks a
|
||
conforming std::messages facet.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_MIN_MAX</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The C++ standard library
|
||
does not provide the min() and max() template functions
|
||
that should be in <algorithm>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">BOOST_NO_STD_OUTPUT_ITERATOR_ASSIGN</td>
|
||
<td valign="top">Standard library</td>
|
||
<td valign="top">Defined if the standard library's output
|
||
iterators are not assignable.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_USE_FACET</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The standard library lacks a
|
||
conforming std::use_facet.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STD_WSTRING</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The standard library lacks
|
||
std::wstring.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STDC_NAMESPACE</td>
|
||
<td valign="top" width="16%">Compiler/Platform</td>
|
||
<td valign="top" width="33%">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...</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_STRINGSTREAM</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The C++ implementation does
|
||
not provide the <sstream> header.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_SWPRINTF</td>
|
||
<td valign="top" width="16%">Platform</td>
|
||
<td valign="top" width="33%">The platform does not have a
|
||
conforming version of swprintf.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">Class template partial
|
||
specialization (14.5.4 [temp.class.spec]) not supported.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_TEMPLATED_ITERATOR_CONSTRUCTORS</td>
|
||
<td valign="top" width="16%">Standard library</td>
|
||
<td valign="top" width="33%">The standard library does
|
||
not provide templated iterator constructors for its
|
||
containers.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_USING_TEMPLATE</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">The compiler will not accept
|
||
a using declaration that imports a template from the
|
||
global namespace into a named namespace. Probably Borland
|
||
specific.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_WEAK_FUNCTION_TEMPLATE_ORDERING</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">The compiler does not
|
||
perform function template ordering or its function
|
||
template ordering is incorrect. <pre>template<typename T> void f(T); // #1
|
||
template<typename T, typename U> void f(T (*)(U)); // #2
|
||
|
||
void bar(int);
|
||
|
||
f(&bar); // should choose #2.</pre>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h4><a name="features"></a>Macros that describe optional features:</h4>
|
||
|
||
<p>The following macros describe features that are not required
|
||
by the C++ standard. The macro is only defined if the feature is
|
||
present.</p>
|
||
|
||
<table border="1" cellpadding="7" cellspacing="1" width="100%">
|
||
<tr>
|
||
<td valign="top" width="48%"><p align="center"><b>Macro</b></p>
|
||
</td>
|
||
<td valign="top" width="15%"><p align="center"><b>Section</b></p>
|
||
</td>
|
||
<td valign="top" width="37%"><p align="center"><b>Description</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_BETHREADS</td>
|
||
<td valign="top" width="15%">Platform</td>
|
||
<td valign="top" width="37%">The platform supports BeOS
|
||
style threads.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_HASH</td>
|
||
<td valign="top" width="15%">Standard library</td>
|
||
<td valign="top" width="37%">The C++ implementation
|
||
provides the (SGI) hash_set or hash_map classes.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_MACRO_USE_FACET</td>
|
||
<td valign="top" width="15%">Standard library</td>
|
||
<td valign="top" width="37%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_NL_TYPES_H</td>
|
||
<td valign="top" width="15%">Platform</td>
|
||
<td valign="top" width="37%">The platform has an
|
||
<nl_types.h>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_PTHREADS</td>
|
||
<td valign="top" width="15%">Platform</td>
|
||
<td valign="top" width="37%">The platform support POSIX
|
||
style threads.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_SLIST</td>
|
||
<td valign="top" width="15%">Standard library</td>
|
||
<td valign="top" width="37%">The C++ implementation
|
||
provides the (SGI) slist class.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_STLP_USE_FACET</td>
|
||
<td valign="top" width="15%">Standard library</td>
|
||
<td valign="top" width="37%">The standard library lacks a
|
||
conforming std::use_facet, but has a workaound class-version
|
||
that does the job. This is primarily for the STLport std
|
||
lib.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_THREADS</td>
|
||
<td valign="top" width="15%">Platform/compiler</td>
|
||
<td valign="top" width="37%">Defined if the compiler, in
|
||
its current translation mode, supports multiple threads
|
||
of execution.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_TWO_ARG_USE_FACET</td>
|
||
<td valign="top" width="15%">Standard library</td>
|
||
<td valign="top" width="37%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_UNISTD_H</td>
|
||
<td valign="top" width="15%">Platform</td>
|
||
<td valign="top" width="37%">The Platform provides
|
||
<unistd.h>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_WINTHREADS</td>
|
||
<td valign="top" width="15%">Platform</td>
|
||
<td valign="top" width="37%">The platform supports MS
|
||
Windows style threads.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_MSVC_STD_ITERATOR</td>
|
||
<td valign="top" width="15%">Standard library</td>
|
||
<td valign="top" width="37%">Microsoft's broken version
|
||
of std::iterator is being used. This implies that std::iterator
|
||
takes no more than two template parameters, and that std::reverse_iterator
|
||
takes at least two template parameters.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_MSVC6_MEMBER_TEMPLATES</td>
|
||
<td valign="top" width="15%">Compiler</td>
|
||
<td valign="top" width="37%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="48%">BOOST_HAS_STDINT_H</td>
|
||
<td valign="top" width="15%">Platform</td>
|
||
<td valign="top" width="37%">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).</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h4><a name="helpers"></a>Boost Helper Macros</h4>
|
||
|
||
<p>The following macros are either simple helpers, or macros that
|
||
provide workarounds for compiler/standard library defects.</p>
|
||
|
||
<table border="1" cellpadding="7" cellspacing="1" width="100%">
|
||
<tr>
|
||
<td valign="top" width="50%"><p align="center"><b>Macro</b></p>
|
||
</td>
|
||
<td valign="top" width="50%"><p align="center"><b>Description</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">BOOST_STATIC_CONSTANT(Type,
|
||
assignment)</td>
|
||
<td valign="top" width="50%">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:<pre>struct foo{
|
||
static const int value = 2;
|
||
};</pre>
|
||
<p>use:</p>
|
||
<pre>struct foo{
|
||
BOOST_STATIC_CONSTANT(int, value = 2);
|
||
};</pre>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">BOOST_USE_FACET(Type, loc)</td>
|
||
<td valign="top" width="50%">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:<pre>std::use_facet<Type>(loc);</pre>
|
||
<p>with:</p>
|
||
<pre>BOOST_USE_FACET(Type, loc);</pre>
|
||
<p>Note do not add a std:: prefix to the front of
|
||
BOOST_USE_FACET.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">BOOST_NESTED_TEMPLATE</td>
|
||
<td valign="top" width="50%">Member templates are
|
||
supported by some compilers even though they can't use
|
||
the A::template member<U> syntax, as a workaround
|
||
replace:<pre>typedef typename A::template rebind<U> binder;</pre>
|
||
<p>with:</p>
|
||
<pre>typedef typename A::BOOST_NESTED_TEMPLATE rebind<U> binder;</pre>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">BOOST_STRINGIZE(X)</td>
|
||
<td valign="top" width="50%">Converts the parameter X to
|
||
a string after macro replacement on X has been performed.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">BOOST_JOIN(X,Y)</td>
|
||
<td valign="top" width="50%">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__.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h4><a name="info_macros"></a>Boost Informational Macros</h4>
|
||
|
||
<p>The following macros describe boost features; these are the
|
||
generally speaking the only boost macros that should be tested in
|
||
user code.</p>
|
||
|
||
<table border="1" cellpadding="7" cellspacing="1" width="100%">
|
||
<tr>
|
||
<td valign="top" width="33%"><p align="center"><b>Macro</b></p>
|
||
</td>
|
||
<td valign="top" width="33%"><p align="center"><b>Header</b></p>
|
||
</td>
|
||
<td valign="top" width="33%"><p align="center"><b>Description</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="33%">BOOST_VERSION</td>
|
||
<td valign="top" width="33%"><boost/version.hpp></td>
|
||
<td valign="top" width="33%">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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="33%">BOOST_NO_INT64_T</td>
|
||
<td valign="top" width="33%"><boost/cstdint.hpp><p><boost/stdint.h></p>
|
||
</td>
|
||
<td valign="top" width="33%">Defined if there are no 64-bit
|
||
integral types: int64_t, uint64_t etc.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="33%">BOOST_NO_INTEGRAL_INT64_T</td>
|
||
<td valign="top" width="33%"><boost/cstdint.hpp><p><boost/stdint.h></p>
|
||
</td>
|
||
<td valign="top" width="33%">Defined if int64_t as
|
||
defined by <boost/cstdint.hpp> is not usable in
|
||
integral constant expressions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="33%">BOOST_NO_WREGEX</td>
|
||
<td valign="top" width="33%"><boost/regex.hpp></td>
|
||
<td valign="top" width="33%">Defined if the regex library
|
||
does not support wide character regular expressions.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="33%">BOOST_COMPILER</td>
|
||
<td valign="top" width="33%"><boost/config.hpp></td>
|
||
<td valign="top" width="33%">Defined as a string
|
||
describing the name and version number of the compiler in
|
||
use. Mainly for debugging the configuration.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="33%">BOOST_STDLIB</td>
|
||
<td valign="top" width="33%"><boost/config.hpp></td>
|
||
<td valign="top" width="33%">Defined as a string
|
||
describing the name and version number of the standard
|
||
library in use. Mainly for debugging the configuration.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="33%">BOOST_PLATFORM</td>
|
||
<td valign="top" width="33%"><boost/config.hpp></td>
|
||
<td valign="top" width="33%">Defined as a string
|
||
describing the name of the platform. Mainly for debugging
|
||
the configuration.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h2><a name="guidelines"></a></h2>
|
||
|
||
<h2>Guidelines for Boost Authors</h2>
|
||
|
||
<p>The <a href="../../boost/config.hpp">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>
|
||
|
||
<ul>
|
||
<li>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). </li>
|
||
<li>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. </li>
|
||
<li>If configuration information can be deduced from standard
|
||
headers such as <climits>, use those standard
|
||
headers rather than <boost/config.hpp>. </li>
|
||
<li>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. </li>
|
||
<li>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. </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>
|
||
|
||
<h4><a name="defect_guidelines"></a>Adding New Defect Macros</h4>
|
||
|
||
<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 BOOST_NO_SOMETHING 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 .cxx file with the
|
||
following comments near the top:</p>
|
||
|
||
<pre>// MACRO: BOOST_NO_FOO
|
||
// TITLE: foo
|
||
// DESCRIPTION: If the compiler fails to support foo</pre>
|
||
|
||
<p>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.cxx", 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:</p>
|
||
|
||
<pre>namespace boost_no_foo{
|
||
|
||
int test()
|
||
{
|
||
// test code goes here:
|
||
//
|
||
return 0;
|
||
}
|
||
|
||
}</pre>
|
||
|
||
<p>Once the test code is in place, run the shell script "generate"
|
||
that you will find in the boost-root/libs/config/tools/ directory.
|
||
This generates two .cpp test files from the new test code, and
|
||
adds the tests to the regression test script, and the config_test.cpp
|
||
test program. If you can't run shell scripts on your platform
|
||
then post a message on the boost mailing list, and someone will
|
||
run it for you. Finally add a new entry to config_info.cpp so
|
||
that the new macro gets printed out when that program is run.</p>
|
||
|
||
<h4><a name="feature_guidelines"></a>Adding New Feature Test
|
||
Macros</h4>
|
||
|
||
<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 BOOST_HAS_FOO, and name
|
||
the test file "boost_has_foo.cxx". 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 <a
|
||
href="../../boost/config/suffix.hpp">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 <unistd.h>).</p>
|
||
|
||
<h4><a name="modify_guidelines"></a>Modifying the Boost
|
||
Configuration Headers</h4>
|
||
|
||
<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">boost/config.hpp</a>>
|
||
should never change, don't alter this file.</p>
|
||
|
||
<p><<a href="../../boost/config/user.hpp">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">libs/config/tools/configure.in</a> as
|
||
well.</p>
|
||
|
||
<p><<a href="../../boost/config/suffix.hpp">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">boost/config/select_compiler_config.hpp</a>>,
|
||
<<a href="../../boost/config/select_platform_config.hpp">boost/config/select_platform_config.hpp</a>>
|
||
and <<a href="../../boost/config/select_stdlib_config.hpp">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>
|
||
|
||
<h2><a name="rationale"></a>Rationale</h2>
|
||
|
||
<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/publications/Principles%20and%20Patterns.PDF">following
|
||
article</a>.</p>
|
||
|
||
<h4>The problem</h4>
|
||
|
||
<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>
|
||
|
||
<p><b><i>"A module should be open for extension but closed
|
||
for modification."</i></b></p>
|
||
|
||
<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>
|
||
|
||
<p><b><i>"Depend in the direction of stability."</i></b></p>
|
||
|
||
<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 <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.</p>
|
||
|
||
<h4>The solution</h4>
|
||
|
||
<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
|
||
change to one compiler's configuration (for example) does not
|
||
effect 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>
|
||
|
||
<h2><a name="Acknowledgements"></a>Acknowledgements</h2>
|
||
|
||
<p>Beman Dawes provided the original config.hpp and part of this
|
||
document. Vesa Karvonen provided a description of the principles
|
||
(see <a href="#rationale">rationale</a>) 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.</p>
|
||
|
||
<p> </p>
|
||
|
||
<hr>
|
||
|
||
<p><EFBFBD> Beman Dawes 2001</p>
|
||
|
||
<p><EFBFBD> Vesa Karvonen 2001</p>
|
||
|
||
<p><EFBFBD> John Maddock 2001</p>
|
||
|
||
<p> </p>
|
||
|
||
<p> </p>
|
||
|
||
<p> </p>
|
||
|
||
<p> </p>
|
||
|
||
<p> </p>
|
||
</body>
|
||
</html>
|