...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The following macros all describe features that are required by the C++03 standard, if one of the following macros is defined, then it represents a defect in the compiler's conformance with the 2003 standard.
Macro |
Section |
Description |
---|---|---|
|
Compiler |
The compiler exhibits certain partial specialisation bug - probably Borland C++ Builder specific. |
|
Compiler |
Argument dependent lookup fails if there is a using declaration
for the symbol being looked up in the current scope. For example,
using |
|
Compiler |
The compiler locates and searches namespaces that it should *not* in fact search when performing argument dependent lookup. |
|
Compiler |
Compiler does not implement argument-dependent lookup (also named Koenig lookup); see std::3.4.2 [basic.koenig.lookup] |
|
Standard library |
If the compiler / library supplies non-standard or broken |
|
Compiler |
Compiler has not completely implemented value-initialization. See also The Utility/Value Init docs |
|
Platform |
The Platform does not provide functions for the character-classifying
operations |
|
Compiler |
If template specialisations for cv-qualified types conflict with a specialisation for a cv-unqualififed type. |
|
Compiler |
If template specialisations for cv-void types conflict with a specialisation for void. |
|
Platform |
The Platform does not provide |
|
Platform |
The Platform does not provide |
|
Platform, Standard library |
The C standard library doesn't provide |
|
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 {}; }; |
|
Compiler |
Template value parameters cannot have a dependent type, for example: template<class T, typename T::type value> class X { ... };
|
|
Standard Library |
The standard library does not put some or all of the contents of
|
|
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! |
|
Compiler |
The compiler does not perform function template ordering or its function template ordering is incorrect. // #1 template<class T> void f(T); // #2 template<class T,class U> void f(T(*)(U)); void bar(int); f(&bar); // should choose #2.
|
|
Compiler |
Compiler violates std::9.4.2/4. |
|
Compiler |
The C++ implementation does not provide |
|
std lib |
The standard library lacks |
|
std lib |
The standard library lacks |
|
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. See also BOOST_NO_SFINAE and BOOST_NO_SFINAE_EXPR |
|
Standard library |
The C++ implementation does not provide the |
|
Standard library |
C++11 additions to |
|
Standard library |
Constants such as |
|
Standard library |
There is no specialization for |
|
Compiler |
The compiler does not support the specialization of individual member functions of template classes. |
|
Compiler |
If the compiler supports member templates, but not the template keyword when accessing member template classes. |
|
Compiler |
Member template friend syntax ( |
|
Compiler |
Member template functions not fully supported. |
|
Standard library |
There is no specialization for |
|
Compiler |
Compiler doesn't allow a nested class to access private members of its containing class. Probably Borland/CodeGear specific. |
|
Compiler |
Compiler requires inherited operator friend functions to be defined
at namespace scope, then using'ed to boost. Probably GCC specific.
See |
|
Compiler |
The compiler does not correctly handle partial specializations which depend upon default arguments in the primary template. |
|
Compiler |
The compiler does not correctly handle pointers to const member
functions, preventing use of these in overloaded function templates.
See |
|
Compiler |
Pointers to members don't work when used as template parameters. |
|
Compiler |
The compiler misreads 8.5.1, treating classes as non-aggregate if they contain private or protected member functions. |
|
Compiler |
Compiler-specific |
|
Compiler |
The compiler may (or may not) have the typeid operator, but RTTI on the dynamic type of an object is not supported. |
|
Compiler |
The compiler does not support the "Substitution Failure Is Not An Error" meta-programming idiom. This is the lightweight pre-C++11 version of SFINAE. |
|
Compiler |
The compiler does not support usage of SFINAE with arbitrary expressions. This is the post-C++11 SFINAE, but excludes a few specific corner cases, see also BOOST_NO_CXX11_SFINAE_EXPR. |
|
Standard library |
The C++ standard library does not provide a standards conforming
|
|
Standard library |
The platform does not have a conforming version of |
|
Standard library |
The C++ implementation fails to provide the |
|
Standard library |
The compiler does not provide a standard compliant implementation
of |
|
Standard library |
The standard library lacks |
|
Standard library |
The standard library lacks a conforming |
|
Standard library |
The C++ standard library does not provide the |
|
Standard library |
Defined if the standard library's output iterators are not assignable. |
|
Standard library |
The <typeinfo> header declares |
|
Standard library |
The standard library lacks a conforming |
|
Standard library |
The standard library's implementation of |
|
Standard library |
The standard library lacks |
|
Compiler, Platform |
The contents of C++ standard headers for C library functions (the
|
|
Standard library |
The C++ implementation does not provide the |
|
Platform |
The platform does not have a conforming version of |
|
Compiler |
Class template partial specialization (14.5.4 [temp.class.spec]) not supported. |
|
Standard library |
The standard library does not provide templated iostream classes. |
|
Standard library |
The standard library does not provide templated iterator constructors for its containers. |
|
Compiler |
The compiler does not support template template parameters. |
|
Compiler |
The compiler does not support the typeid operator at all. |
|
Compiler |
The typename keyword cannot be used when creating a temporary of a Dependent type. |
|
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. |
|
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. |
|
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). |
|
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 |
---|---|---|
|
Platform |
The platform supports BeOS style threads. |
|
Platform |
The platform has the POSIX API |
|
Platform |
The platform has the POSIX header |
|
Platform |
The platform has the functions |
|
Compiler |
The compiler has |
|
Platform |
The platform has the Win32 API type FTIME. |
|
Platform |
The platform has the Win32 API GetSystemTimeAsFileTime. |
|
Platform |
The platform has the POSIX API |
|
Standard library |
The C++ implementation provides the (SGI) hash_set and hash_map
classes. When defined, |
|
Compiler |
The compiler has |
|
Platform |
The platform has the functions |
|
Standard library |
The standard library lacks a conforming |
|
Compiler |
The compiler supports the |
|
Platform |
The platform has the POSIX API nanosleep. |
|
Platform |
The platform has an |
|
Compiler |
Indicated that the compiler supports the named return value optimization
(NRVO). Used to select the most efficient implementation for some
function. See |
|
Standard Library |
The standard library has a partially conforming |
|
Compiler |
The compiler recognizes the |
|
Compiler |
The compiler recognizes the |
|
Platform |
The platform has the POSIX API |
|
Platform |
The platform has the POSIX API |
|
Platform |
The platform has the POSIX API |
|
Platform |
The platform support POSIX style threads. |
|
Platform |
The platform has the POSIX API |
|
Compiler, Standard library |
The compiler has native support for SGI style type traits. |
|
Platform |
The platform has a |
|
Standard library |
The C++ implementation provides the (SGI) slist class. When defined,
|
|
Standard library |
The standard library lacks a conforming |
|
Standard library |
The library has a TR1 conforming version of |
|
Standard library |
The library has a version of |
|
Standard library |
The library has a version of |
|
Standard library |
The library has TR1 conforming reference wrappers in |
|
Standard library |
The library has a TR1 conforming result_of template in |
|
Standard library |
The library has a TR1 conforming mem_fn function template in |
|
Standard library |
The library has a TR1 conforming bind function template in |
|
Standard library |
The library has a TR1 conforming function class template in |
|
Standard library |
The library has a TR1 conforming hash function template in |
|
Standard library |
The library has a TR1 conforming |
|
Standard library |
The library has a TR1 conforming version of |
|
Standard library |
The library has a TR1 conforming version of |
|
Standard library |
The library has a TR1 conforming version of |
|
Standard library |
The library has a TR1 conforming version of |
|
Standard library |
The library has the TR1 additions to |
|
Standard library |
The library has a TR1 conforming version of |
|
Standard library |
The library has a TR1 conforming version of |
|
Standard library |
Implies all the other |
|
Platform, Compiler |
Defined if the compiler, in its current translation mode, supports multiple threads of execution. |
|
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. |
|
Platform |
The Platform provides |
|
Platform |
The platform supports MS Windows style threads. |
|
Standard library |
Microsoft's broken version of |
|
Compiler |
Microsoft Visual C++ 6.0 has enough member template idiosyncrasies
(being polite) that |
|
Platform |
There are no 1998 C++ Standard headers |
The following macros describe features that may be included in some future ISO C++ standard, but have not yet been approved for inclusion in the language.
Macro |
Description |
---|---|
|
The compiler supports concepts. |
The following macros describe features in the 2011 ISO C++ standard, formerly known as C++0x, that are not yet supported by a particular compiler or library.
Macro |
Description |
---|---|
|
The standard library header <memory> has no working std::addressof. |
|
The compiler does not support the |
|
The standard library does not provide a C++11 version of |
|
The standard library <memory> does not support atomic smart pointer operations. |
|
The compiler does not support type deduction for variables declared
with the |
|
The compiler does not support type deduction for multiple variables
declared with the |
|
The compiler does not support type |
|
The compiler does not support type |
|
The compiler does not support |
|
The compiler does not support |
|
The compiler does not support the extension to |
|
The compiler does not support deleted ( |
|
The compiler does not support defaulted ( |
|
The compiler does not support defaulted move constructor or assignment. Other defaulted functions may still be supported. |
|
The compiler does not support explicit conversion operators ( |
|
The compiler does not support explicit instantiation forward declarations
for templates ( |
|
The compiler does not support the C++ class-virt-specifier final. |
|
The compiler does not support expanding a variadic template parameter pack into a template containing one or more fixed arguments |
|
The compiler does not support default template arguments for function templates. |
|
The standard library does not provide header <atomic>. |
|
The standard library does not provide header <array>. |
|
The standard library does not provide header <chrono>. |
|
The standard library does not provide header <codecvt>. |
|
The standard library does not provide header <condition_variable>. |
|
The standard library does not provide header <forward_list>. |
|
The standard library does not provide a C++11 compatible version of <functional>. |
|
The standard library does not provide header <future>. |
|
The standard library does not provide header <initializer_list>. |
|
The standard library does not provide header <mutex>. |
|
The standard library does not provide header <random>. |
|
The standard library does not provide header <ratio>. |
|
The standard library does not provide header <regex>. |
|
The standard library does not provide header <system_error>. |
|
The standard library does not provide header <thread>. |
|
The standard library does not provide header <tuple>. |
|
The standard library does not provide header <typeindex>. |
|
The standard library does not provide header <type_traits>. |
|
The standard library does not provide header <unordered_map>. |
|
The standard library does not provide header <unordered_set>. |
|
The compiler does not support inline namespaces. |
|
The compiler does not support Lambdas. |
|
The compiler does not allow to pass local classes as template parameters (this macro intentionally does not control passing of unnamed types as template parameters, see also N2657). |
|
The compiler does not support defaulted ( |
|
The compiler does not support |
|
The compiler does not support |
|
The standard library |
|
The standard library does not provide a C++11 version of |
|
The compiler does not support range-based for statements. |
|
The compiler does not support raw string literals. |
|
The compiler does not support ref-qualifiers on member functions as described in N2439. |
|
The compiler does not support r-value references. |
|
The compiler does not support scoped enumerations ( |
|
The compiler does not support usage of C++11 SFINAE with arbitrary expressions. Use this macro only if you are using all of the features of SFINAE including substitution-failure-on-private-member-access. Otherwise use BOOST_NO_SFINAE_EXPR or BOOST_NO_SFINAE which get defined for fewer compilers. |
|
The standard library header <memory> has no shared_ptr and unique_ptr. |
|
The compiler does not support |
|
The standard library header <memory> has no working std::align. |
|
The standard library does not support <unordered_map> and <unordered_set>. |
|
The compiler does not support template aliases. |
|
The compiler does not support the |
|
The compiler does not support the new function result type specification
syntax (e.g. |
|
The compiler does not support Unicode ( |
|
The compiler does not support the C++11 Unified Initialization Syntax. |
|
The compiler does not support user defined literals. |
|
The compiler does not support variadic templates. |
|
The compiler does not support variadic macros. |
|
The compiler does not support |
The following macros allow use of C++11 features even with compilers that do not yet provide compliant C++11 support.
Macro |
Description |
---|---|
|
Some compilers don't support the struct BOOST_ALIGNMENT(16) my_data { char c[16]; }; BOOST_ALIGNMENT(8) int arr[32];
|
|
Some compilers don't support the use of constexpr tuple(); with: BOOST_CONSTEXPR tuple();
|
|
Some compilers don't support the use of static constexpr UIntType xor_mask = a; with: static BOOST_CONSTEXPR_OR_CONST UIntType xor_mask = a;
|
|
This is a shortcut for static constexpr UIntType xor_mask = a; with: BOOST_STATIC_CONSTEXPR UIntType xor_mask = a;
|
|
This macro is intended to be used within a class definition in
order to declare a default implementation of function struct my_struct { BOOST_DEFAULTED_FUNCTION(my_struct(), {}) }; is equivalent to: struct my_struct { my_struct() = default; }; or: struct my_struct { my_struct() {} };
|
|
This macro is intended to be used within a class definition in
order to declare a deleted function struct noncopyable { BOOST_DELETED_FUNCTION(noncopyable(noncopyable const&)) BOOST_DELETED_FUNCTION(noncopyable& operator= (noncopyable const&)) }; is equivalent to: struct noncopyable { noncopyable(noncopyable const&) = delete; noncopyable& operator= (noncopyable const&) = delete; }; or: struct noncopyable { private: noncopyable(noncopyable const&); noncopyable& operator= (noncopyable const&); };
|
BOOST_NOEXCEPT BOOST_NOEXCEPT_OR_NOTHROW BOOST_NOEXCEPT_IF(Predicate) BOOST_NOEXCEPT_EXPR(Expression)
|
If
If
|
|
For Microsoft Visual C++ 2012, enable the C++11 features supplied by the November 2012 Community Technology Preview. These features are not automatically enabled because the CTP is non-supported alpha code that is not recommended for production use. This macro must be defined before including any Boost headers, and must be defined for all translation units in the program, including Boost library builds. This macro will no longer have any effect once an official Microsoft release supports the CTP features. |
The following macros describe features in the 2014 ISO C++ standard, formerly known as C++0y, that are not yet supported by a particular compiler or library.
Macro |
Description |
---|---|
|
The compiler does not support member initializer for aggregates as in the following example:
|
|
The compiler does not binary literals (e.g. |
|
The compiler does not support relaxed |
|
The compiler does not support |
|
The compiler does not support digit separators (e.g. |
|
The compiler does not support |
|
The compiler does not support generic lambda (e.g. |
|
The standard library does not provide header <shared_mutex>. |
|
The compiler does not support initialized lambda capture (e.g.
|
|
The compiler does not support return type deduction for normal
functions (e.g. |
|
The compiler does not support variable template (e.g. |
The following macros allow use of C++14 features even with compilers that do not yet provide compliant C++14 support.
Macro |
Description |
---|---|
|
This macro works similar to BOOST_CONSTEXPR, but expands to |
The following macros describe features in the 2017 ISO C++ standard, formerly known as C++1z, that are not yet supported by a particular compiler or library.
Macro |
Description |
---|---|
|
The compiler does not support the header |
|
The compiler does not support the header |
|
The compiler does not support the header |
|
The compiler does not support |
|
The compiler does not support |
|
The compiler does not support SFINAE-friendly |
|
The compiler does not support |
The following macros describe features which were required by one version of the standard, but have been removed by later versions.
Macro |
Description |
---|---|
|
The standard library no longer supports |
|
The standard library no longer supports |
|
The standard library no longer supports |
|
The standard library no longer supports |
The following macros are either simple helpers, or macros that provide workarounds for compiler/standard library defects.
Macro |
Description |
---|---|
|
This macro is used where a compiler specific workaround is required that is not otherwise described by one of the other Boost.Config macros. To use the macro you must first #include <boost/config/workaround.hpp> usage is then: #if BOOST_WORKAROUND(MACRONAME, CONDITION) // workaround code goes here... #else // Standard conforming code goes here... #endif
where
The macro can also be used with
For example Note: the ultimate source of documentation for this macro is in boost/config/workaround.hpp. |
|
Sometimes you have a function name with the same name as a C macro, for example "min" and "max" member functions, in which case one can prevent the function being expanded as a macro using: someclass.min BOOST_PREVENT_MACRO_SUBSTITUTION(arg1, arg2); The following also works in most, but not all, contexts: (someclass.max)(arg1, arg2);
|
|
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: |
|
The header to include to get the SGI |
|
The header to include to get the SGI |
|
The header to include to get the SGI |
|
The namespace used for std library extensions (hashtable classes etc). |
|
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); };
|
|
Normally evaluates to nothing, but evaluates to return x; if the compiler requires a return, even when it can never be reached. |
|
The BOOST_FALLTHROUGH macro can be used to annotate implicit fall-through between switch labels: switch (x) { case 40: case 41: if (truth_is_out_there) { ++x; BOOST_FALLTHROUGH; // Use instead of/along with annotations in // comments. } else { return x; } case 42: ... As shown in the example above, the BOOST_FALLTHROUGH macro should be followed by a semicolon. It is designed to mimic control-flow statements like 'break;', so it can be placed in most places where 'break;' can, but only if there are no statements on the execution path between it and the next switch label.
When compiled with Clang >3.2 in C++11 mode, the BOOST_FALLTHROUGH
macro is expanded to When used with unsupported compilers, the BOOST_FALLTHROUGH macro has no effect on diagnostics. In either case this macro has no effect on runtime behavior and performance of code. |
|
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 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 |
|
When the standard library does not have a conforming |
|
When the standard library does not have a comforming |
|
Member templates are supported by some compilers even though they
can't use the |
|
Converts the parameter |
|
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__. |
|
This macro can be used in place of the compiler specific variant
of the C99 Usage example: void perform_computation( float* BOOST_RESTRICT in, float* BOOST_RESTRICT out ) { *out = *in * 0.5f; }
|
|
This macro can be used in place of the Usage example: template<class T> BOOST_FORCEINLINE T& f(T& t) { return t; }
Note that use of this macro can lead to cryptic error messages
with some compilers. Consider defining it to |
|
This macro can be used in place of the Usage example: BOOST_NOINLINE void handle_error(const char* descr) { // ... }
|
|
This macro can be used before the function declaration or definition
to instruct the compiler that the function does not return normally
(i.e. with a Usage example: BOOST_NORETURN void on_error_occurred(const char* descr) { throw std::runtime_error(descr); }
If the compiler does not support this markup, |
|
These macros communicate to the compiler that the conditional expression
The macros are intended to be used in branching statements. The additional hint they provide can be used by the compiler to arrange the compiled code of the branches more effectively. Usage example: if (BOOST_UNLIKELY(ptr == NULL)) handle_error("ptr is NULL");
|
|
Expands to |
|
Expands to |
|
Expands to |
|
Usage example: struct BOOST_MAY_ALIAS aliasing_struct; typedef unsigned int BOOST_MAY_ALIAS aliasing_uint;
|
|
Defined in header
Example:
The messages issued by |
|
Defined in header
Example:
The messages issued by |
The following macros describe boost features; these are, generally speaking the only boost macros that should be tested in user code.
Macro |
Header |
Description |
---|---|---|
|
|
Describes the boost version number in XYYYZZ format such that:
|
|
|
Defined if there are no 64-bit integral types: |
|
|
Defined if |
|
|
Defined if the compiler is really Microsoft Visual C++, as opposed
to one of the many other compilers that also define |
|
|
Defined to a normalised 9 digit version of _MSC_FULL_VER (which sometimes only has 8 digits), the macro has the form VVMMPPPPP where VV is the major version number, MM is the minor version number, and PPPPP is the compiler build number. |
|
|
Defined if the compiler is really GCC, as opposed to one of the
many other compilers that also define |
|
|
Defined if the compiler is an Intel compiler, takes the same value as the compiler version macro. |
|
|
Defined to 1 if the compiler is the Clang compiler. |
|
|
Defined if the Windows platform API is available. |
|
|
Defined if the dinkumware standard library is in use, takes the
same value as the Dinkumware library version macro |
|
|
Defined if the regex library does not support wide character regular expressions. |
|
|
Defined as a string describing the name and version number of the compiler in use. Mainly for debugging the configuration. |
|
|
Defined as a string describing the name and version number of the standard library in use. Mainly for debugging the configuration. |
|
|
Defined as a string describing the name of the platform. Mainly for debugging the configuration. |
The following have been deprecated; please use the replacements instead. They will be removed in a future version of boost.
Deprecated Macro |
Replacement |
When deprecated |
When removed |
---|---|---|---|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.50 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.51 |
|
|
|
Boost 1.53 |
|
|
|
Boost 1.53 |
|
|
|
Boost 1.53 |
|
|
|
Boost 1.53 |
|
|
|
Boost 1.53 |
The following macros and helper headers are of use to authors whose libraries include separate source code, and are intended to address several issues:
See Guidelines for Authors of Boost Libraries Containing Separate Source
Some compilers support C++ extensions that control which symbols will be exported from shared libraries such as dynamic shared objects (DSO's) on Unix-like systems or dynamic-link libraries (DLL's) on Windows.
The Microsoft VC++ compiler has long supplied __declspec(dllexport)
and __declspec(dllimport)
extensions for this purpose, as do virtually
all other compilers targeting the Windows platform.
Modern versions of the GNU GCC compiler provide the __attribute__((visibility("default")))
extension to indicate that a symbol
should be exported. All other symbols may be hidden by using the -fvisibility-hidden
or -fvisibility-ms-compat
compiler switches.
Boost supplies several macros to make it easier to manage symbol visibility in a way that is portable between compilers and operating systems.
Macro |
Description |
---|---|
|
Defines the syntax of a C++ language extension that indicates a symbol is to be exported from a shared library. If the compiler has no such extension, the macro is defined with no replacement text. |
|
Defines the syntax of a C++ language extension that indicates a symbol is to be imported from a shared library. If the compiler has no such extension, the macro is defined with no replacement text. |
|
Defines the syntax of a C++ language extension that indicates a symbol is to be globally visible. If the compiler has no such extension, the macro is defined with no replacement text. Needed for classes that are not otherwise exported, but are used by RTTI. Examples include class for objects that will be thrown as exceptions or used in dynamic_casts, across shared library boundaries. For example, a header-only exception class might look like this: class BOOST_SYMBOL_VISIBLE my_exception : public std::runtime_error { ... }; Without BOOST_SYMBOL_VISIBLE, it would be impossible to catch my_exception thrown from a shared library compiled by GCC with the -fvisibility=hidden option. |
|
The compiler has C++ extensions |
Typical usage:
boost/foo/config.hpp
... #if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_FOO_DYN_LINK) # if defined(BOOST_FOO_SOURCE) # define BOOST_FOO_DECL BOOST_SYMBOL_EXPORT # else # define BOOST_FOO_DECL BOOST_SYMBOL_IMPORT # endif #else # define BOOST_FOO_DECL #endif ...
boost/foo/foo.hpp
#include <boost/foo/config.hpp> ... class BOOST_FOO_DECL bar { ... }; ... void BOOST_FOO_DECL f(); ...
boost/libs/foo/src/foo.cpp
#define BOOST_FOO_SOURCE #include <boost/foo/foo.hpp> ... void BOOST_FOO_DECL f() { ... } ...
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 is:
my_library.hpp
#ifndef MY_INCLUDE_GUARD #define MY_INCLUDE_GUARD // all includes go here:#include <boost/config.hpp>
#include <whatever>#include <boost/config/abi_prefix.hpp>
// must be the last #include namespace boost { // your code goes here }#include <boost/config/abi_suffix.hpp>
// pops abi_prefix.hpp pragmas #endif // include guard
my_library.cpp
... // nothing special need be done in the implementation file ...
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).
BOOST_AUTO_LINK_NOMANGLE
Optional: whan set specifies that we should link to BOOST_LIB_NAME.lib, rather than a mangled-name version.
BOOST_AUTO_LINK_TAGGED
Optional: Specifies that we link to libraries built with the --layout=tagged option. This is essentially the same as the default name-mangled version, but without the compiler name and version, or the Boost version. Just the build options.
BOOST_AUTO_LINK_SYSTEM
Optional: Specifies that we link to libraries built with the --layout=system option. This is essentially the same as the non-name-mangled version, but with the prefix to differentiate static and dll builds
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.
my_library.hpp
... // // Don't include auto-linking code if the user has disabled it by // defining BOOST_ALL_NO_LIB, or BOOST_MY_LIBRARY_NO_LIB, or if this // is one of our own source files (signified by BOOST_MY_LIBRARY_SOURCE): // #if !defined(BOOST_ALL_NO_LIB) && !defined(BOOST_MY_LIBRARY_NO_LIB) && !defined(BOOST_MY_LIBRARY_SOURCE) # define BOOST_LIB_NAME boost_my_library # ifdef BOOST_MY_LIBRARY_DYN_LINK # define BOOST_DYN_LINK # endif # include <boost/config/auto_link.hpp> #endif ...
my_library.cpp
// define BOOST_MY_LIBRARY_SOURCE so that the header knows that the // library is being built (possibly exporting rather than importing code) // #define BOOST_MY_LIBRARY_SOURCE #include <boost/my_library/my_library.hpp> ...