mirror of
https://github.com/boostorg/config.git
synced 2025-10-28 06:11:44 +01:00
1522 lines
85 KiB
HTML
1522 lines
85 KiB
HTML
<html>
|
||
<head>
|
||
<title></title>
|
||
<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 5.0">
|
||
</head>
|
||
<body bgcolor="#ffffff" link="#0000ff" vlink="#800080">
|
||
<p align="left"><img src="../../boost.png" alt="Boost" 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="#source">Macros for libraries with separate source code</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>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="#info_macros">informational</A> or <A href="#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="#features">feature test</A> and <A href="#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>
|
||
<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>sh ./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" sh
|
||
./configure</pre>
|
||
<p>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. <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>
|
||
<tr>
|
||
<td valign="top">BOOST_DISABLE_WIN32</td>
|
||
<td>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".</td>
|
||
</tr>
|
||
<TR>
|
||
<TD vAlign="top">BOOST_DISABLE_ABI_HEADERS</TD>
|
||
<TD>Stops boost headers from including any prefix/suffix headers that normally
|
||
control things like struct packing and alignment.</TD>
|
||
</TR>
|
||
<TR>
|
||
<TD vAlign="top">BOOST_ABI_PREFIX</TD>
|
||
<TD>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.</TD>
|
||
</TR>
|
||
<TR>
|
||
<TD vAlign="top">BOOST_ABI_SUFFIX</TD>
|
||
<TD>A suffix header to include in place of whatever boost.config would normally
|
||
select, any replacement should undo the effects of the prefix header.</TD>
|
||
</TR>
|
||
<TR>
|
||
<TD vAlign="top">BOOST_ALL_DYN_LINK</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
|
||
__declspec(dllimport) modifiers, so that the compiler knows which symbols to
|
||
look for in a dll rather than in a static library).
|
||
</P>
|
||
<P>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 vAlign="top">BOOST_WHATEVER_DYN_LINK</TD>
|
||
<TD>
|
||
<P>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).
|
||
</P>
|
||
<P>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 vAlign="top">BOOST_ALL_NO_LIB</TD>
|
||
<TD>
|
||
<P>Tells the config system not to automatically select which libraries to link
|
||
against.
|
||
</P>
|
||
<P>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 vAlign="top">BOOST_WHATEVER_NO_LIB</TD>
|
||
<TD>
|
||
<P>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.
|
||
</P>
|
||
<P>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 vAlign="top">BOOST_LIB_DIAGNOSTIC</TD>
|
||
<TD>Causes the auto-linking code to output diagnostic messages indicating the name
|
||
of the library that is selected for linking.</TD>
|
||
</TR>
|
||
<TR>
|
||
<TD vAlign="top">BOOST_LIB_TOOLSET</TD>
|
||
<TD>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".</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>BOOST_BCB_PARTIAL_SPECIALIZATION_BUG</td>
|
||
<td>Compiler</td>
|
||
<td>The compiler exibits certain partial specialisation bug - probably Borland C++
|
||
Builder specific.</td>
|
||
</tr>
|
||
<TR>
|
||
<TD vAlign="top" width="51%">BOOST_FUNCTION_SCOPE_USING_DECLARATION_BREAKS_ADL</TD>
|
||
<TD vAlign="top" width="16%">Compiler</TD>
|
||
<TD vAlign="top" width="33%">Argument dependent lookup fails if there is a using
|
||
declaration for the symbol being looked up in the current scope. For
|
||
example, <code>using boost::get_pointer;</code> prevents ADL from finding
|
||
overloads of <code>get_pointer</code> in namespaces nested inside boost (but
|
||
not elsewhere). Probably Borland specific.</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">BOOST_NO_EXCEPTION_STD_NAMESPACE</td>
|
||
<td valign="top">Standard Library</td>
|
||
<td>The standard library does not put some or all of the contents of
|
||
<exception> in namespace std.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">BOOST_NO_EXCEPTIONS</td>
|
||
<td valign="top">Compiler</td>
|
||
<td>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!</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_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>
|
||
<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_IS_ABSTRACT</TD>
|
||
<TD vAlign="top" width="16%">Compiler</TD>
|
||
<TD vAlign="top" width="33%">The C++ compiler does not support SFINAE with
|
||
abstract types, this is covered by <A href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#337">
|
||
Core Language DR337</A>, but is not part of the current standard.
|
||
Fortunately most compilers that support SFINAE also support this DR.</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. Never check for this symbol in library code; always
|
||
include <boost/limits.hpp>, which guarantees to provide <code>std::numeric_limits</code>.</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>BOOST_NO_LONG_LONG_NUMERIC_LIMITS</td>
|
||
<td>Standard library</td>
|
||
<td>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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_NO_MEMBER_FUNCTION_SPECIALIZATIONS</td>
|
||
<td>Compiler</td>
|
||
<td>The compiler does not support the specialization of individual member
|
||
functions of template classes.</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>BOOST_NO_MS_INT64_NUMERIC_LIMITS</td>
|
||
<td>Standard library</td>
|
||
<td>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.</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_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS</TD>
|
||
<TD vAlign="top" width="16%">Compiler</TD>
|
||
<TD vAlign="top" width="33%">Pointers to members don't work when used as template
|
||
parameters.</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_SFINAE</TD>
|
||
<TD vAlign="top" width="16%">Compiler</TD>
|
||
<TD vAlign="top" width="33%">The compiler does not support the "Substitution
|
||
Failure Is Not An Error" meta-programming idiom.</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>BOOST_NO_STD_WSTREAMBUF</td>
|
||
<td>Standard library</td>
|
||
<td>The standard library's implementation of std::basic_streambuf<wchar_t>
|
||
is either missing, incomplete, or buggy.</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>BOOST_NO_TEMPLATE_TEMPLATES</td>
|
||
<td>Compiler</td>
|
||
<td>The compiler does not support template template parameters.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_NO_UNREACHABLE_RETURN_DETECTION</td>
|
||
<td>Compiler</td>
|
||
<td>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.</td>
|
||
</tr>
|
||
<TR>
|
||
<TD vAlign="top" width="51%">BOOST_NO_USING_DECLARATION_OVERLOADS_FROM_TYPENAME_BASE</TD>
|
||
<TD vAlign="top" width="16%">Compiler</TD>
|
||
<TD vAlign="top" width="33%">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.</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 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).</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="51%">BOOST_NO_VOID_RETURNS</td>
|
||
<td valign="top" width="16%">Compiler</td>
|
||
<td valign="top" width="33%">The compiler does not allow a void function to return
|
||
the result of calling another void function.
|
||
<pre>void f() {}
|
||
void g() { return f(); }</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>BOOST_HAS_CLOCK_GETTIME</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX API clock_gettime.</td>
|
||
</tr>
|
||
<TR>
|
||
<TD>BOOST_HAS_DECLSPEC
|
||
</TD>
|
||
<TD>Compiler</TD>
|
||
<TD>The compiler uses __declspec(dllexport) and __declspec(dllimport) to
|
||
export/import symbols from dll's.</TD>
|
||
</TR>
|
||
<tr>
|
||
<td>BOOST_HAS_DIRENT_H</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX header <dirent.h>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_FTIME</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the Win32 API GetSystemTimeAsFileTime.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_GETTIMEOFDAY</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX API gettimeofday.</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>BOOST_HAS_LONG_LONG</td>
|
||
<td>Compiler</td>
|
||
<td>The compiler supports the long long data type.</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>BOOST_HAS_MS_INT64</td>
|
||
<td>Compiler</td>
|
||
<td>The compiler supports the __int64 data type.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_NANOSLEEP</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX API nanosleep.</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>BOOST_HAS_NRVO</td>
|
||
<td>Compiler</td>
|
||
<td>Indicated that the compiler supports the named return value optimization
|
||
(NRVO). Used to select the most efficient implementation for some function. See <a href="../../boost/operators.hpp">
|
||
boost/operators.hpp</a> for example.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">BOOST_HAS_PARTIAL_STD_ALLOCATOR</td>
|
||
<td>Standard Library</td>
|
||
<td>The standard library has a partially conforming std::allocator class, but
|
||
without any of the member templates.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_PTHREAD_DELAY_NP</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX API pthread_delay_np.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_PTHREAD_MUTEXATTR_SETTYPE</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX API pthread_mutexattr_settype.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_PTHREAD_YIELD</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX API pthread_yield.</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>BOOST_HAS_SCHED_YIELD</td>
|
||
<td>Platform</td>
|
||
<td>The platform has the POSIX API sched_yield.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_SGI_TYPE_TRAITS</td>
|
||
<td>Compiler/standard library</td>
|
||
<td>The compiler has native support for SGI style type traits.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_HAS_STDINT_H</td>
|
||
<td>Platform</td>
|
||
<td>The platform has a <stdint.h></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 workaround 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.</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_DEDUCED_TYPENAME</td>
|
||
<td valign="top" width="50%">Some compilers don't support the use of <code>typename</code>
|
||
for dependent types in deduced contexts. This macro expands to nothing on those
|
||
compilers, and <code>typename</code> elsewhere. For example, replace:<pre>template <class T> void f(T, typename T::type);</pre>
|
||
<p>with:</p>
|
||
<pre>template <class T> void f(T, BOOST_DEDUCED_TYPENAME T::type);</pre>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_STD_EXTENSION_NAMESPACE</td>
|
||
<td>The namespace used for std library extensions (hashtable classes etc).</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>BOOST_UNREACHABLE_RETURN(result)</td>
|
||
<td>Normally evaluates to nothing, but evaluates to <font face="Courier New">return
|
||
x;</font> if the compiler requires a return, even when it can never be
|
||
reached.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>BOOST_EXPLICIT_TEMPLATE_TYPE(t)<br>
|
||
BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t, v)<br>
|
||
BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t)<br>
|
||
BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t, v)<br>
|
||
</td>
|
||
<td>Some compilers silently "fold" different function template instantiations if
|
||
some of the template parameters don't appear in the function parameter list.
|
||
For instance:
|
||
<pre> #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>();
|
||
}
|
||
</pre>
|
||
incorrectly outputs <tt>"2 2 double double "</tt> 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:
|
||
<pre> template <int n>
|
||
void f(BOOST_EXPLICIT_TEMPLATE_NON_TYPE(int, n)) { ... }
|
||
|
||
template <typename T>
|
||
void g(BOOST_EXPLICIT_TEMPLATE_TYPE(T)) { ... }
|
||
</pre>
|
||
Beware that they can declare (for affected compilers) a dummy <i>defaulted</i> parameter,
|
||
so they
|
||
<br>
|
||
<br>
|
||
a) should be always invoked *at the end* of the parameter list
|
||
<br>
|
||
b) can't be used if your function template is multiply declared.
|
||
<br>
|
||
<br>
|
||
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.
|
||
</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_HAS_FACET(Type, loc)</td>
|
||
<td valign="top" width="50%">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:<pre>std::has_facet<Type>(loc);</pre>
|
||
<p>with:</p>
|
||
<pre>BOOST_HAS_FACET(Type, loc);</pre>
|
||
<p>Note do not add a std:: prefix to the front of BOOST_HAS_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">BOOST_MSVC</td>
|
||
<td valign="top"><boost/config.hpp></td>
|
||
<td valign="top">Defined if the compiler is really Microsoft Visual C++, as
|
||
opposed to one of the many other compilers that also define _MSC_VER.</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top">BOOST_INTEL</td>
|
||
<td valign="top"><boost/config.hpp></td>
|
||
<td valign="top">Defined if the compiler is an Intel compiler, takes the same
|
||
value as the compiler version macro.</td>
|
||
</tr>
|
||
<TR>
|
||
<TD vAlign="top">BOOST_WINDOWS</TD>
|
||
<TD vAlign="top"><boost/config.hpp></TD>
|
||
<TD vAlign="top">Defined if the Windows platform API is available.</TD>
|
||
</TR>
|
||
<tr>
|
||
<td>BOOST_DINKUMWARE_STDLIB</td>
|
||
<td><boost/config.hpp></td>
|
||
<td>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.</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>
|
||
<H4><A name="source"></A>Macros for libraries with separate source code</H4>
|
||
<P>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.</P>
|
||
<H5>ABI Fixing</H5>
|
||
<P>When linking against a pre-compiled library it vital that the ABI used by the
|
||
compiler when building the library <EM>matches</EM> <EM>exactly</EM> 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 would be:</P>
|
||
<PRE>#ifndef MY_INCLUDE_GUARD
|
||
#define MY_INCLUDE_GUARD
|
||
|
||
// all includes go here:
|
||
#include <boost/config.hpp>
|
||
#include <whatever>
|
||
|
||
#ifdef BOOST_HAS_ABI_HEADERS
|
||
# include BOOST_ABI_PREFIX
|
||
#endif
|
||
|
||
namespace boost{
|
||
// your code goes here
|
||
}
|
||
|
||
#ifdef BOOST_HAS_ABI_HEADERS
|
||
# include BOOST_ABI_SUFFIX
|
||
#endif
|
||
|
||
|
||
#endif // include guard
|
||
</PRE>
|
||
<P>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.</P>
|
||
<H5>Automatic library selection</H5>
|
||
<P>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).</P>
|
||
<P>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:</P>
|
||
<P>
|
||
<TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="1">
|
||
<TR>
|
||
<TD>BOOST_LIB_NAME</TD>
|
||
<TD>
|
||
Required: An identifier containing the basename of the library, for
|
||
example 'boost_regex'.</TD>
|
||
</TR>
|
||
<TR>
|
||
<TD>BOOST_DYN_LINK</TD>
|
||
<TD>Optional: when set link to dll rather than static library.</TD>
|
||
</TR>
|
||
<TR>
|
||
<TD>BOOST_LIB_DIAGNOSTIC</TD>
|
||
<TD>Optional: when set the header will print out the name of the library selected
|
||
(useful for debugging).</TD>
|
||
</TR>
|
||
</TABLE>
|
||
</P>
|
||
<P>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.</P>
|
||
<P>Typical usage would be:</P>
|
||
<PRE>//
|
||
// Don't include auto-linking code if the user has disabled it by
|
||
// defining BOOST_WHATEVER_NO_LIB, or if this is one of our own
|
||
// source files (signified by BOOST_WHATEVER_SOURCE):
|
||
//
|
||
#if !defined(BOOST_WHATEVER_NO_LIB) && !defined(BOOST_WHATEVER_SOURCE)
|
||
# define BOOST_LIB_NAME boost_whatever
|
||
# ifdef BOOST_WHATEVER_DYN_LINK
|
||
# define BOOST_DYN_LINK
|
||
# endif
|
||
# include <boost/config/auto_link.hpp>
|
||
#endif
|
||
</PRE>
|
||
<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>
|
||
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>
|
||
If configuration information can be deduced from standard headers such as
|
||
<climits>, use those standard headers rather than
|
||
<boost/config.hpp>.
|
||
<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>
|
||
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>
|
||
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>
|
||
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 .ipp 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.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:</p>
|
||
<pre>namespace boost_no_foo{
|
||
|
||
int test()
|
||
{
|
||
// test code goes here:
|
||
//
|
||
return 0;
|
||
}
|
||
|
||
}</pre>
|
||
<p>
|
||
Once the test code is in place, build and run the program "generate.cpp" 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 Jamfile, and the config_test.cpp test program. 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.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 <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>
|