1 2[/ Copyright (C) 2008-2018 Lorenzo Caminiti] 3[/ Distributed under the Boost Software License, Version 1.0 (see accompanying] 4[/ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt).] 5[/ See: http://www.boost.org/doc/libs/release/libs/contract/doc/html/index.html] 6 7[section Getting Started] 8 9This section shows how to setup and start using this library. 10 11[section This Documentation] 12 13Programmers should be able to start using this library after reading the __Introduction__, __Getting_Started__, and __Tutorial__. 14Other 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. 15__Contract_Programming_Overview__ can be skipped by programmers that are already familiar with the contract programming methodology. 16 17Some of the source code listed in this documentation contains special code comments of the form `//[...` and `//]`. 18These mark sections of the code that are automatically extracted from the source code and presented as part of this documentation. 19[footnote 20*Rationale:* 21This 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. 22] 23It 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. 24 25Some footnotes are marked by the word "*Rationale*". 26These explain some of the decisions made during the design and implementation of this library. 27 28[endsect] 29 30[section Compilers and Platforms] 31 32In general, this library requires C++ compilers with a sound implementation of SFINAE and other template meta-programming techniques supported by the C++03 standard. 33It 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__). 34It 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__). 35 36Some parts of this documentation use the syntax [^['type-of](...)] to indicate an operator logically equivalent to C++11 `decltype(...)`. 37However, 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). 38 39This library has been developed and tested using: 40 41* Visual Studio 2015 on Windows (MSVC =cl= version 19.00.24215.1). 42* GCC version 5.4.0 on Cygwin (with C++11 features enabled =-std=c++11=). 43* Clang version 3.8.1 on Cygwin (with C++11 features enabled =-std=c++11=). 44 45For information on other compilers and platforms see the library [@http://www.boost.org/development/tests/master/developer/contract.html regression tests]. 46The development and maintenance of this library is hosted on [@https://github.com/boostorg/contract GitHub]. 47 48[endsect] 49 50[section Code Organization] 51 52Let [^['boost-root]] be the directory where Boost source files were installed. 53This library flies are organized as follows: 54 55[pre 56['boost-root]\/libs\/contract # Directory where this library files are. 57 build/ # Build files (using BJam). 58 doc/ # Documentation (using Boost.QuickBook). 59 example/ # Examples (also those listed in this documentation). 60 include/ # DO NOT USE: Use copies of these files from 61 boost/ # ['boost-root]\/boost/ instead: 62 contract.hpp # - Include all headers at once. 63 contract_macro.hpp # - Include library macro interface. 64 contract/ # - Header files that can be included one-by-one. 65 core/ # - Fundamental headers (usually indirectly included by other headers). 66 detail/ # - Implementation code (should never be included or used directly). 67 src/ # Library source code to be compiled. 68 test/ # Tests. 69] 70 71All headers required by this library can be included at once by: 72 73 #include <boost/contract.hpp> 74 75Or, by the following when using the library macro interface (see __Disable_Contract_Compilation__): 76 77 #include <boost/contract_macro.hpp> 78 79Alternatively, 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). 80The =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. 81 82All 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. 83Names 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). 84 85[endsect] 86 87[section Build] 88 89Let [^['boost-root]] be the directory where Boost source files were installed. 90This library is installed and compiled as part of Boost using BJam. 91 92[warning 93It 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. 94When 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`). 95 96It 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). 97However, this library is not guaranteed to always work correctly in these cases. 98Specifically, 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.). 99] 100 101[heading Linux-Based Systems] 102 103For 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]): 104 105[pre 106$ cd ['boost-root] 107$ .\/bootstrap.sh 108$ .\/bjam 109] 110 111To compile and run the [@../../example/features/introduction.cpp [^['boost-root]\/libs/contract/example/features/introduction.cpp]] example: 112 113[pre 114$ cd ['boost-root]\/libs/contract/example 115$ ..\/..\/..\/bjam features-introduction 116] 117 118To compile and run all this library's tests (this might take while): 119 120[pre 121$ cd ['boost-root]\/libs/contract/test 122$ ..\/..\/..\/bjam 123] 124 125To compile and run code that uses this library but without BJam (similarly for Clang): 126 127[pre 128$ cd /tmp 129$ 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 130$ export PATH=$PATH:['boost-root]\/stage/lib 131$ ./introduction 132] 133 134[heading Windows-Based Systems] 135 136For 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]): 137 138[pre 139>cd ['boost-root] 140>bootstrap.bat 141>bjam 142] 143 144To compile and run the [@../../example/features/introduction.cpp [^['boost-root]\/libs/contract/example/features/introduction.cpp]] example: 145 146[pre 147>cd ['boost-root]\libs\contract\example 148>..\\..\\..\\bjam features-introduction 149] 150 151To compile and run all this library's tests (this might take while): 152 153[pre 154>cd ['boost-root]\libs\contract\test 155>..\\..\\..\\bjam 156] 157 158To compile and run code that uses this library but without BJam: 159 160[pre 161>cd C:\Temp 162>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 163>set PATH=%PATH%;['boost-root]\/stage/lib 164>introduction 165] 166 167[endsect] 168 169[endsect] 170 171