<aname="boost_config.configuring_boost_for_your_platform"></a><aclass="link"href="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><aclass="link"href="index.html#boost_config.configuring_boost_for_your_platform.using_the_default_boost_configuration"title="Using the default boost configuration">Using
Boost <aclass="link"href="boost_config/boost_macro_reference.html#config_info_macros">informational</a> or <aclass="link"href="boost_config/boost_macro_reference.html#config_helpers">helper</a>
<aname="boost_config.configuring_boost_for_your_platform.using_the_configure_script"></a><aname="config_config_script"></a><aclass="link"href="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>
The linker flags to use, for example <codeclass="computeroutput"><spanclass="special">-</span><spanclass="identifier">L</span><spanclass="special">/</span><spanclass="identifier">mypath</span></code>.
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>).
<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!).
<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>.
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 <codeclass="computeroutput"><spanclass="identifier">BOOST_STDLIB_CONFIG</span></code>
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>.
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
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
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.
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><aclass="link"href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_2__skipping_files_that_you_don_t_need"title="Example 2: skipping files that you don't need">Example
<aname="boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration"></a><aclass="link"href="index.html#boost_config.configuring_boost_for_your_platform.advanced_configuration_usage.example_3__using_configure_script_to_freeze_the_boost_configuration"title="Example 3: using configure script to freeze the boost configuration">Example
<aname="boost_config.configuring_boost_for_your_platform.testing_the_boost_configuration"></a><aclass="link"href="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.
