Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.

Boost

Boost Configuration Reference

Contents

Configuring Boost for Your Platform
   Using the default boost configuration
   The <boost\config.hpp> header
   Using the configure script
   User settable options
   Advanced configuration usage
   Testing the boost configuration
Boost Macro Reference
   Macros that describe defects
   Macros that describe optional features
   Boost Helper Macros
   Boost Informational Macros
   Macros for libraries with separate source code
Guidelines for Boost Authors
   Adding New Defect Macros
   Adding New Feature Test Macros
   Modifying the Boost Configuration Headers
Rationale
Acknowledgements

Configuring Boost for Your Platform

Using the default boost configuration

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 STLport).

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 Tracker and submitting a support request.

The <boost/config.hpp> header

Boost library implementations access configuration macros via #include <boost/config.hpp>.

Boost library users are never required to #include <boost/config.hpp>, and are discouraged from doing so on their own. It is an implementation detail which is subject to change, and thus should not be depended upon by users.

Using the configure script

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:

./configure

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:

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"
./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 user.hpp (located under <boost-root>/boost/config/). There are two ways you can use this header:

Option 1: copy the header into <boost-root>/boost/config/ 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 user.hpp 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-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.

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: 

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_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_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_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_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".
BOOST_DISABLE_ABI_HEADERS Stops boost headers from including any prefix/suffix headers that normally control things like struct packing and alignment.
BOOST_ABI_PREFIX 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.
BOOST_ABI_SUFFIX A suffix header to include in place of whatever boost.config would normally select, any replacement should undo the effects of the prefix header.
BOOST_ALL_DYN_LINK

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). 

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.

BOOST_WHATEVER_DYN_LINK

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). 

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.

BOOST_ALL_NO_LIB

Tells the config system not to automatically select which libraries to link against. 

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.

BOOST_WHATEVER_NO_LIB

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. 

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.

Advanced configuration usage

By setting various macros on the compiler command line or by editing <boost/config/user.hpp>, the boost configuration setup can be optimised in a variety of ways.

Boost's configuration is structured so that the user-configuration is included first (defaulting to <boost/config/user.hpp> 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.

Next the compiler, standard library, and platform configuration files are included. These are included via macros (BOOST_COMPILER_CONFIG etc, see user settable macros), 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 - see user settable macros).

Finally the boost configuration header, includes <boost/config/suffix.hpp>; this header contains any boiler plate configuration code - for example where one boost macro being set implies that another must be set also.

The following usage examples represent just a few of the possibilities:

Example 1, creating our own frozen configuration.

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: <boost/config/compiler/visualc.hpp> for the compiler, <boost/config/stdlib/stlport.hpp> for the standard library, and <boost/config/platform/win32.hpp> 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 <boost/config/user.hpp> and edit the following defines:

#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"

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.

Example 2: skipping files that you don't need.

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.

Example 3: using configure script to freeze the boost configuration.

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 - see using the configure script for more details.

Testing the boost configuration

The boost configuration library provides a full set of regression test programs under the <boost-root>/libs/config/test/ sub-directory:

File

Description

config_info.cpp 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.
config_test.cpp 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.
limits_test.cpp 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.
no_*pass.cpp 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.
no_*fail.cpp Individual compiler defect test files. Each of these should not 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.
has_*pass.cpp Individual feature test files. If one of these does not compile then the corresponding BOOST_HAS_XXX macro is defined when it should not be - see each test file for specific details.
has_*fail.cpp 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.

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:

If you have built the boost regression test driver, then you can use this to produce a nice html formatted report of the results using the supplied test file.

Alternatively you can run the configure script like this:

./configure --enable-test

in which case the script will test the current configuration rather than creating a new one from scratch.

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.

Boost Macro Reference

Macros that describe defects:

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.

Macro

Section

Description

BOOST_BCB_PARTIAL_SPECIALIZATION_BUG Compiler The compiler exibits certain partial specialisation bug - probably Borland C++ Builder specific.
BOOST_FUNCTION_SCOPE_USING_DECLARATION_BREAKS_ADL Compiler Argument dependent lookup fails if there is a using declaration for the symbol being looked up in the current scope.  For example, using boost::get_pointer; prevents ADL from finding overloads of get_pointer in namespaces nested inside boost (but not elsewhere).  Probably Borland specific.
BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP Compiler Compiler does not implement argument-dependent lookup (also named Koenig lookup); see std::3.4.2 [basic.koenig.lookup]
BOOST_NO_AUTO_PTR Standard library If the compiler / library supplies non-standard or broken std::auto_ptr.
BOOST_NO_CTYPE_FUNCTIONS Platform The Platform does not provide functions for the character-classifying operations <ctype.h> and <cctype>, only macros.
BOOST_NO_CV_SPECIALIZATIONS Compiler If template specialisations for cv-qualified types conflict with a specialisation for a cv-unqualififed type.
BOOST_NO_CV_VOID_SPECIALIZATIONS Compiler If template specialisations for cv-void types conflict with a specialisation for void.
BOOST_NO_CWCHAR Platform The Platform does not provide <wchar.h> and <cwchar>.
BOOST_NO_CWCTYPE Platform The Platform does not provide <wctype.h> and <cwctype>.
BOOST_NO_DEPENDENT_NESTED_DERIVATIONS Compiler The compiler fails to compile a nested class that has a dependent base class:
template<typename T>
struct foo : {
   template<typename U>
   struct bar : public U {};
};
BOOST_NO_DEPENDENT_TYPES_IN_TEMPLATE_VALUE_PARAMETERS Compiler Template value parameters cannot have a dependent type, for example:
template<class T, typename T::type value> 
class X { ... };
BOOST_NO_EXCEPTION_STD_NAMESPACE Standard Library The standard library does not put some or all of the contents of <exception> in namespace std.
BOOST_NO_EXCEPTIONS Compiler 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!
BOOST_NO_EXPLICIT_FUNCTION_TEMPLATE_ARGUMENTS Compiler Can only use deduced template arguments when calling function template instantiations.
BOOST_NO_FUNCTION_TEMPLATE_ORDERING Compiler The compiler does not perform function template ordering or its function template ordering is incorrect.
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.
BOOST_NO_INCLASS_MEMBER_INITIALIZATION Compiler Compiler violates std::9.4.2/4.
BOOST_NO_INTRINSIC_WCHAR_T Compiler 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.
BOOST_NO_LIMITS Standard library 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 std::numeric_limits.
BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS Standard library Constants such as numeric_limits<T>::is_signed are not available for use at compile-time.
BOOST_NO_LONG_LONG_NUMERIC_LIMITS Standard library 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.
BOOST_NO_MEMBER_FUNCTION_SPECIALIZATIONS Compiler The compiler does not support the specialization of individual member functions of template classes.
BOOST_NO_MEMBER_TEMPLATE_KEYWORD Compiler If the compiler supports member templates, but not the template keyword when accessing member template classes.
BOOST_NO_MEMBER_TEMPLATE_FRIENDS Compiler Member template friend syntax ("template<class P> friend class frd;") described in the C++ Standard, 14.5.3, not supported.
BOOST_NO_MEMBER_TEMPLATES Compiler Member template functions not fully supported.
BOOST_NO_MS_INT64_NUMERIC_LIMITS Standard library 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.
BOOST_NO_OPERATORS_IN_NAMESPACE Compiler Compiler requires inherited operator friend functions to be defined at namespace scope, then using'ed to boost. Probably GCC specific. See boost/operators.hpp for example.
BOOST_NO_POINTER_TO_MEMBER_CONST Compiler The compiler does not correctly handle pointers to const member functions, preventing use of these in overloaded function templates. See boost/functional.hpp for example.
BOOST_NO_PRIVATE_IN_AGGREGATE Compiler The compiler misreads 8.5.1, treating classes as non-aggregate if they contain private or protected member functions.
BOOST_NO_STD_ALLOCATOR Standard library The C++ standard library does not provide a standards conforming std::allocator.
BOOST_NO_STD_DISTANCE Standard library The platform does not have a conforming version of std::distance.
BOOST_NO_STD_ITERATOR Standard library The C++ implementation fails to provide the std::iterator class.
BOOST_NO_STD_ITERATOR_TRAITS Standard library The compiler does not provide a standard compliant implementation of std::iterator_traits. Note that the compiler may still have a non-standard implementation.
BOOST_NO_STD_LOCALE Standard library The standard library lacks std::locale.
BOOST_NO_STD_MESSAGES Standard library The standard library lacks a conforming std::messages facet.
BOOST_NO_STD_MIN_MAX Standard library The C++ standard library does not provide the min() and max() template functions that should be in <algorithm>.
BOOST_NO_STD_OUTPUT_ITERATOR_ASSIGN Standard library Defined if the standard library's output iterators are not assignable.
BOOST_NO_STD_USE_FACET Standard library The standard library lacks a conforming std::use_facet.
BOOST_NO_STD_WSTREAMBUF Standard library The standard library's implementation of std::basic_streambuf<wchar_t> is either missing, incomplete, or buggy.
BOOST_NO_STD_WSTRING Standard library The standard library lacks std::wstring.
BOOST_NO_STDC_NAMESPACE Compiler/Platform 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...
BOOST_NO_STRINGSTREAM Standard library The C++ implementation does not provide the <sstream> header.
BOOST_NO_SWPRINTF Platform The platform does not have a conforming version of swprintf.
BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION Compiler Class template partial specialization (14.5.4 [temp.class.spec]) not supported.
BOOST_NO_TEMPLATED_ITERATOR_CONSTRUCTORS Standard library The standard library does not provide templated iterator constructors for its containers.
BOOST_NO_TEMPLATE_TEMPLATES Compiler The compiler does not support template template parameters.
BOOST_NO_UNREACHABLE_RETURN_DETECTION Compiler 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.
BOOST_NO_USING_DECLARATION_OVERLOADS_FROM_TYPENAME_BASE Compiler 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.
BOOST_NO_USING_TEMPLATE Compiler 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).
BOOST_NO_VOID_RETURNS Compiler The compiler does not allow a void function to return the result of calling another void function.
void f() {}
void g() { return f(); }

Macros that describe optional features:

The following macros describe features that are not required by the C++ standard. The macro is only defined if the feature is present.

Macro

Section

Description

BOOST_HAS_BETHREADS Platform The platform supports BeOS style threads.
BOOST_HAS_CLOCK_GETTIME Platform The platform has the POSIX API clock_gettime.
BOOST_HAS_DECLSPEC Compiler The compiler uses __declspec(dllexport) and __declspec(dllimport) to export/import symbols from dll's.
BOOST_HAS_DIRENT_H Platform The platform has the POSIX header <dirent.h>.
BOOST_HAS_FTIME Platform The platform has the Win32 API GetSystemTimeAsFileTime.
BOOST_HAS_GETTIMEOFDAY Platform The platform has the POSIX API gettimeofday.
BOOST_HAS_HASH Standard library The C++ implementation provides the (SGI) hash_set or hash_map classes.
BOOST_HAS_LONG_LONG Compiler The compiler supports the long long data type.
BOOST_HAS_MACRO_USE_FACET Standard library 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.
BOOST_HAS_MS_INT64 Compiler The compiler supports the __int64 data type.
BOOST_HAS_NANOSLEEP Platform The platform has the POSIX API nanosleep.
BOOST_HAS_NL_TYPES_H Platform The platform has an <nl_types.h>.
BOOST_HAS_NRVO Compiler Indicated that the compiler supports the named return value optimization (NRVO). Used to select the most efficient implementation for some function. See boost/operators.hpp for example.
BOOST_HAS_PARTIAL_STD_ALLOCATOR Standard Library The standard library has a partially conforming std::allocator class, but without any of the member templates.
BOOST_HAS_PTHREAD_DELAY_NP Platform The platform has the POSIX API pthread_delay_np.
BOOST_HAS_PTHREAD_MUTEXATTR_SETTYPE Platform The platform has the POSIX API pthread_mutexattr_settype.
BOOST_HAS_PTHREAD_YIELD Platform The platform has the POSIX API pthread_yield.
BOOST_HAS_PTHREADS Platform The platform support POSIX style threads.
BOOST_HAS_SCHED_YIELD Platform The platform has the POSIX API sched_yield.
BOOST_HAS_SGI_TYPE_TRAITS Compiler/standard library The compiler has native support for SGI style type traits.
BOOST_HAS_STDINT_H Platform The platform has a <stdint.h>
BOOST_HAS_SLIST Standard library The C++ implementation provides the (SGI) slist class.
BOOST_HAS_STLP_USE_FACET Standard library 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.
BOOST_HAS_THREADS Platform/compiler Defined if the compiler, in its current translation mode, supports multiple threads of execution.
BOOST_HAS_TWO_ARG_USE_FACET Standard library 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.
BOOST_HAS_UNISTD_H Platform The Platform provides <unistd.h>.
BOOST_HAS_WINTHREADS Platform The platform supports MS Windows style threads.
BOOST_MSVC_STD_ITERATOR Standard library Microsoft's broken version of std::iterator is being used. This implies that std::iterator takes no more than two template parameters.
BOOST_MSVC6_MEMBER_TEMPLATES Compiler 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.
BOOST_HAS_STDINT_H Platform 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).

Boost Helper Macros

The following macros are either simple helpers, or macros that provide workarounds for compiler/standard library defects.

Macro

Description

BOOST_DEDUCED_TYPENAME Some compilers don't support the use of typename for dependent types in deduced contexts. This macro expands to nothing on those compilers, and typename elsewhere. For example, replace:
template <class T> void f(T, typename T::type);

with:

template <class T> void f(T, BOOST_DEDUCED_TYPENAME T::type);
BOOST_STD_EXTENSION_NAMESPACE The namespace used for std library extensions (hashtable classes etc).
BOOST_STATIC_CONSTANT(Type, assignment) 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:
struct foo{
   static const int value = 2;
};

use:

struct foo{
   BOOST_STATIC_CONSTANT(int, value = 2);
};
BOOST_UNREACHABLE_RETURN(result) Normally evaluates to nothing, but evaluates to return x; if the compiler requires a return, even when it can never be reached.
BOOST_EXPLICIT_TEMPLATE_TYPE(t)
BOOST_EXPLICIT_TEMPLATE_NON_TYPE(t, v)
BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(t)
BOOST_APPEND_EXPLICIT_TEMPLATE_NON_TYPE(t, v)
Some compilers silently "fold" different function template instantiations if some of the template parameters don't appear in the function parameter list. For instance:
  #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>();
  }
incorrectly outputs "2 2 double double " 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:
  template <int n>
  void f(BOOST_EXPLICIT_TEMPLATE_NON_TYPE(int, n)) { ... }

  template <typename T>
  void g(BOOST_EXPLICIT_TEMPLATE_TYPE(T)) { ... }
Beware that they can declare (for affected compilers) a dummy defaulted parameter, so they

a) should be always invoked *at the end* of the parameter list
b) can't be used if your function template is multiply declared.

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.
BOOST_USE_FACET(Type, loc) 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:
std::use_facet<Type>(loc);

with:

BOOST_USE_FACET(Type, loc);

Note do not add a std:: prefix to the front of BOOST_USE_FACET.

BOOST_NESTED_TEMPLATE Member templates are supported by some compilers even though they can't use the A::template member<U> syntax, as a workaround replace:
typedef typename A::template rebind<U> binder;

with:

typedef typename A::BOOST_NESTED_TEMPLATE rebind<U> binder;
BOOST_STRINGIZE(X) Converts the parameter X to a string after macro replacement on X has been performed.
BOOST_JOIN(X,Y) 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__.

Boost Informational Macros

The following macros describe boost features; these are the generally speaking the only boost macros that should be tested in user code.

Macro

Header

Description

BOOST_VERSION <boost/version.hpp> 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.
BOOST_NO_INT64_T <boost/cstdint.hpp>

<boost/stdint.h>

Defined if there are no 64-bit integral types: int64_t, uint64_t etc.
BOOST_NO_INTEGRAL_INT64_T <boost/cstdint.hpp>

<boost/stdint.h>

Defined if int64_t as defined by <boost/cstdint.hpp> is not usable in integral constant expressions.
BOOST_MSVC <boost/config.hpp> Defined if the compiler is really Microsoft Visual C++, as opposed to one of the many other compilers that also define _MSC_VER.
BOOST_INTEL <boost/config.hpp> Defined if the compiler is an Intel compiler, takes the same value as the compiler version macro.
BOOST_DINKUMWARE_STDLIB <boost/config.hpp> 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.
BOOST_NO_WREGEX <boost/regex.hpp> Defined if the regex library does not support wide character regular expressions.
BOOST_COMPILER <boost/config.hpp> Defined as a string describing the name and version number of the compiler in use. Mainly for debugging the configuration.
BOOST_STDLIB <boost/config.hpp> Defined as a string describing the name and version number of the standard library in use. Mainly for debugging the configuration.
BOOST_PLATFORM <boost/config.hpp> Defined as a string describing the name of the platform. Mainly for debugging the configuration.

Macros for libraries with separate source code

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.

ABI Fixing

When linking against a pre-compiled library it vital that the ABI used by the compiler when building the library matches exactly 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:

#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

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.

Automatic library selection

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).

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:

BOOST_LIB_NAME Required: An identifier containing the basename of the library, for example 'boost_regex'.
BOOST_DYN_LINK Optional: when set link to dll rather than static library.
BOOST_LIB_DIAGNOSTIC Optional: when set the header will print out the name of the library selected (useful for debugging).

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.

Typical usage would be:

//
// 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

Guidelines for Boost Authors

The boost/config.hpp 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.

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.

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.

Note that:

Adding New Defect Macros

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.

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.

Finally, add the test program to the regression tests. You will need to place the test case in a .cxx file with the following comments near the top:

//  MACRO:         BOOST_NO_FOO
//  TITLE:         foo
//  DESCRIPTION:   If the compiler fails to support foo

These comments are processed by the autoconf script, so make sure the format follows the one given. The file should be named "boost_no_foo.cxx", where foo is the defect description - try and keep the file name under the Mac 30 character filename limit though. You will also need to provide a function prototype "int test()" that is declared in a namespace with the same name as the macro, but in all lower case, and which returns zero on success:

namespace boost_no_foo{

int test()
{
   // test code goes here:
   //
   return 0;
}

}

Once the test code is in place, run the shell script "generate" that you will find in the boost-root/libs/config/tools/ directory. This generates two .cpp test files from the new test code, and adds the tests to the regression test script, and the config_test.cpp test program. If you can't run shell scripts on your platform then post a message on the boost mailing list, and someone will run it for you. Finally add a new entry to config_info.cpp so that the new macro gets printed out when that program is run.

Adding New Feature Test Macros

When you need to add a macro that describes a feature that the standard does not require, follow the convention for adding a new defect macro (above), but call the macro BOOST_HAS_FOO, and name the test file "boost_has_foo.cxx". Try not to add feature test macros unnecessarily, if there is a platform specific macro that can already be used (for example _WIN32, __BEOS__, or __linux) to identify the feature then use that. Try to keep the macro to a feature group, or header name, rather than one specific API (for example BOOST_HAS_NL_TYPES_H rather than BOOST_HAS_CATOPEN). If the macro describes a POSIX feature group, then add boilerplate code to boost/config/suffix.hpp 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>).

Modifying the Boost Configuration Headers

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:

<boost/config.hpp> should never change, don't alter this file.

<boost/config/user.hpp> is included by default, don't add extra code to this file unless you have to. If you do, please remember to update libs/config/tools/configure.in as well.

<boost/config/suffix.hpp> 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.

<boost/config/select_compiler_config.hpp>, <boost/config/select_platform_config.hpp> and <boost/config/select_stdlib_config.hpp> are included by default and should change only if support for a new compiler/standard library/platform is added.

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.

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!

Rationale

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 following article.

The problem

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?

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:

"A module should be open for extension but closed for modification."

Extending a traditional configuration header implies modifying existing code.

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:

"Depend in the direction of stability."

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.

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.

The solution

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.

Acknowledgements

Beman Dawes provided the original config.hpp and part of this document. Vesa Karvonen provided a description of the principles (see rationale) 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.

 


© Beman Dawes 2001

© Vesa Karvonen 2001

© John Maddock 2001