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+
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. +
+Boost library implementations access configuration macros via #include
+ <boost/config.hpp>.
+
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 informational or helper + macros are designed for use by Boost users as well as for our own internal + use. Note however, that the feature test and + 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.
+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 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" 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 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.
+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. + |
+
| BOOST_LIB_DIAGNOSTIC | +Causes the auto-linking code to output diagnostic messages indicating the name + of the library that is selected for linking. | +
| BOOST_LIB_TOOLSET | +Overrides the name of the toolset part of the name of library being linked to; + note if defined this must be defined to a quoted string literal, for example + "abc". | +
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.
+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.
+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_IS_ABSTRACT | +Compiler | +The C++ compiler does not support SFINAE with + abstract types, this is covered by + Core Language DR337, but is not part of the current standard. + Fortunately most compilers that support SFINAE also support this DR. | +
| 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_POINTER_TO_MEMBER_TEMPLATE_PARAMETERS | +Compiler | +Pointers to members don't work when used as template + parameters. | +
| 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_SFINAE | +Compiler | +The compiler does not support the "Substitution + Failure Is Not An Error" meta-programming idiom. | +
| 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(); }
+ |
+
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). | +
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_HAS_FACET(Type, loc) | +When the standard library does not have a comforming
+ std::has_facet there are various workarounds available, but they differ from
+ library to library. This macro provides a consistent way to check a locale's
+ facets. For example, replace:std::has_facet<Type>(loc);+ with: +BOOST_HAS_FACET(Type, loc);+ Note do not add a std:: prefix to the front of BOOST_HAS_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__. | +
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_WINDOWS | +<boost/config.hpp> | +Defined if the Windows platform API is available. | +
| 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. | +
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.
+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.
+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 ++
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:
+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 .ipp 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.ipp", where foo + is the defect description - try and keep the file name under the Mac 30 + character filename limit though. You will also need to provide a function + prototype "int test()" that is declared in a namespace with the same name as + the macro, but in all lower case, and which returns zero on success:
+namespace boost_no_foo{
+
+int test()
+{
+ // test code goes here:
+ //
+ return 0;
+}
+
+}
+ + Once the test code is in place, build and run the program "generate.cpp" that + you will find in the boost-root/libs/config/tools/ directory. This generates + two .cpp test files from the new test code, and adds the tests to the + regression test Jamfile, and the config_test.cpp test program. Finally add a + new entry to config_info.cpp so that the new macro gets printed out when that + program is run.
+When you need to add a macro that describes a feature that the standard does + not require, follow the convention for adding a new defect macro (above), but + call the macro BOOST_HAS_FOO, and name the test file "boost_has_foo.ipp". Try + not to add feature test macros unnecessarily, if there is a platform specific + macro that can already be used (for example _WIN32, __BEOS__, or __linux) to + identify the feature then use that. Try to keep the macro to a feature group, + or header name, rather than one specific API (for example BOOST_HAS_NL_TYPES_H + rather than BOOST_HAS_CATOPEN). If the macro describes a POSIX feature group, + then add boilerplate code to 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>).
+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!
+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.
+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 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.
+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
++
+
+
+
+ +