• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
3<title>Build and install - Boost.Outcome documentation</title>
4<link rel="stylesheet" href="./css/boost.css" type="text/css">
5<meta name="generator" content="Hugo 0.52 with Boostdoc theme">
6<meta name="viewport" content="width=device-width,initial-scale=1.0"/>
7
8<link rel="icon" href="./images/favicon.ico" type="image/ico"/>
9<body><div class="spirit-nav">
10<a accesskey="p" href="./requirements.html"><img src="./images/prev.png" alt="Prev"></a>
11    <a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
12    <a accesskey="h" href="./index.html"><img src="./images/home.png" alt="Home"></a><a accesskey="n" href="./motivation.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">
13
14  <div class="titlepage"><div><div><h1 style="clear: both">Build and install</h1></div></div></div>
15
16
17<h2 id="usage-as-a-single-header-file">Usage as a single header file</h2>
18
19<p>Outcome v2 comes in single header file form. This is regenerated per commit. To fetch
20on Linux:</p>
21
22<pre><code>wget https://github.com/ned14/outcome/raw/master/single-header/outcome.hpp
23</code></pre>
24
25<p>On BSD:</p>
26
27<pre><code>fetch https://github.com/ned14/outcome/raw/master/single-header/outcome.hpp
28</code></pre>
29
30<p>If you have <code>curl</code> installed:</p>
31
32<pre><code>curl -O -J -L https://github.com/ned14/outcome/raw/master/single-header/outcome.hpp
33</code></pre>
34
35<p>Otherwise, simply download the raw file from above and place it wherever it suits you.
36If you might be debugging using Microsoft Visual Studio, you may find the debugger
37visualisation file at <a href="https://github.com/ned14/outcome/raw/master/include/outcome/outcome.natvis">https://github.com/ned14/outcome/raw/master/include/outcome/outcome.natvis</a>
38useful to include into your build.</p>
39
40<h2 id="usage-from-the-conan-package-manager">Usage from the Conan package manager</h2>
41
42<p><em>(thanks to Théo Delrieu for contributing this support)</em></p>
43
44<p>At the command line, add the bintray repo for Outcome to conan:</p>
45
46<pre><code>conan remote add outcome https://api.bintray.com/conan/ned14/Outcome
47</code></pre>
48
49<p>Now simply add this to your Conan build:</p>
50
51<pre><code>[requires]
52Outcome/master@ned14/stable
53</code></pre>
54
55<p>Outcome will be made available by Conan at <code>&lt;outcome.hpp&gt;</code>.</p>
56
57<h2 id="usage-from-the-cmake-hunter-package-manager">Usage from the cmake hunter package manager</h2>
58
59<p>Outcome has not been submitted to the main cmake hunter package manager repo as
60it changes too frequently. You can however add it as a git submodule:</p>
61
62<pre><code>cd yourthirdpartyrepodir
63git submodule add https://github.com/ned14/quickcpplib
64git submodule add https://github.com/ned14/outcome
65cd ..
66git submodule update --init --recursive
67</code></pre>
68
69<p>Now tell cmake hunter about a git submoduled cmake hunter package by
70adding to your project&rsquo;s <code>cmake/Hunter/config.cmake</code>:</p>
71
72<pre><code>hunter_config(quickcpplib GIT_SUBMODULE &quot;yourthirdpartyrepodir/quickcpplib&quot;)
73hunter_config(outcome GIT_SUBMODULE &quot;yourthirdpartyrepodir/outcome&quot;)
74</code></pre>
75
76<p>&hellip; and finally to your <code>CMakeLists.txt</code>, now add outcome as if it were
77an ordinary cmake hunter package:</p>
78
79<pre><code>hunter_add_package(quickcpplib)
80find_package(quickcpplib CONFIG REQUIRED)
81hunter_add_package(outcome)
82find_package(outcome CONFIG REQUIRED)
83</code></pre>
84
85<p>Now you tell cmake to link to outcome as usual (see below for cmake targets):</p>
86
87<pre><code>target_link_libraries(mytarget outcome::hl)
88</code></pre>
89
90<h2 id="usage-as-a-git-submodule">Usage as a git submodule</h2>
91
92<p>If you are very keen on tracking very latest Outcome, you can add it as a git
93submodule to your project so you can keep abreast of bug fixes. Here is how:</p>
94
95<pre><code>git submodule add https://github.com/ned14/outcome
96cd outcome
97git checkout master
98git submodule update --init --recursive
99</code></pre>
100
101<p>After this you can bring Outcome into your code using:</p>
102
103<pre><code>#include &quot;outcome/single-header/outcome.hpp&quot;
104</code></pre>
105
106<p>That&rsquo;s it, you are ready to go. From time to time, you may wish to update to
107latest:</p>
108
109<pre><code>cd outcome
110git pull
111git submodule update
112</code></pre>
113
114<h2 id="usage-as-a-stable-source-tarball">Usage as a stable source tarball</h2>
115
116<p>If you would prefer a single source tarball of the stable branch containing
117all the documentation, tests and sources, this can always be retrieved from:</p>
118
119<p><a href="https://dedi5.nedprod.com/static/files/outcome-v2.0-source-latest.tar.xz">https://dedi5.nedprod.com/static/files/outcome-v2.0-source-latest.tar.xz</a></p>
120
121<p>This tarball is automatically generated when Outcome fully compiles and passes
122all unit tests on all platforms tested by the CIs. This currently includes:</p>
123
124<ul>
125<li>Linux: GCC 6.5, clang 4.0.1</li>
126<li>MacOS: XCode 9</li>
127<li>Windows: VS2017.9</li>
128</ul>
129
130<p>It should be emphasised that newer compilers are not tested, so there is
131an unlikely chance that the tarball may not work on a newer compiler.</p>
132
133<hr>
134
135<h1 id="running-the-unit-test-suite">Running the unit test suite</h1>
136
137<p>To run the unit test suite you will need cmake 3.3 or later installed.</p>
138
139<pre><code>mkdir build
140cd build
141cmake ..
142cmake --build .
143ctest
144</code></pre>
145
146<p>On some cmake generators (Visual Studio, Xcode) you may need to tell cmake build a configuration
147like Release or Debug. Similarly, ctest needs to be told the same e.g.</p>
148
149<pre><code>mkdir build
150cd build
151cmake ..
152cmake --build . --config Release
153ctest -C Release
154</code></pre>
155
156<p><a href="http://my.cdash.org/index.php?project=Boost.Outcome">Per commit, tests are run by Travis and uploaded to a CDash dashboard here</a>.</p>
157
158<hr>
159
160<h1 id="cmake-find-package-imported-targets-support">CMake <code>find_package()</code> imported targets support</h1>
161
162<p>Outcome fully complies with cmake install, so by installing Outcome, it can be
163found by cmake&rsquo;s <code>find_package()</code>.</p>
164
165<pre><code>mkdir build
166cd build
167cmake ..
168cmake --build .
169sudo cmake --build . --target install
170</code></pre>
171
172<h1 id="modular-cmake-build-support">Modular CMake build support</h1>
173
174<p>If you are using Outcome in a CMake project, Outcome is a &ldquo;modular cmake&rdquo; project
175using only modern cmake 3 throughout. This lets you add the Outcome directory as a
176cmake subdirectory with no unexpected consequence on the rest of your cmake. You will need
177to be using cmake 3.3 or better.</p>
178
179<pre><code>add_subdirectory(
180  &quot;${CMAKE_CURRENT_SOURCE_DIR}/outcome&quot;  # path to outcome source
181  &quot;${CMAKE_CURRENT_BINARY_DIR}/outcome&quot;  # your choice of where to put binaries
182  EXCLUDE_FROM_ALL                       # please only lazy build outcome on demand
183)
184</code></pre>
185
186<p>Outcome&rsquo;s cmake has the following useful products:</p>
187
188<ul>
189<li><code>outcome::hl</code> (target): the Outcome header-only library. Add this to any
190<code>target_link_libraries()</code> in your cmake to bring in Outcome as a header-only library. This will also
191add to your link (via <code>PUBLIC</code>) any debugger visualisation support files, any system library
192dependencies and also force all consuming executables to be configured with a minimum
193of C++ 14 as Outcome requires a minimum of that.</li>
194<li><code>outcome_TEST_TARGETS</code> (list): a list of targets which generate Outcome&rsquo;s test
195suite. You can append this to your own test suite if you wish to run Outcome&rsquo;s test
196suite along with your own.</li>
197</ul>
198
199
200
201        </div><p><small>Last revised: March 12, 2020 at 10:35:42 UTC</small></p>
202<hr>
203<div class="spirit-nav">
204<a accesskey="p" href="./requirements.html"><img src="./images/prev.png" alt="Prev"></a>
205    <a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
206    <a accesskey="h" href="./index.html"><img src="./images/home.png" alt="Home"></a><a accesskey="n" href="./motivation.html"><img src="./images/next.png" alt="Next"></a></div></body>
207</html>
208