1  <a id="top"></a>
  2  # Supplying main() yourself
  3  
  4  **Contents**<br>
  5  [Let Catch2 take full control of args and config](#let-catch2-take-full-control-of-args-and-config)<br>
  6  [Amending the Catch2 config](#amending-the-catch2-config)<br>
  7  [Adding your own command line options](#adding-your-own-command-line-options)<br>
  8  [Version detection](#version-detection)<br>
  9  
 10  The easiest way to use Catch2 is to use its own `main` function, and let
 11  it handle the command line arguments. This is done by linking against
 12  Catch2Main library, e.g. through the [CMake target](cmake-integration.md#cmake-targets),
 13  or pkg-config files.
 14  
 15  If you want to provide your own `main`, then you should link against
 16  the static library (target) only, without the main part. You will then
 17  have to write your own `main` and call into Catch2 test runner manually.
 18  
 19  Below are some basic recipes on what you can do supplying your own main.
 20  
 21  
 22  ## Let Catch2 take full control of args and config
 23  
 24  This is useful if you just need to have code that executes before/after
 25  Catch2 runs tests.
 26  
 27  ```cpp
 28  #include <catch2/catch_session.hpp>
 29  
 30  int main( int argc, char* argv[] ) {
 31    // your setup ...
 32  
 33    int result = Catch::Session().run( argc, argv );
 34  
 35    // your clean-up...
 36  
 37    return result;
 38  }
 39  ```
 40  
 41  _Note that if you only want to run some set up before tests are run, it
 42  might be simpler to use [event listeners](event-listeners.md#top) instead._
 43  
 44  
 45  ## Amending the Catch2 config
 46  
 47  If you want Catch2 to process command line arguments, but also want to
 48  programmatically change the resulting configuration of Catch2 run,
 49  you can do it in two ways:
 50  
 51  ```c++
 52  int main( int argc, char* argv[] ) {
 53    Catch::Session session; // There must be exactly one instance
 54  
 55    // writing to session.configData() here sets defaults
 56    // this is the preferred way to set them
 57  
 58    int returnCode = session.applyCommandLine( argc, argv );
 59    if( returnCode != 0 ) // Indicates a command line error
 60          return returnCode;
 61  
 62    // writing to session.configData() or session.Config() here
 63    // overrides command line args
 64    // only do this if you know you need to
 65  
 66    int numFailed = session.run();
 67  
 68    // numFailed is clamped to 255 as some unices only use the lower 8 bits.
 69    // This clamping has already been applied, so just return it here
 70    // You can also do any post run clean-up here
 71    return numFailed;
 72  }
 73  ```
 74  
 75  If you want full control of the configuration, don't call `applyCommandLine`.
 76  
 77  
 78  ## Adding your own command line options
 79  
 80  You can add new command line options to Catch2, by composing the premade
 81  CLI parser (called Clara), and add your own options.
 82  
 83  ```cpp
 84  int main( int argc, char* argv[] ) {
 85    Catch::Session session; // There must be exactly one instance
 86  
 87    int height = 0; // Some user variable you want to be able to set
 88  
 89    // Build a new parser on top of Catch2's
 90    using namespace Catch::Clara;
 91    auto cli
 92      = session.cli()           // Get Catch2's command line parser
 93      | Opt( height, "height" ) // bind variable to a new option, with a hint string
 94          ["-g"]["--height"]    // the option names it will respond to
 95          ("how high?");        // description string for the help output
 96  
 97    // Now pass the new composite back to Catch2 so it uses that
 98    session.cli( cli );
 99  
100    // Let Catch2 (using Clara) parse the command line
101    int returnCode = session.applyCommandLine( argc, argv );
102    if( returnCode != 0 ) // Indicates a command line error
103        return returnCode;
104  
105    // if set on the command line then 'height' is now set at this point
106    if( height > 0 )
107        std::cout << "height: " << height << std::endl;
108  
109    return session.run();
110  }
111  ```
112  
113  See the [Clara documentation](https://github.com/catchorg/Clara/blob/master/README.md)
114  for more details on how to use the Clara parser.
115  
116  
117  ## Version detection
118  
119  Catch2 provides a triplet of macros providing the header's version,
120  
121  * `CATCH_VERSION_MAJOR`
122  * `CATCH_VERSION_MINOR`
123  * `CATCH_VERSION_PATCH`
124  
125  these macros expand into a single number, that corresponds to the appropriate
126  part of the version. As an example, given single header version v2.3.4,
127  the macros would expand into `2`, `3`, and `4` respectively.
128  
129  
130  ---
131  
132  [Home](Readme.md#top)