libs/contract/doc/html/boost_contract/getting_started.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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&#160;1.&#160;Boost.Contract 1.0.0">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;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">&lt;</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">&gt;</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">&lt;</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">&gt;</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">&gt;cd <span class="emphasis"><em>boost-root</em></span>
 257 &gt;bootstrap.bat
 258 &gt;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">&gt;cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\example
 265 &gt;..\..\..\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">&gt;cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\test
 271 &gt;..\..\..\bjam
 272 </pre>
 273 <p>
 274         To compile and run code that uses this library but without BJam:
 275       </p>
 276 <pre class="programlisting">&gt;cd C:\Temp
 277 &gt;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 &gt;set PATH=%PATH%;<span class="emphasis"><em>boost-root</em></span>/stage/lib
 279 &gt;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 &#169; 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>