Boost C++ Libraries

Programmers should be able to start using this library after reading the Introduction, Getting Started, and Tutorial. Other sections of this documentation (e.g., Advanced and Extras) can be consulted at a later point to gain a more in-depth knowledge of the library. Contract Programming Overview can be skipped by programmers that are already familiar with the contract programming methodology.

Some of the source code listed in this documentation contains special code comments of the form //[... and //]. These mark sections of the code that are automatically extracted from the source code and presented as part of this documentation. ^[6] It should be noted that the purpose of all examples of this documentation is to illustrate how to use this library and not to represent real product code.

Some footnotes are marked by the word "Rationale". These explain some of the decisions made during the design and implementation of this library.

In general, this library requires C++ compilers with a sound implementation of SFINAE and other template meta-programming techniques supported by the C++03 standard. It is possible to use this library without C++11 lambda functions but a large amount of boiler-plate code is required to manually program separate functor to specify preconditions, postconditions, etc. (so using this library without C++11 lambda functions is possible but not recommended, see No Lambda Functions). It is also possible to use this library without variadic macros by manually programming a small amount of boiler-plate code (but most if not all modern C++ compilers support variadic macros even before C++99 and C++11 so this should never be needed in practice, see No Macros).

Some parts of this documentation use the syntax type-of(...) to indicate an operator logically equivalent to C++11 decltype(...). However, this library implementation does not actually use type deduction in these cases (because the library already knows the types in question) so support for C++11 decltype and other type-of implementations are not actually required by this library (that is why type-of and not the real decltype operator is used in this documentation).

This library has been developed and tested using:

For information on other compilers and platforms see the library regression tests.

Warning

It is strongly recommended to compile and use this library as a shared library (a.k.a., Dynamically Linked Library or DLL) by defining the BOOST_ALL_DYN_LINK macro (or at least BOOST_CONTRACT_DYN_LINK) when building Boost. It is possible to compile and use this library as a static library (by defining the BOOST_CONTRACT_STATIC_LINK macro) or as a header-only library (by leaving both BOOST_CONTRACT_DYN_LINK and BOOST_CONTRACT_STATIC_LINK undefined, as by default). However, this library is not guaranteed to always work correctly in these cases. Specifically, this library might not correctly disable contracts while checking other contracts and call the correct user-defined contract failure handlers unless it is compiled as a shared library when it is used across different program units (different programs, different shared libraries in the same program, etc.).

All headers required by this library can be included at once by:

#include <boost/contract.hpp>

Or, by the following when using the library macro interface (see Disable Contract Compilation):

#include <boost/contract_macro.hpp>

Alternatively, all boost/contract/*.hpp headers are independent from one another and they can be selectively included one-by-one based on the specific functionality of this library being used (but this was measured to not make an appreciable difference in compile-time so boost/contract.hp can be included directly in most cases). The boost/contract/core/*.hpp headers are not independent from other headers and they do not need to be directly included in user code when boost/contract.hpp or boost/contract/*.hpp headers are included already.

All files under boost/contract/detail/, names in the boost::contract::detail namespace, macros starting with BOOST_CONTRACT_DETAIL..., and all names starting with boost_contract_detail... (in any namespace, including user-defined namespaces) are part of this library implementation and should never be used directly in user code. Names starting with BOOST_CONTRACT_ERROR... are used by this library to report some compile-time errors (so spotting these names in compiler error messages might help troubleshooting).