1 <a id="top"></a> 2 # Supplying main() yourself 3 4 **Contents**<br> 5 [Let Catch take full control of args and config](#let-catch-take-full-control-of-args-and-config)<br> 6 [Amending the config](#amending-the-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 Catch is to let it supply ```main()``` for you and handle configuring itself from the command line. 11 12 This is achieved by writing ```#define CATCH_CONFIG_MAIN``` before the ```#include "catch.hpp"``` in *exactly one* source file. 13 14 Sometimes, though, you need to write your own version of main(). You can do this by writing ```#define CATCH_CONFIG_RUNNER``` instead. Now you are free to write ```main()``` as normal and call into Catch yourself manually. 15 16 You now have a lot of flexibility - but here are three recipes to get your started: 17 18 ## Let Catch take full control of args and config 19 20 If you just need to have code that executes before and/ or after Catch this is the simplest option. 21 22 ```c++ 23 #define CATCH_CONFIG_RUNNER 24 #include "catch.hpp" 25 26 int main( int argc, char* argv[] ) { 27 // global setup... 28 29 int result = Catch::Session().run( argc, argv ); 30 31 // global clean-up... 32 33 return result; 34 } 35 ``` 36 37 ## Amending the config 38 39 If you still want Catch to process the command line, but you want to programmatically tweak the config, you can do so in one of two ways: 40 41 ```c++ 42 #define CATCH_CONFIG_RUNNER 43 #include "catch.hpp" 44 45 int main( int argc, char* argv[] ) 46 { 47 Catch::Session session; // There must be exactly one instance 48 49 // writing to session.configData() here sets defaults 50 // this is the preferred way to set them 51 52 int returnCode = session.applyCommandLine( argc, argv ); 53 if( returnCode != 0 ) // Indicates a command line error 54 return returnCode; 55 56 // writing to session.configData() or session.Config() here 57 // overrides command line args 58 // only do this if you know you need to 59 60 int numFailed = session.run(); 61 62 // numFailed is clamped to 255 as some unices only use the lower 8 bits. 63 // This clamping has already been applied, so just return it here 64 // You can also do any post run clean-up here 65 return numFailed; 66 } 67 ``` 68 69 Take a look at the definitions of Config and ConfigData to see what you can do with them. 70 71 To take full control of the config simply omit the call to ```applyCommandLine()```. 72 73 ## Adding your own command line options 74 75 Catch embeds a powerful command line parser called [Clara](https://github.com/philsquared/Clara). 76 As of Catch2 (and Clara 1.0) Clara allows you to write _composable_ option and argument parsers, 77 so extending Catch's own command line options is now easy. 78 79 ```c++ 80 #define CATCH_CONFIG_RUNNER 81 #include "catch.hpp" 82 83 int main( int argc, char* argv[] ) 84 { 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 Catch's 90 using namespace Catch::clara; 91 auto cli 92 = session.cli() // Get Catch's composite 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 Catch so it uses that 98 session.cli( cli ); 99 100 // Let Catch (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/philsquared/Clara/blob/master/README.md) for more details. 114 115 116 ## Version detection 117 118 Catch provides a triplet of macros providing the header's version, 119 120 * `CATCH_VERSION_MAJOR` 121 * `CATCH_VERSION_MINOR` 122 * `CATCH_VERSION_PATCH` 123 124 these macros expand into a single number, that corresponds to the appropriate 125 part of the version. As an example, given single header version v2.3.4, 126 the macros would expand into `2`, `3`, and `4` respectively. 127 128 129 --- 130 131 [Home](Readme.md#top) 132
