1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Getting Started</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Boost.Contract 1.0.0"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.Contract 1.0.0"> 9<link rel="prev" href="full_table_of_contents.html" title="Full Table of Contents"> 10<link rel="next" href="contract_programming_overview.html" title="Contract Programming Overview"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="full_table_of_contents.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="contract_programming_overview.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_contract.getting_started"></a><a class="link" href="getting_started.html" title="Getting Started">Getting Started</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.this_documentation">This 31 Documentation</a></span></dt> 32<dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.compilers_and_platforms">Compilers 33 and Platforms</a></span></dt> 34<dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.code_organization">Code 35 Organization</a></span></dt> 36<dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.build">Build</a></span></dt> 37</dl></div> 38<p> 39 This section shows how to setup and start using this library. 40 </p> 41<div class="section"> 42<div class="titlepage"><div><div><h3 class="title"> 43<a name="boost_contract.getting_started.this_documentation"></a><a class="link" href="getting_started.html#boost_contract.getting_started.this_documentation" title="This Documentation">This 44 Documentation</a> 45</h3></div></div></div> 46<p> 47 Programmers should be able to start using this library after reading the 48 <a class="link" href="../index.html#boost_contract.introduction" title="Introduction">Introduction</a>, <a class="link" href="getting_started.html" title="Getting Started">Getting 49 Started</a>, and <a class="link" href="tutorial.html" title="Tutorial">Tutorial</a>. 50 Other sections of this documentation (e.g., <a class="link" href="advanced.html" title="Advanced">Advanced</a> 51 and <a class="link" href="extras.html" title="Extras">Extras</a>) can be consulted 52 at a later point to gain a more in-depth knowledge of the library. <a class="link" href="contract_programming_overview.html" title="Contract Programming Overview">Contract Programming 53 Overview</a> can be skipped by programmers that are already familiar with 54 the contract programming methodology. 55 </p> 56<p> 57 Some of the source code listed in this documentation contains special code 58 comments of the form <code class="computeroutput"><span class="comment">//[...</span></code> 59 and <code class="computeroutput"><span class="comment">//]</span></code>. These mark sections 60 of the code that are automatically extracted from the source code and presented 61 as part of this documentation. <a href="#ftn.boost_contract.getting_started.this_documentation.f0" class="footnote" name="boost_contract.getting_started.this_documentation.f0"><sup class="footnote">[5]</sup></a> It should be noted that the purpose of all examples of this documentation 62 is to illustrate how to use this library and not to show real production 63 code. 64 </p> 65<p> 66 Some footnotes are marked by the word "<span class="bold"><strong>Rationale</strong></span>". 67 These explain some of the decisions made during the design and implementation 68 of this library. 69 </p> 70</div> 71<div class="section"> 72<div class="titlepage"><div><div><h3 class="title"> 73<a name="boost_contract.getting_started.compilers_and_platforms"></a><a class="link" href="getting_started.html#boost_contract.getting_started.compilers_and_platforms" title="Compilers and Platforms">Compilers 74 and Platforms</a> 75</h3></div></div></div> 76<p> 77 In general, this library requires C++ compilers with a sound implementation 78 of SFINAE and other template meta-programming techniques supported by the 79 C++03 standard. It is possible to use this library without C++11 lambda functions 80 but a large amount of boiler-plate code is required to manually program separate 81 functors to specify preconditions, postconditions, etc. (so using this library 82 without C++11 lambda functions is possible but not recommended, see <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No Lambda 83 Functions</a>). It is also possible to use this library without variadic 84 macros by manually programming a small amount of boiler-plate code (but most 85 if not all modern C++ compilers support variadic macros even before C++99 86 and C++11 so this should never be needed in practice, see <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No 87 Macros</a>). 88 </p> 89<p> 90 Some parts of this documentation use the syntax <code class="literal"><span class="emphasis"><em>type-of</em></span>(...)</code> 91 to indicate an operator logically equivalent to C++11 <code class="computeroutput"><span class="keyword">decltype</span><span class="special">(...)</span></code>. However, this library implementation 92 does not actually use type deduction in these cases (because the library 93 internally already knows the types in question) so support for C++11 <code class="computeroutput"><span class="keyword">decltype</span></code> and other type-of implementations 94 are not actually required (that is why <code class="literal"><span class="emphasis"><em>type-of</em></span></code> 95 and not the real <code class="computeroutput"><span class="keyword">decltype</span></code> operator 96 is used in this documentation). 97 </p> 98<p> 99 This library has been developed and tested using: 100 </p> 101<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 102<li class="listitem"> 103 Visual Studio 2015 on Windows (MSVC <code class="literal">cl</code> version 19.00.24215.1). 104 </li> 105<li class="listitem"> 106 GCC version 5.4.0 on Cygwin (with C++11 features enabled <code class="literal">-std=c++11</code>). 107 </li> 108<li class="listitem"> 109 Clang version 3.8.1 on Cygwin (with C++11 features enabled <code class="literal">-std=c++11</code>). 110 </li> 111</ul></div> 112<p> 113 For information on other compilers and platforms see the library <a href="http://www.boost.org/development/tests/master/developer/contract.html" target="_top">regression 114 tests</a>. The development and maintenance of this library is hosted 115 on <a href="https://github.com/boostorg/contract" target="_top">GitHub</a>. 116 </p> 117</div> 118<div class="section"> 119<div class="titlepage"><div><div><h3 class="title"> 120<a name="boost_contract.getting_started.code_organization"></a><a class="link" href="getting_started.html#boost_contract.getting_started.code_organization" title="Code Organization">Code 121 Organization</a> 122</h3></div></div></div> 123<p> 124 Let <code class="literal"><span class="emphasis"><em>boost-root</em></span></code> be the directory where 125 Boost source files were installed. This library flies are organized as follows: 126 </p> 127<pre class="programlisting"><span class="emphasis"><em>boost-root</em></span>/libs/contract # Directory where this library files are. 128 build/ # Build files (using BJam). 129 doc/ # Documentation (using Boost.QuickBook). 130 example/ # Examples (also those listed in this documentation). 131 include/ # DO NOT USE: Use copies of these files from 132 boost/ # <span class="emphasis"><em>boost-root</em></span>/boost/ instead: 133 contract.hpp # - Include all headers at once. 134 contract_macro.hpp # - Include library macro interface. 135 contract/ # - Header files that can be included one-by-one. 136 core/ # - Fundamental headers (usually indirectly included by other headers). 137 detail/ # - Implementation code (should never be included or used directly). 138 src/ # Library source code to be compiled. 139 test/ # Tests. 140</pre> 141<p> 142 All headers required by this library can be included at once by: 143 </p> 144<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">contract</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 145</pre> 146<p> 147 Or, by the following when using the library macro interface (see <a class="link" href="extras.html#boost_contract.extras.disable_contract_compilation__macro_interface_" title="Disable Contract Compilation (Macro Interface)">Disable 148 Contract Compilation</a>): 149 </p> 150<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">contract_macro</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 151</pre> 152<p> 153 Alternatively, all <code class="literal">boost/contract/*.hpp</code> headers are independent 154 from one another and they can be selectively included one-by-one based on 155 the specific functionality of this library being used (but this was measured 156 to not make an appreciable difference in compile-time so <code class="literal">boost/contract.hpp</code> 157 can be included directly in most cases). The <code class="literal">boost/contract/core/*.hpp</code> 158 headers are not independent from other headers and they do not need to be 159 directly included in user code when <code class="literal">boost/contract.hpp</code> 160 or <code class="literal">boost/contract/*.hpp</code> headers are included already. 161 </p> 162<p> 163 All files under <code class="literal">boost/contract/detail/</code>, names in the 164 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">contract</span><span class="special">::</span><span class="identifier">detail</span></code> namespace, macros starting with 165 <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_DETAIL</span><span class="special">...</span></code>, 166 and all names starting with <code class="computeroutput"><span class="identifier">boost_contract_detail</span><span class="special">...</span></code> (in any namespace, including user-defined 167 namespaces) are part of this library implementation and should never be used 168 directly in user code. Names starting with <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_ERROR</span><span class="special">...</span></code> are used by this library to report some 169 compile-time errors (so spotting these names in compiler error messages might 170 help troubleshooting). 171 </p> 172</div> 173<div class="section"> 174<div class="titlepage"><div><div><h3 class="title"> 175<a name="boost_contract.getting_started.build"></a><a class="link" href="getting_started.html#boost_contract.getting_started.build" title="Build">Build</a> 176</h3></div></div></div> 177<p> 178 Let <code class="literal"><span class="emphasis"><em>boost-root</em></span></code> be the directory where 179 Boost source files were installed. This library is installed and compiled 180 as part of Boost using BJam. 181 </p> 182<div class="warning"><table border="0" summary="Warning"> 183<tr> 184<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td> 185<th align="left">Warning</th> 186</tr> 187<tr><td align="left" valign="top"> 188<p> 189 It is strongly recommended to compile and use this library as a shared 190 library (a.k.a., Dynamically Linked Library or DLL) by defining the <code class="computeroutput"><span class="identifier">BOOST_ALL_DYN_LINK</span></code> macro (or at least 191 <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_DYN_LINK.html" title="Macro BOOST_CONTRACT_DYN_LINK">BOOST_CONTRACT_DYN_LINK</a></code>) 192 when building Boost. When using BJam to build Boost, this can be achieved 193 by the <code class="computeroutput"><span class="identifier">link</span><span class="special">=</span><span class="identifier">shared</span></code> parameter (which is already the 194 default so no extra parameter is actually needed for <code class="computeroutput"><span class="identifier">bjam</span></code>). 195 </p> 196<p> 197 It is also possible to compile and use this library as a static library 198 (by defining the <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_STATIC_LINK.html" title="Macro BOOST_CONTRACT_STATIC_LINK">BOOST_CONTRACT_STATIC_LINK</a></code> 199 macro) or as a header-only library (by leaving both <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_DYN_LINK.html" title="Macro BOOST_CONTRACT_DYN_LINK">BOOST_CONTRACT_DYN_LINK</a></code> 200 and <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_STATIC_LINK.html" title="Macro BOOST_CONTRACT_STATIC_LINK">BOOST_CONTRACT_STATIC_LINK</a></code> 201 undefined). However, this library is not guaranteed to always work correctly 202 in these cases. Specifically, this library might not correctly disable 203 contracts while checking other contracts and call the correct user-defined 204 contract failure handlers unless it is compiled as a shared library when 205 it is used across different program units (different programs, different 206 shared libraries in the same program, etc.). 207 </p> 208</td></tr> 209</table></div> 210<h5> 211<a name="boost_contract.getting_started.build.h0"></a> 212 <span class="phrase"><a name="boost_contract.getting_started.build.linux_based_systems"></a></span><a class="link" href="getting_started.html#boost_contract.getting_started.build.linux_based_systems">Linux-Based 213 Systems</a> 214 </h5> 215<p> 216 For example, to build all Boost libraries including this one (as shared libraries, 217 see also <a href="https://www.boost.org/doc/libs/1_70_0/more/getting_started" target="_top">Boost 218 documentation</a>): 219 </p> 220<pre class="programlisting">$ cd <span class="emphasis"><em>boost-root</em></span> 221$ ./bootstrap.sh 222$ ./bjam 223</pre> 224<p> 225 To compile and run the <a href="../../../example/features/introduction.cpp" target="_top"><code class="literal"><span class="emphasis"><em>boost-root</em></span>/libs/contract/example/features/introduction.cpp</code></a> 226 example: 227 </p> 228<pre class="programlisting">$ cd <span class="emphasis"><em>boost-root</em></span>/libs/contract/example 229$ ../../../bjam features-introduction 230</pre> 231<p> 232 To compile and run all this library's tests (this might take while): 233 </p> 234<pre class="programlisting">$ cd <span class="emphasis"><em>boost-root</em></span>/libs/contract/test 235$ ../../../bjam 236</pre> 237<p> 238 To compile and run code that uses this library but without BJam (similarly 239 for Clang): 240 </p> 241<pre class="programlisting">$ cd /tmp 242$ g++ -std=c++11 -D BOOST_CONTRACT_DYN_LINK -I <span class="emphasis"><em>boost-root</em></span> <span class="emphasis"><em>boost-root</em></span>/stage/lib/<span class="emphasis"><em>system-prefix</em></span>boost_contract.dll <span class="emphasis"><em>boost-root</em></span>/libs/contract/example/features/introduction.cpp -o introduction 243$ export PATH=$PATH:<span class="emphasis"><em>boost-root</em></span>/stage/lib 244$ ./introduction 245</pre> 246<h5> 247<a name="boost_contract.getting_started.build.h1"></a> 248 <span class="phrase"><a name="boost_contract.getting_started.build.windows_based_systems"></a></span><a class="link" href="getting_started.html#boost_contract.getting_started.build.windows_based_systems">Windows-Based 249 Systems</a> 250 </h5> 251<p> 252 For example, to build all Boost libraries including this one (as DLLs, see 253 also <a href="https://www.boost.org/doc/libs/1_70_0/more/getting_started" target="_top">Boost 254 documentation</a>): 255 </p> 256<pre class="programlisting">>cd <span class="emphasis"><em>boost-root</em></span> 257>bootstrap.bat 258>bjam 259</pre> 260<p> 261 To compile and run the <a href="../../../example/features/introduction.cpp" target="_top"><code class="literal"><span class="emphasis"><em>boost-root</em></span>/libs/contract/example/features/introduction.cpp</code></a> 262 example: 263 </p> 264<pre class="programlisting">>cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\example 265>..\..\..\bjam features-introduction 266</pre> 267<p> 268 To compile and run all this library's tests (this might take while): 269 </p> 270<pre class="programlisting">>cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\test 271>..\..\..\bjam 272</pre> 273<p> 274 To compile and run code that uses this library but without BJam: 275 </p> 276<pre class="programlisting">>cd C:\Temp 277>cl /MDd /EHs /std:c++11 /D BOOST_CONTRACT_DYN_LINK /I <span class="emphasis"><em>boost-root</em></span> /link /DLL /LIBPATH:<span class="emphasis"><em>boost-root</em></span>\stage\lib <span class="emphasis"><em>boost-root</em></span>\libs\contract\example\features\introduction.cpp /out:introduction 278>set PATH=%PATH%;<span class="emphasis"><em>boost-root</em></span>/stage/lib 279>introduction 280</pre> 281</div> 282<div class="footnotes"> 283<br><hr style="width:100; text-align:left;margin-left: 0"> 284<div id="ftn.boost_contract.getting_started.this_documentation.f0" class="footnote"><p><a href="#boost_contract.getting_started.this_documentation.f0" class="para"><sup class="para">[5] </sup></a> 285 <span class="bold"><strong>Rationale:</strong></span> This allows to make sure that 286 most of the example code presented in this documentation is always up-to-date, 287 builds and runs with the latest implementation of the library. 288 </p></div> 289</div> 290</div> 291<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 292<td align="left"></td> 293<td align="right"><div class="copyright-footer">Copyright © 2008-2019 Lorenzo Caminiti<p> 294 Distributed under the Boost Software License, Version 1.0 (see accompanying 295 file LICENSE_1_0.txt or a copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 296 </p> 297</div></td> 298</tr></table> 299<hr> 300<div class="spirit-nav"> 301<a accesskey="p" href="full_table_of_contents.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="contract_programming_overview.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 302</div> 303</body> 304</html> 305
