catch2/docs/own-main.md

131 lines
4.0 KiB
Markdown
Raw Normal View History

2017-08-24 15:21:36 +02:00
<a id="top"></a>
# Supplying main() yourself
2013-06-07 20:09:38 +02:00
2018-09-05 10:01:54 +02:00
**Contents**<br>
2021-11-19 15:52:32 +01:00
[Let Catch2 take full control of args and config](#let-catch2-take-full-control-of-args-and-config)<br>
[Amending the Catch2 config](#amending-the-catch2-config)<br>
2018-09-05 10:01:54 +02:00
[Adding your own command line options](#adding-your-own-command-line-options)<br>
[Version detection](#version-detection)<br>
2021-11-19 15:52:32 +01:00
The easiest way to use Catch2 is to use its own `main` function, and let
it handle the command line arguments. This is done by linking against
Catch2Main library, e.g. through the [CMake target](cmake-integration.md#cmake-targets),
or pkg-config files.
2021-11-19 15:52:32 +01:00
If you want to provide your own `main`, then you should link against
the static library (target) only, without the main part. You will then
have to write your own `main` and call into Catch2 test runner manually.
2021-11-19 15:52:32 +01:00
Below are some basic recipes on what you can do supplying your own main.
2021-11-19 15:52:32 +01:00
## Let Catch2 take full control of args and config
2021-11-19 15:52:32 +01:00
This is useful if you just need to have code that executes before/after
Catch2 runs tests.
2021-11-19 15:52:32 +01:00
```cpp
#include <catch2/catch_session.hpp>
int main( int argc, char* argv[] ) {
2021-11-19 15:52:32 +01:00
// your setup ...
int result = Catch::Session().run( argc, argv );
2021-11-19 15:52:32 +01:00
// your clean-up...
return result;
}
```
2021-11-19 15:52:32 +01:00
_Note that if you only want to run some set up before tests are run, it
might be simpler to use [event listeners](event-listeners.md#top) instead._
2021-11-19 15:52:32 +01:00
## Amending the Catch2 config
2021-11-19 15:52:32 +01:00
If you want Catch2 to process command line arguments, but also want to
programmatically change the resulting configuration of Catch2 run,
you can do it in two ways:
```c++
int main( int argc, char* argv[] ) {
2016-06-15 21:01:55 +02:00
Catch::Session session; // There must be exactly one instance
2021-11-19 15:52:32 +01:00
// writing to session.configData() here sets defaults
// this is the preferred way to set them
2021-11-19 15:52:32 +01:00
int returnCode = session.applyCommandLine( argc, argv );
if( returnCode != 0 ) // Indicates a command line error
return returnCode;
2021-11-19 15:52:32 +01:00
// writing to session.configData() or session.Config() here
// overrides command line args
// only do this if you know you need to
int numFailed = session.run();
2021-11-19 15:52:32 +01:00
// numFailed is clamped to 255 as some unices only use the lower 8 bits.
// This clamping has already been applied, so just return it here
// You can also do any post run clean-up here
return numFailed;
}
```
2021-11-19 15:52:32 +01:00
If you want full control of the configuration, don't call `applyCommandLine`.
## Adding your own command line options
2021-11-19 15:52:32 +01:00
You can add new command line options to Catch2, by composing the premade
CLI parser (called Clara), and add your own options.
2021-11-19 15:52:32 +01:00
```cpp
int main( int argc, char* argv[] ) {
Catch::Session session; // There must be exactly one instance
2021-11-19 15:52:32 +01:00
int height = 0; // Some user variable you want to be able to set
2021-11-19 15:52:32 +01:00
// Build a new parser on top of Catch2's
using namespace Catch::Clara;
auto cli
= session.cli() // Get Catch2's command line parser
| Opt( height, "height" ) // bind variable to a new option, with a hint string
["-g"]["--height"] // the option names it will respond to
("how high?"); // description string for the help output
2021-11-19 15:52:32 +01:00
// Now pass the new composite back to Catch2 so it uses that
session.cli( cli );
// Let Catch2 (using Clara) parse the command line
int returnCode = session.applyCommandLine( argc, argv );
if( returnCode != 0 ) // Indicates a command line error
return returnCode;
// if set on the command line then 'height' is now set at this point
if( height > 0 )
std::cout << "height: " << height << std::endl;
return session.run();
}
```
2021-11-19 15:52:32 +01:00
See the [Clara documentation](https://github.com/catchorg/Clara/blob/master/README.md)
for more details on how to use the Clara parser.
2013-06-07 22:31:28 +02:00
## Version detection
2021-11-19 15:52:32 +01:00
Catch2 provides a triplet of macros providing the header's version,
* `CATCH_VERSION_MAJOR`
* `CATCH_VERSION_MINOR`
* `CATCH_VERSION_PATCH`
these macros expand into a single number, that corresponds to the appropriate
part of the version. As an example, given single header version v2.3.4,
the macros would expand into `2`, `3`, and `4` respectively.
2013-06-07 20:09:38 +02:00