diff options
| author | Martin Hořeňovský | 2020-10-31 08:14:34 +0100 |
|---|---|---|
| committer | Martin Hořeňovský | 2020-10-31 08:14:50 +0100 |
| commit | 39aabede62262522da92a8f05db4658af4b79fb6 (patch) | |
| tree | 0ce1f273680ff829043a907fd420b28807a4df9a /docs | |
| parent | d7ced69db2c24b712f0f6af001643bf6705c6151 (diff) | |
| download | catch3-39aabede62262522da92a8f05db4658af4b79fb6.tar.gz | |
Add a short documentation for migrating from v2 to v3
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/migrate-v2-to-v3.md | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md new file mode 100644 index 00000000..64883508 --- /dev/null +++ b/docs/migrate-v2-to-v3.md @@ -0,0 +1,57 @@ +<a id="top"></a> +# Migrating from v2 to v3 + +If you want to migrate to v3, there are two basic approaches to do so. + +1. Use `catch_amalgamated.hpp` and `catch_amalgamated.cpp`. +2. Build Catch2 as a proper (static) library, and move to piecewise headers + +Doing 1 means downloading the [amalgamated header](/extras/catch_amalgamated.hpp) +and the [amalgamated sources](/extras/catch_amalgamated.cpp) from `extras`, +dropping them into your test project, and rewriting your includes from +`<catch2/catch.hpp>` to `"catch_amalgamated.hpp"` (or something similar, +based on how you set up your paths). + +The disadvantage of using this approach are increased compilation times, +at least compared to the second approach, but it does let you avoid +dealing with consuming libraries in your build system of choice. + + +However, we recommend doing 2, and taking extra time to migrate to v3 +properly. This lets you reap the benefits of significantly improved +compilation times in the v3 version. The basic steps to do se are: + +1. Change your CMakeLists.txt to link against `Catch2WithMain` target if +you use Catch2's default main. (If you do not, keep linking against +the `Catch2` target.) +2. Delete TU with `CATCH_CONFIG_RUNNER` or `CATCH_CONFIG_MAIN` defined, +as it is no longer needed. +3. Change `#include <catch2/catch.hpp>` to `#include <catch2/catch_all.hpp>` +4. Check that everything compiles. You might have to modify namespaces, +or perform some other changes (see the +[Things that can break during porting](#things-that-can-break-during-porting) +section for the most common things). +5. Start migrating your test TUs from including `<catch2/catch_all.hpp>` +to piecemeal includes. You will likely want to start by including +`<catch2/catch_test_macros.hpp>`, and then go from there. (see +[other notes](#other-notes) for further ideas) + +## Other notes +* The main test include is now `<catch2/catch_test_macros.hpp>` +* Big "subparts" like Matchers, or Generators, have their own folder, and +also their own "big header", so if you just want to include all matchers, +you can include `<catch2/matchers/catch_matchers_all.hpp>`, +or `<catch2/generators/catch_generators_all.hpp>` + + +## Things that can break during porting +* The namespace on Matchers were cleaned up, they are no longer first declared +deep within an internal namespace and then brought up. All Matchers now live +in `Catch::Matchers`. +* The reporter interfaces changed in a breaking manner. If you wrote custom +reporter or listener, you might need to modify them a bit. + + +--- + +[Home](Readme.md#top)
\ No newline at end of file |