171 lines
8.9 KiB
Plaintext
171 lines
8.9 KiB
Plaintext
|
|
[/ Copyright (C) 2008-2018 Lorenzo Caminiti]
|
|
[/ Distributed under the Boost Software License, Version 1.0 (see accompanying]
|
|
[/ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt).]
|
|
[/ See: http://www.boost.org/doc/libs/release/libs/contract/doc/html/index.html]
|
|
|
|
[section Getting Started]
|
|
|
|
This section shows how to setup and start using this library.
|
|
|
|
[section This Documentation]
|
|
|
|
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.
|
|
[footnote
|
|
*Rationale:*
|
|
This allows to make sure that most of the example code presented in this documentation is always up-to-date, builds and runs with the latest implementation of the library.
|
|
]
|
|
It should be noted that the purpose of all examples of this documentation is to illustrate how to use this library and not to show real production code.
|
|
|
|
Some footnotes are marked by the word "*Rationale*".
|
|
These explain some of the decisions made during the design and implementation of this library.
|
|
|
|
[endsect]
|
|
|
|
[section Compilers and Platforms]
|
|
|
|
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 functors 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 internally already knows the types in question) so support for C++11 `decltype` and other type-of implementations are not actually required (that is why [^['type-of]] and not the real `decltype` operator is used in this documentation).
|
|
|
|
This library has been developed and tested using:
|
|
|
|
* Visual Studio 2015 on Windows (MSVC =cl= version 19.00.24215.1).
|
|
* GCC version 5.4.0 on Cygwin (with C++11 features enabled =-std=c++11=).
|
|
* Clang version 3.8.1 on Cygwin (with C++11 features enabled =-std=c++11=).
|
|
|
|
For information on other compilers and platforms see the library [@http://www.boost.org/development/tests/master/developer/contract.html regression tests].
|
|
The development and maintenance of this library is hosted on [@https://github.com/boostorg/contract GitHub].
|
|
|
|
[endsect]
|
|
|
|
[section Code Organization]
|
|
|
|
Let [^['boost-root]] be the directory where Boost source files were installed.
|
|
This library flies are organized as follows:
|
|
|
|
[pre
|
|
['boost-root]\/libs\/contract # Directory where this library files are.
|
|
build/ # Build files (using BJam).
|
|
doc/ # Documentation (using Boost.QuickBook).
|
|
example/ # Examples (also those listed in this documentation).
|
|
include/ # DO NOT USE: Use copies of these files from
|
|
boost/ # ['boost-root]\/boost/ instead:
|
|
contract.hpp # - Include all headers at once.
|
|
contract_macro.hpp # - Include library macro interface.
|
|
contract/ # - Header files that can be included one-by-one.
|
|
core/ # - Fundamental headers (usually indirectly included by other headers).
|
|
detail/ # - Implementation code (should never be included or used directly).
|
|
src/ # Library source code to be compiled.
|
|
test/ # Tests.
|
|
]
|
|
|
|
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.hpp= 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).
|
|
|
|
[endsect]
|
|
|
|
[section Build]
|
|
|
|
Let [^['boost-root]] be the directory where Boost source files were installed.
|
|
This library is installed and compiled as part of Boost using BJam.
|
|
|
|
[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 [macroref BOOST_CONTRACT_DYN_LINK]) when building Boost.
|
|
When using BJam to build Boost, this can be achieved by the `link=shared` parameter (which is already the default so no extra parameter is actually needed for `bjam`).
|
|
|
|
It is also possible to compile and use this library as a static library (by defining the [macroref BOOST_CONTRACT_STATIC_LINK] macro) or as a header-only library (by leaving both [macroref BOOST_CONTRACT_DYN_LINK] and [macroref BOOST_CONTRACT_STATIC_LINK] undefined).
|
|
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.).
|
|
]
|
|
|
|
[heading Linux-Based Systems]
|
|
|
|
For example, to build all Boost libraries including this one (as shared libraries, see also [@https://www.boost.org/doc/libs/1_70_0/more/getting_started Boost documentation]):
|
|
|
|
[pre
|
|
$ cd ['boost-root]
|
|
$ .\/bootstrap.sh
|
|
$ .\/bjam
|
|
]
|
|
|
|
To compile and run the [@../../example/features/introduction.cpp [^['boost-root]\/libs/contract/example/features/introduction.cpp]] example:
|
|
|
|
[pre
|
|
$ cd ['boost-root]\/libs/contract/example
|
|
$ ..\/..\/..\/bjam features-introduction
|
|
]
|
|
|
|
To compile and run all this library's tests (this might take while):
|
|
|
|
[pre
|
|
$ cd ['boost-root]\/libs/contract/test
|
|
$ ..\/..\/..\/bjam
|
|
]
|
|
|
|
To compile and run code that uses this library but without BJam (similarly for Clang):
|
|
|
|
[pre
|
|
$ cd /tmp
|
|
$ g++ -std=c++11 -D BOOST_CONTRACT_DYN_LINK -I ['boost-root] ['boost-root]\/stage/lib/['system-prefix]boost_contract.dll ['boost-root]\/libs/contract/example/features/introduction.cpp -o introduction
|
|
$ export PATH=$PATH:['boost-root]\/stage/lib
|
|
$ ./introduction
|
|
]
|
|
|
|
[heading Windows-Based Systems]
|
|
|
|
For example, to build all Boost libraries including this one (as DLLs, see also [@https://www.boost.org/doc/libs/1_70_0/more/getting_started Boost documentation]):
|
|
|
|
[pre
|
|
>cd ['boost-root]
|
|
>bootstrap.bat
|
|
>bjam
|
|
]
|
|
|
|
To compile and run the [@../../example/features/introduction.cpp [^['boost-root]\/libs/contract/example/features/introduction.cpp]] example:
|
|
|
|
[pre
|
|
>cd ['boost-root]\libs\contract\example
|
|
>..\\..\\..\\bjam features-introduction
|
|
]
|
|
|
|
To compile and run all this library's tests (this might take while):
|
|
|
|
[pre
|
|
>cd ['boost-root]\libs\contract\test
|
|
>..\\..\\..\\bjam
|
|
]
|
|
|
|
To compile and run code that uses this library but without BJam:
|
|
|
|
[pre
|
|
>cd C:\Temp
|
|
>cl /MDd /EHs /std:c++11 /D BOOST_CONTRACT_DYN_LINK /I ['boost-root] /link /DLL /LIBPATH:['boost-root]\stage\lib ['boost-root]\libs\contract\example\features\introduction.cpp /out:introduction
|
|
>set PATH=%PATH%;['boost-root]\/stage/lib
|
|
>introduction
|
|
]
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|
|
|