123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170 |
- [/ 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]
|