<aname="boost_config.configuring_boost_for_your_platform"></a><ahref="index.html#boost_config.configuring_boost_for_your_platform"title="Configuring Boost for Your Platform">Configuring
<aname="boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration"></a><ahref="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration"title="Using the default boost configuration">Using
Boost <ahref="boost_config/boost_macro_reference.html#config_info_macros">informational</a> or <ahref="boost_config/boost_macro_reference.html#config_helpers">helper</a>
<aname="boost_config.configuring_boost_for_your_platform.using_the_configure_script"></a><ahref="index.html#boost_config.configuring_boost_for_your_platform.using_the_configure_script"title="Using the configure script">Using
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 <spanclass="emphasis"><em><boost-root></em></span><codeclass="computeroutput"><spanclass="special">/</span><spanclass="identifier">libs</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span></code>
you will see a list of the items being checked as the script works its way
through the regression tests. Note that the configure script only really
auto-detects your compiler if it's called g++, c++ or CC. If you are using
some other compiler you will need to set one or more of the following environment
variables:
</p>
<divclass="informaltable"><tableclass="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Variable
</p>
</th>
<th>
<p>
Description
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
CXX
</p>
</td>
<td>
<p>
The name of the compiler, for example <codeclass="computeroutput"><spanclass="identifier">c</span><spanclass="special">++</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
CXXFLAGS
</p>
</td>
<td>
<p>
The compiler flags to use, for example <codeclass="computeroutput"><spanclass="special">-</span><spanclass="identifier">O2</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
LDFLAGS
</p>
</td>
<td>
<p>
The linker flags to use, for example <codeclass="computeroutput"><spanclass="special">-</span><spanclass="identifier">L</span><spanclass="special">/</span><spanclass="identifier">mypath</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
LIBS
</p>
</td>
<td>
<p>
Any libraries to link in, for example <codeclass="computeroutput"><spanclass="special">-</span><spanclass="identifier">lpthread</span></code>.
</p>
</td>
</tr>
</tbody>
</table></div>
<p>
For example to run the configure script with HP aCC, you might use something
However you run the configure script, when it finishes you will find a new
header -<codeclass="computeroutput"><spanclass="identifier">user</span><spanclass="special">.</span><spanclass="identifier">hpp</span></code>- located in the <spanclass="emphasis"><em><boost-root></em></span><codeclass="computeroutput"><spanclass="special">/</span><spanclass="identifier">libs</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span></code>
directory. <spanclass="bold"><strong>Note that configure does not install this
header into your boost include path by default</strong></span>. This header contains
all the options generated by the configure script, plus a header-section
that contains the user settable options from the default version of <ahref="../../../../boost/config/user.hpp"target="_top"><boost/config/user.hpp></a>
(located under <spanclass="emphasis"><em><boost-root></em></span><codeclass="computeroutput"><spanclass="special">/</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span></code>).
There are two ways you can use this header:
</p>
<divclass="itemizedlist"><ultype="disc">
<li>
<spanclass="bold"><strong>Option 1:</strong></span> copy the header into <spanclass="emphasis"><em><boost-root></em></span><codeclass="computeroutput"><spanclass="special">/</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span></code> so that it replaces the default user.hpp
provided by boost. This option allows only one configure-generated setup;
boost developers should avoid this option, as it incurs the danger of accidentally
committing a configure-modified <ahref="../../../../boost/config/user.hpp"target="_top"><boost/config/user.hpp></a>
to the cvs repository (something you will not be thanked for!).
</li>
<li>
<spanclass="bold"><strong>Option 2:</strong></span> give the header a more memorable
name, and place it somewhere convenient; then, define the macro <codeclass="computeroutput"><spanclass="identifier">BOOST_USER_CONFIG</span></code> to point to it. For
example create a new sub-directory <spanclass="emphasis"><em><boost-root></em></span><codeclass="computeroutput"><spanclass="special">/</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span></code><codeclass="computeroutput"><spanclass="identifier">user</span><spanclass="special">/</span></code>, and copy the header there; for example
as <codeclass="computeroutput"><spanclass="identifier">multithread</span><spanclass="special">-</span><spanclass="identifier">gcc</span><spanclass="special">-</span><spanclass="identifier">config</span><spanclass="special">.</span><spanclass="identifier">hpp</span></code>. Then, when compiling add the command
line option: <codeclass="computeroutput"><spanclass="special">-</span><spanclass="identifier">DBOOST_USER_CONFIG</span><spanclass="special">=</span><spanclass="string">"<boost/config/user/multithread-gcc-config.hpp>"</span></code>,
and boost will use the new configuration header. This option allows you
to generate more than one configuration header, and to keep them separate
from the boost source - so that updates to the source do not interfere
and at the start of a configure-generated <codeclass="computeroutput"><spanclass="identifier">user</span><spanclass="special">.</span><spanclass="identifier">hpp</span></code> header.
You can define these on the command line, or by editing <codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">user</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code>, they are listed in the following table:
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 <ahref="../../../../boost/config/user.hpp"target="_top"><codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">user</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code></a>.
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 <ahref="../../../../boost/config/compiler/gcc.hpp"target="_top"><codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">compiler</span><spanclass="special">/</span><spanclass="identifier">gcc</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code></a>.
to <ahref="../../../../boost/config/stdlib/stlport.hpp"target="_top"><codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">stdlib</span><spanclass="special">/</span><spanclass="identifier">stlport</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code></a>.
to <ahref="../../../../boost/config/platform/linux.hpp"target="_top"><codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">platform</span><spanclass="special">/</span><spanclass="identifier">linux</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code></a>.
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 <codeclass="computeroutput"><spanclass="identifier">BOOST_USER_CONFIG</span></code>), has had any
options necessary added to it, for example by an autoconf generated
When defined, disables the use of Win32 specific API's, even when
these are available. Also has the effect of setting <codeclass="computeroutput"><spanclass="identifier">BOOST_DISABLE_THREADS</span></code> unless <codeclass="computeroutput"><spanclass="identifier">BOOST_HAS_PTHREADS</span></code> is set. This
option may be set automatically by the config system when it detects
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 <codeclass="computeroutput"><spanclass="identifier">__declspec</span><spanclass="special">(</span><spanclass="identifier">dllimport</span><spanclass="special">)</span></code> modifiers, so that the compiler
knows which symbols to look for in a dll rather than in a static
library). Note that there may be some libraries that can only be
statically linked (Boost.Test for example) and others which may only
be dynamically linked (Boost.Threads for example), in these cases
Forces library "whatever" to be linked as a dll rather
than a static library on Microsoft Windows: replace the <spanclass="emphasis"><em>WHATEVER</em></span>
part of the macro name with the name of the library that you want
to dynamically link to, for example use <codeclass="computeroutput"><spanclass="identifier">BOOST_DATE_TIME_DYN_LINK</span></code>
or <codeclass="computeroutput"><spanclass="identifier">BOOST_REGEX_DYN_LINK</span></code>
etc (this macro is used to turn on <codeclass="computeroutput"><spanclass="identifier">__declspec</span><spanclass="special">(</span><spanclass="identifier">dllimport</span><spanclass="special">)</span></code> modifiers, so that the compiler
knows which symbols to look for in a dll rather than in a static
library). Note that there may be some libraries that can only be
statically linked (Boost.Test for example) and others which may only
be dynamically linked (Boost.Threads for example), in these cases
Tells the config system not to automatically select which library
to link against for library "whatever", replace <spanclass="emphasis"><em>WHATEVER</em></span>
in the macro name with the name of the library; for example <codeclass="computeroutput"><spanclass="identifier">BOOST_DATE_TIME_NO_LIB</span></code> or <codeclass="computeroutput"><spanclass="identifier">BOOST_REGEX_NO_LIB</span></code>. Normally if
a compiler supports <codeclass="computeroutput"><spanclass="preprocessor">#pragma</span>
<spanclass="identifier">lib</span></code>, then the correct library
build variant will be automatically selected and linked against,
simply by the act of including one of that library's headers. This
3: using configure script to freeze the boost configuration</a></span></dt>
</dl></div>
<p>
By setting various macros on the compiler command line or by editing <ahref="../../../../boost/config/user.hpp"target="_top"><boost/config/user.hpp></a>,
the boost configuration setup can be optimised in a variety of ways.
</p>
<p>
Boost's configuration is structured so that the user-configuration is included
first (defaulting to <ahref="../../../../boost/config/user.hpp"target="_top"><boost/config/user.hpp></a>
if <codeclass="computeroutput"><spanclass="identifier">BOOST_USER_CONFIG</span></code> is not
defined). This sets up any user-defined policies, and gives the user-configuration
a chance to influence what happens next.
</p>
<p>
Next the compiler, standard library, and platform configuration files are
included. These are included via macros (<codeclass="computeroutput"><spanclass="identifier">BOOST_COMPILER_CONFIG</span></code>
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: <ahref="../../../../boost/config/compiler/visualc.hpp"target="_top"><codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">compiler</span><spanclass="special">/</span><spanclass="identifier">visualc</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code></a> for the compiler, <ahref="../../../../boost/config/stdlib/stlport.hpp"target="_top"><codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">stdlib</span><spanclass="special">/</span><spanclass="identifier">stlport</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code></a> for the standard library, and
<ahref="../../../../boost/config/platform/win32.hpp"target="_top"><codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">platform</span><spanclass="special">/</span><spanclass="identifier">win32</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code></a> for the platform. Next we'll
create our own private configuration directory: <codeclass="computeroutput"><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span><spanclass="identifier">mysetup</span><spanclass="special">/</span></code>, and copy the configuration files into
there. Finally, open up <ahref="../../../../boost/config/user.hpp"target="_top"><boost/config/user.hpp></a>
<aname="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need"></a><ahref="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need"title="Example 2: skipping files that you don't need">Example
<aname="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration"></a><ahref="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration"title="Example 3: using configure script to freeze the boost configuration">Example
<aname="boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration"></a><ahref="index.html#boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration"title="Testing the boost configuration">Testing
The boost configuration library provides a full set of regression test programs
under the <spanclass="emphasis"><em><boost-root></em></span><codeclass="computeroutput"><spanclass="special">/</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="identifier">config</span><spanclass="special">/</span></code>
Tests your standard library's <codeclass="computeroutput"><spanclass="identifier">std</span><spanclass="special">::</span><spanclass="identifier">numeric_limits</span></code>
implementation (or its boost provided replacement if <codeclass="computeroutput"><spanclass="identifier">BOOST_NO_LIMITS</span></code> is defined). This
test file fails with most versions of numeric_limits, mainly due
to the way that some compilers treat NAN's and infinity.
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 <codeclass="computeroutput"><spanclass="identifier">config_info</span><spanclass="special">.</span><spanclass="identifier">cpp</span></code>, and the pass/fail test results.
