123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304 |
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
- <title>Getting Started</title>
- <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
- <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
- <link rel="home" href="../index.html" title="Chapter 1. Boost.Contract 1.0.0">
- <link rel="up" href="../index.html" title="Chapter 1. Boost.Contract 1.0.0">
- <link rel="prev" href="full_table_of_contents.html" title="Full Table of Contents">
- <link rel="next" href="contract_programming_overview.html" title="Contract Programming Overview">
- </head>
- <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
- <table cellpadding="2" width="100%"><tr>
- <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
- <td align="center"><a href="../../../../../index.html">Home</a></td>
- <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
- <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
- <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
- <td align="center"><a href="../../../../../more/index.htm">More</a></td>
- </tr></table>
- <hr>
- <div class="spirit-nav">
- <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>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h2 class="title" style="clear: both">
- <a name="boost_contract.getting_started"></a><a class="link" href="getting_started.html" title="Getting Started">Getting Started</a>
- </h2></div></div></div>
- <div class="toc"><dl class="toc">
- <dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.this_documentation">This
- Documentation</a></span></dt>
- <dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.compilers_and_platforms">Compilers
- and Platforms</a></span></dt>
- <dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.code_organization">Code
- Organization</a></span></dt>
- <dt><span class="section"><a href="getting_started.html#boost_contract.getting_started.build">Build</a></span></dt>
- </dl></div>
- <p>
- This section shows how to setup and start using this library.
- </p>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <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
- Documentation</a>
- </h3></div></div></div>
- <p>
- Programmers should be able to start using this library after reading the
- <a class="link" href="../index.html#boost_contract.introduction" title="Introduction">Introduction</a>, <a class="link" href="getting_started.html" title="Getting Started">Getting
- Started</a>, and <a class="link" href="tutorial.html" title="Tutorial">Tutorial</a>.
- Other sections of this documentation (e.g., <a class="link" href="advanced.html" title="Advanced">Advanced</a>
- and <a class="link" href="extras.html" title="Extras">Extras</a>) can be consulted
- 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
- Overview</a> can be skipped by programmers that are already familiar with
- the contract programming methodology.
- </p>
- <p>
- Some of the source code listed in this documentation contains special code
- comments of the form <code class="computeroutput"><span class="comment">//[...</span></code>
- and <code class="computeroutput"><span class="comment">//]</span></code>. These mark sections
- of the code that are automatically extracted from the source code and presented
- 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
- is to illustrate how to use this library and not to show real production
- code.
- </p>
- <p>
- Some footnotes are marked by the word "<span class="bold"><strong>Rationale</strong></span>".
- These explain some of the decisions made during the design and implementation
- of this library.
- </p>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <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
- and Platforms</a>
- </h3></div></div></div>
- <p>
- 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 <a class="link" href="extras.html#boost_contract.extras.no_lambda_functions__no_c__11_" title="No Lambda Functions (No C++11)">No Lambda
- Functions</a>). 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 <a class="link" href="extras.html#boost_contract.extras.no_macros__and_no_variadic_macros_" title="No Macros (and No Variadic Macros)">No
- Macros</a>).
- </p>
- <p>
- Some parts of this documentation use the syntax <code class="literal"><span class="emphasis"><em>type-of</em></span>(...)</code>
- 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
- does not actually use type deduction in these cases (because the library
- 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
- are not actually required (that is why <code class="literal"><span class="emphasis"><em>type-of</em></span></code>
- and not the real <code class="computeroutput"><span class="keyword">decltype</span></code> operator
- is used in this documentation).
- </p>
- <p>
- This library has been developed and tested using:
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- Visual Studio 2015 on Windows (MSVC <code class="literal">cl</code> version 19.00.24215.1).
- </li>
- <li class="listitem">
- GCC version 5.4.0 on Cygwin (with C++11 features enabled <code class="literal">-std=c++11</code>).
- </li>
- <li class="listitem">
- Clang version 3.8.1 on Cygwin (with C++11 features enabled <code class="literal">-std=c++11</code>).
- </li>
- </ul></div>
- <p>
- 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
- tests</a>. The development and maintenance of this library is hosted
- on <a href="https://github.com/boostorg/contract" target="_top">GitHub</a>.
- </p>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <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
- Organization</a>
- </h3></div></div></div>
- <p>
- Let <code class="literal"><span class="emphasis"><em>boost-root</em></span></code> be the directory where
- Boost source files were installed. This library flies are organized as follows:
- </p>
- <pre class="programlisting"><span class="emphasis"><em>boost-root</em></span>/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/ # <span class="emphasis"><em>boost-root</em></span>/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.
- </pre>
- <p>
- All headers required by this library can be included at once by:
- </p>
- <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>
- </pre>
- <p>
- 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
- Contract Compilation</a>):
- </p>
- <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>
- </pre>
- <p>
- Alternatively, all <code class="literal">boost/contract/*.hpp</code> 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 <code class="literal">boost/contract.hpp</code>
- can be included directly in most cases). The <code class="literal">boost/contract/core/*.hpp</code>
- headers are not independent from other headers and they do not need to be
- directly included in user code when <code class="literal">boost/contract.hpp</code>
- or <code class="literal">boost/contract/*.hpp</code> headers are included already.
- </p>
- <p>
- All files under <code class="literal">boost/contract/detail/</code>, names in the
- <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
- <code class="computeroutput"><span class="identifier">BOOST_CONTRACT_DETAIL</span><span class="special">...</span></code>,
- 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
- namespaces) are part of this library implementation and should never be used
- 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
- compile-time errors (so spotting these names in compiler error messages might
- help troubleshooting).
- </p>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h3 class="title">
- <a name="boost_contract.getting_started.build"></a><a class="link" href="getting_started.html#boost_contract.getting_started.build" title="Build">Build</a>
- </h3></div></div></div>
- <p>
- Let <code class="literal"><span class="emphasis"><em>boost-root</em></span></code> be the directory where
- Boost source files were installed. This library is installed and compiled
- as part of Boost using BJam.
- </p>
- <div class="warning"><table border="0" summary="Warning">
- <tr>
- <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
- <th align="left">Warning</th>
- </tr>
- <tr><td align="left" valign="top">
- <p>
- 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 <code class="computeroutput"><span class="identifier">BOOST_ALL_DYN_LINK</span></code> macro (or at least
- <code class="computeroutput"><a class="link" href="../BOOST_CONTRACT_DYN_LINK.html" title="Macro BOOST_CONTRACT_DYN_LINK">BOOST_CONTRACT_DYN_LINK</a></code>)
- when building Boost. When using BJam to build Boost, this can be achieved
- 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
- default so no extra parameter is actually needed for <code class="computeroutput"><span class="identifier">bjam</span></code>).
- </p>
- <p>
- It is also possible to compile and use this library as a static library
- (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>
- 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>
- 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>
- 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.).
- </p>
- </td></tr>
- </table></div>
- <h5>
- <a name="boost_contract.getting_started.build.h0"></a>
- <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
- Systems</a>
- </h5>
- <p>
- For example, to build all Boost libraries including this one (as shared libraries,
- see also <a href="https://www.boost.org/doc/libs/1_70_0/more/getting_started" target="_top">Boost
- documentation</a>):
- </p>
- <pre class="programlisting">$ cd <span class="emphasis"><em>boost-root</em></span>
- $ ./bootstrap.sh
- $ ./bjam
- </pre>
- <p>
- 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>
- example:
- </p>
- <pre class="programlisting">$ cd <span class="emphasis"><em>boost-root</em></span>/libs/contract/example
- $ ../../../bjam features-introduction
- </pre>
- <p>
- To compile and run all this library's tests (this might take while):
- </p>
- <pre class="programlisting">$ cd <span class="emphasis"><em>boost-root</em></span>/libs/contract/test
- $ ../../../bjam
- </pre>
- <p>
- To compile and run code that uses this library but without BJam (similarly
- for Clang):
- </p>
- <pre class="programlisting">$ cd /tmp
- $ 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
- $ export PATH=$PATH:<span class="emphasis"><em>boost-root</em></span>/stage/lib
- $ ./introduction
- </pre>
- <h5>
- <a name="boost_contract.getting_started.build.h1"></a>
- <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
- Systems</a>
- </h5>
- <p>
- For example, to build all Boost libraries including this one (as DLLs, see
- also <a href="https://www.boost.org/doc/libs/1_70_0/more/getting_started" target="_top">Boost
- documentation</a>):
- </p>
- <pre class="programlisting">>cd <span class="emphasis"><em>boost-root</em></span>
- >bootstrap.bat
- >bjam
- </pre>
- <p>
- 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>
- example:
- </p>
- <pre class="programlisting">>cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\example
- >..\..\..\bjam features-introduction
- </pre>
- <p>
- To compile and run all this library's tests (this might take while):
- </p>
- <pre class="programlisting">>cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\test
- >..\..\..\bjam
- </pre>
- <p>
- To compile and run code that uses this library but without BJam:
- </p>
- <pre class="programlisting">>cd C:\Temp
- >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
- >set PATH=%PATH%;<span class="emphasis"><em>boost-root</em></span>/stage/lib
- >introduction
- </pre>
- </div>
- <div class="footnotes">
- <br><hr style="width:100; text-align:left;margin-left: 0">
- <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>
- <span class="bold"><strong>Rationale:</strong></span> 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.
- </p></div>
- </div>
- </div>
- <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
- <td align="left"></td>
- <td align="right"><div class="copyright-footer">Copyright © 2008-2019 Lorenzo Caminiti<p>
- Distributed under the Boost Software License, Version 1.0 (see accompanying
- 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>)
- </p>
- </div></td>
- </tr></table>
- <hr>
- <div class="spirit-nav">
- <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>
- </div>
- </body>
- </html>
|