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