generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
boost/libs/contract/doc/html/boost_contract/getting_started.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

305 lines
20 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<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">&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>
</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">&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>
</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">&gt;cd <span class="emphasis"><em>boost-root</em></span>
&gt;bootstrap.bat
&gt;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">&gt;cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\example
&gt;..\..\..\bjam features-introduction
</pre>
<p>
To compile and run all this library's tests (this might take while):
</p>
<pre class="programlisting">&gt;cd <span class="emphasis"><em>boost-root</em></span>\libs\contract\test
&gt;..\..\..\bjam
</pre>
<p>
To compile and run code that uses this library but without BJam:
</p>
<pre class="programlisting">&gt;cd C:\Temp
&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
&gt;set PATH=%PATH%;<span class="emphasis"><em>boost-root</em></span>/stage/lib
&gt;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>
Reference in New Issue View Git Blame Copy Permalink