configuring_boost.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[/
    Boost.Config

    Copyright (c) 2001 Beman Dawes
    Copyright (c) 2001 Vesa Karvonen
    Copyright (c) 2001 John Maddock

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
]


[section Configuring Boost for Your Platform]


[section Using the default boost configuration]

Boost comes already configured for most common compilers and platforms; you
should be able to use boost "as is". Since the compiler is configured
separately from the standard library, the default configuration should work
even if you replace the compiler's standard library with a third-party
standard library (like __STL_PORT__).

Using boost "as is" without trying to reconfigure is the recommended method
for using boost. You can, however, run the configure script if you want to,
and there are regression tests provided that allow you to test the current
boost configuration with your particular compiler setup.

Boost library users can request support for additional compilers or platforms
by visiting our __BOOST_TRACKER__ and submitting a support request.

[endsect]

[section The <boost/config.hpp> header]

Boost library implementations access configuration macros via

    #include ``__BOOST_CONFIG_HEADER__``

While Boost library users are not required to include that file directly, or
use those configuration macros, such use is acceptable. The configuration
macros are documented as to their purpose, usage, and limitations which makes
them usable by both Boost library and user code.

Boost [link config_info_macros informational] or [link config_helpers helper]
macros are designed for use by Boost users as well as for our own internal use.
Note however, that the [link config_features feature test] and
[link config_defects defect test] macros were designed for internal use by
Boost libraries, not user code, so they can change at any time (though no
gratuitous changes are made to them). Boost library problems resulting from
changes to the configuration macros are caught by the Boost regression tests,
so the Boost libraries are updated to account for those changes. By contrast,
Boost library user code can be adversely affected by changes to the macros
without warning. The best way to keep abreast of changes to the macros used in
user code is to monitor the discussions on the Boost developers list.

[endsect]

[#config_config_script]

[section Using the configure script]

[important
This configure script only sets up the Boost headers for use with a particular
compiler. It has no effect on Boost.Build, or how the libraries are built.
]

If you know that boost is incorrectly configured for your particular setup, and
you are on a UNIX like platform, then you may want to try and improve things by
running the boost configure script. From a shell command prompt you will need to
cd into ['<boost-root>]`/libs/config/` and type:

[: `sh ./configure` ]

you will see a list of the items being checked as the script works its way
through the regression tests. Note that the configure script only really
auto-detects your compiler if it's called g++, c++ or CC. If you are using
some other compiler you will need to set one or more of the following
environment variables:


[table
[[Variable][Description                                       ]]
[[CXX     ][The name of the compiler, for example `c++`.      ]]
[[CXXFLAGS][The compiler flags to use, for example `-O2`.     ]]
[[LDFLAGS ][The linker flags to use, for example `-L/mypath`. ]]
[[LIBS    ][Any libraries to link in, for example `-lpthread`.]]
]

For example to run the configure script with HP aCC, you might use something
like:

    export CXX="aCC"
    export CXXFLAGS="-Aa -DAportable -D__HPACC_THREAD_SAFE_RB_TREE \
       -DRWSTD_MULTI_THREAD -DRW_MULTI_THREAD -D_REENTRANT -D_THREAD_SAFE"
    export LDFLAGS="-DAportable"
    export LIBS="-lpthread" 
    sh ./configure

However you run the configure script, when it finishes you will find a
new header -`user.hpp`- located in the ['<boost-root>]`/libs/config/`
directory. [*Note that configure does not install this header into your
boost include path by default]. This header contains all the options
generated by the configure script, plus a header-section that contains
the user settable options from the default version of
__BOOST_CONFIG_USER_HEADER__ (located under __BOOST_CONFIG_DIR__).
There are two ways you can use this header:

* [*Option 1:] copy the header into __BOOST_CONFIG_DIR__ so that it replaces
the default user.hpp provided by boost. This option allows only one
configure-generated setup; boost developers should avoid this option,
as it incurs the danger of accidentally committing a configure-modified
__BOOST_CONFIG_USER_HEADER__ to the cvs repository (something you will not
be thanked for!).

* [*Option 2:]  give the header a more memorable name, and place it somewhere
convenient; then, define the macro `BOOST_USER_CONFIG` to point to it. For
example create a new sub-directory __BOOST_CONFIG_DIR__ `user/`, and copy
the header there; for example as `multithread-gcc-config.hpp`. Then, when
compiling add the command line option:
`-DBOOST_USER_CONFIG="<boost/config/user/multithread-gcc-config.hpp>"`, and
boost will use the new configuration header. This option allows you to
generate more than one configuration header, and to keep them separate
from the boost source - so that updates to the source do not interfere
with your configuration.

[endsect]

[#config_user_settable]

[section User settable options]

There are some configuration-options that represent user choices, rather
than compiler defects or platform specific options. These are listed in
`<boost/config/user.hpp>` and at the start of a configure-generated `user.hpp`
header. You can define these on the command line, or by editing
`<boost/config/user.hpp>`, they are listed in the following table: 



[table

[[Macro         ][Description       ]]

[[`BOOST_USER_CONFIG`][
When defined, it should point to the name of the user configuration file
to include prior to any boost configuration files. When not defined,
defaults to [@../../../../boost/config/user.hpp `<boost/config/user.hpp>`].
]]
[[`BOOST_COMPILER_CONFIG`][
When defined, it should point to the name of the compiler configuration
file to use. Defining this cuts out the compiler selection logic, and
eliminates the dependency on the header containing that logic. For
example if you are using gcc, then you could define BOOST_COMPILER_CONFIG
to [@../../../../boost/config/compiler/gcc.hpp `<boost/config/compiler/gcc.hpp>`].
]]
[[`BOOST_STDLIB_CONFIG`][
When defined, it should point to the name of the standard library
configuration file to use. Defining this cuts out the standard library
selection logic, and eliminates the dependency on the header containing
that logic. For example if you are using STLport, then you could define
`BOOST_STDLIB_CONFIG` to
[@../../../../boost/config/stdlib/stlport.hpp `<boost/config/stdlib/stlport.hpp>`].
]]
[[`BOOST_PLATFORM_CONFIG`][
When defined, it should point to the name of the platform configuration
file to use. Defining this cuts out the platform selection logic, and
eliminates the dependency on the header containing that logic. For example
if you are compiling on linux, then you could define `BOOST_PLATFORM_CONFIG`
to [@../../../../boost/config/platform/linux.hpp `<boost/config/platform/linux.hpp>`].
]]
[[`BOOST_NO_COMPILER_CONFIG`][
When defined, no compiler configuration file is selected or included,
define when the compiler is fully conformant with the standard, or where
the user header (see `BOOST_USER_CONFIG`), has had any options necessary
added to it, for example by an autoconf generated configure script.
]]
[[`BOOST_NO_STDLIB_CONFIG` ][
When defined, no standard library configuration file is selected or included,
define when the standard library is fully conformant with the standard, or
where the user header (see `BOOST_USER_CONFIG`), has had any options necessary
added to it, for example by an autoconf generated configure script.
]]
[[`BOOST_NO_PLATFORM_CONFIG` ][
When defined, no platform configuration file is selected or included,
define when the platform is fully conformant with the standard (and has
no useful extra features), or where the user header (see
`BOOST_USER_CONFIG`), has had any options necessary added to it, for example
by an autoconf generated configure script.
]]
[[`BOOST_NO_CONFIG` ][
Equivalent to defining all of `BOOST_NO_COMPILER_CONFIG`,
`BOOST_NO_STDLIB_CONFIG` and `BOOST_NO_PLATFORM_CONFIG`.
]]
[[`BOOST_STRICT_CONFIG` ][
The normal behavior for compiler versions that are newer than the last
known version, is to assume that they have all the same defects as the
last known version. By setting this define, then compiler versions that
are newer than the last known version are assumed to be fully conforming
with the standard. This is probably most useful for boost developers or
testers, and for those who want to use boost to test beta compiler versions.
]]
[[`BOOST_ASSERT_CONFIG` ][
When this flag is set, if the config finds anything unknown, then it will
stop with a #error rather than continue. Boost regression testers should
set this define, as should anyone who wants to quickly check whether boost
is supported on their platform.
]]
[[`BOOST_DISABLE_THREADS` ][
When defined, disables threading support, even if the compiler in its
current translation mode supports multiple threads.
]]
[[`BOOST_DISABLE_WIN32` ][
When defined, disables the use of Win32 specific API's, even when these
are available. Also has the effect of setting `BOOST_DISABLE_THREADS` unless
`BOOST_HAS_PTHREADS` is set. This option may be set automatically by the
config system when it detects that the compiler is in "strict mode".