mirror of
https://github.com/boostorg/contract.git
synced 2026-02-26 16:42:19 +00:00
162 lines
9.3 KiB
Plaintext
162 lines
9.3 KiB
Plaintext
|
|
[/ Copyright (C) 2008-2016 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 gives preliminary information to get oriented in using this library.
|
|
|
|
[section This Documentation]
|
|
|
|
Programmers should be able to start using this library after reading the __Introduction__, __Getting_Started__, and __Tutorial__ sections.
|
|
The __Advanced_Topics__ and other sections of this documentation can be consulted at a later point to gain a more in-depth knowledge of the library.
|
|
|
|
Some of the source code of the examples linked by this documentation contains special code comments of the form `//[...` and `//]`.
|
|
These mark sections of the code that are automatically extracted from the source 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.
|
|
]
|
|
Also the purpose of these examples 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 reasons behind decisions made during the design and implementation of this library.
|
|
|
|
[endsect]
|
|
|
|
[section Compilers and Platforms]
|
|
|
|
In general, this library requires a C++ compiler with support for SFINAE and other template meta-programming techniques part of the C++03 standard.
|
|
This library requires Boost (Boost.Optional, Boost.Thread, Boost.FunctionTypes, Boost.Traits, Boost.MPL, etc.).
|
|
|
|
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 functions to specify preconditions and postconditions (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 modern C++ compilers support variadic macros even before C++99 and C++11, see __No_Macros__).
|
|
|
|
Some parts of this documentation use an operator [^['type-of](...)] to indicate an operator equivalent to C++11 `decltype(...)`.
|
|
However, this library does not actually use type deduction in these cases (because the library already knows the types in question) so C++11 `decltype` and other type-of implementations are not required to compile this library (that is why [^['type-of]] and not the actual `decltype` operator is used in these cases).
|
|
|
|
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=).
|
|
* Boost C++ libraries version 1.62.0.
|
|
|
|
[endsect]
|
|
|
|
[section Code Organization]
|
|
|
|
Let [^['lib-root]] be the directory under which this library source files have been installed.
|
|
This library flies are organized as follows:
|
|
|
|
[pre
|
|
['lib-root/] # Directory where this library files were installed.
|
|
build/ # Build files (using Boost.Jam).
|
|
doc/ # Documentation (using Boost.QuickBook).
|
|
html/ # This documentation (HTML).
|
|
example/ # Examples (including those listed in this documentation).
|
|
include/
|
|
boost/
|
|
contract.hpp # Include all headers at once.
|
|
contract/ # Header files to 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>
|
|
|
|
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 (this might somewhat reduce compilation time).
|
|
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.
|
|
|
|
Files in =boost/contract/detail/=, names in the `boost::contract::detail` namespace, macros starting with `BOOST_CONTRACT_DETAIL...`, and 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 error messages reported by the compiler might help troubleshooting).
|
|
|
|
[endsect]
|
|
|
|
[section Install and Compile]
|
|
|
|
Let [^['lib-root]] be the directory under which this library source files have been installed.
|
|
Let [^['boost-root]] be the directory under which Boost source code has been installed and compiled following Boost's documentation (if pre-compiled Boost distributions are used instead, the [^['lib-boost]\/include] and [^['lib-boost]\/stage\/lib] directories below might be replaced by =/usr/include= and =/usr/lib= or similar directories depending on the specific Boost distribution, OS, etc.).
|
|
|
|
The steps below show how to compile this library as a shared library (a.k.a., Dynamically Linked Library or DLL) and then compile and run a sample program that uses this library (the [@../../example/features/introduction.cpp =introduction.cpp=] program shown in __Introduction__ is used as an example).
|
|
|
|
[warning
|
|
By default, this library is compiled as a shared library (in which case this library automatically defines the [macroref BOOST_CONTRACT_DYN_LINK] macro).
|
|
[footnote
|
|
*Rationale:*
|
|
[macroref BOOST_CONTRACT_DYN_LINK] is named similarly to [macroref BOOST_ALL_DYN_LINK].
|
|
]
|
|
|
|
There are configuration macros [macroref BOOST_CONTRACT_STATIC_LINK] and [macroref BOOST_CONTRACT_HEADER_ONLY] that can be defined to compile this library as a static or header-only library respectively.
|
|
[footnote
|
|
*Rationale:*
|
|
[macroref BOOST_CONTRACT_STATIC_LINK] and [macroref BOOST_CONTRACT_HEADER_ONLY] are named similarly to `BOOST_ALL_DYN_LINK` and `BOOST_CHRONO_HEADER_ONLY`.
|
|
]
|
|
|
|
However, the use of [macroref BOOST_CONTRACT_STATIC_LINK] and [macroref BOOST_CONTRACT_HEADER_ONLY] is strongly discouraged because this library is not guaranteed to always work correctly at run-time when these macros are defined.
|
|
Specifically, this library will 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 being used by different program units (different programs, different libraries of the same program, etc.).
|
|
]
|
|
|
|
Using MSVC on Windows (from a developer command prompt that automatically invokes the correct =vcvarsall.bat=):
|
|
|
|
[pre
|
|
> cd ['lib-root]\build
|
|
> cl ['lib-root]\src\contract.cpp \/MDd \/EHs -I ['lib-root]\include -I ['boost-root] /link /DLL /LIBPATH:['boost-root]\stage\lib /out:boost_contract.dll
|
|
]
|
|
|
|
[pre
|
|
> cd ['lib-root]\example\features
|
|
> cl introduction.cpp \/MDd \/EHs -I ['lib-root]\include -I ['boost-root] /link /LIBPATH:['boost-root]\stage\lib ['lib-root]\build\boost_contract.lib
|
|
]
|
|
|
|
[pre
|
|
> set PATH=%PATH%;['lib-root]\build
|
|
> introduction
|
|
]
|
|
|
|
Using GCC on Cygwin (and some Linux-like OS):
|
|
|
|
[pre
|
|
$ cd ['lib-root]\/build
|
|
$ g++ ['lib-root]\/src\/contract.cpp -std=c++11 -shared -I ['lib-root]\/include -I ['boost-root] ['boost-root]\/stage\/lib\/libboost_system.a -o boost_contract.dll
|
|
]
|
|
|
|
[pre
|
|
$ cd ['lib-root]\/example\/features
|
|
$ g++ introduction.cpp -std=c++11 -I ['lib-root]\/include -I ['boost-root] ['lib-root]\/build\/boost_contract.dll -o introduction
|
|
]
|
|
|
|
[pre
|
|
$ export PATH=$PATH:['lib-root]\/build
|
|
$ .\/introduction
|
|
]
|
|
|
|
The above steps also work for Clang using =clang++= instead of =g++=.
|
|
|
|
Alternatively, programmers can setup their build environments (BJam, Make, CMake, MSBuild, etc.) to compile this library source code into a shared library and then compile and link user code against it (if that is preferred instead of manually running the compiler as indicated by the steps above).
|
|
For example, this library source comes with a complete set of Boost.Build (BJam) files that can be used to build the library, build and run its tests and examples (see [@../../example/Jamfile.v2 =example/Jamfile.v2=], [@../../test/Jamfile.v2 =test/Jamfile.v2=], [@../../build/Jamfile.v2 =build/Jamfile.v2=], [@../../build/boost_contract_no.jam =build/boost_contract_no.jam=], [@../../Jamroot =Jammroot=], etc.).
|
|
Assuming that:
|
|
|
|
* Boost was installed and built from source.
|
|
* An environment variable named `BOOST_ROOT` is set to the [^['boost-root]] directory path.
|
|
* The `bjam` program can be found in the `PATH` environment variable.
|
|
|
|
Then the following uses BJam to build and run the [@../../example/features/introduction.cpp =introduction.cpp=] program and also to automatically build this library when necessary:
|
|
|
|
[pre
|
|
> cd ['lib-root]\example
|
|
> bjam features-introduction
|
|
]
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|
|
|