[{"data":1,"prerenderedAt":302},["ShallowReactive",2],{"doc-migrate-v2-to-v3":3},{"id":4,"title":5,"body":6,"description":287,"extension":293,"meta":294,"navigation":295,"path":296,"seo":297,"slug":298,"source":299,"stem":300,"__hash__":301},"docs\u002Fdocs\u002Fmigrate-v2-to-v3.md","Migrating from v2 to v3",{"type":7,"value":8,"toc":286},"minimark",[9,50,54,57,70,73,83,89,94,97,112,145,148,151,218,222,239,242,247,258,273],[10,11,12],"blockquote",{},[13,14,15,19,20,24,25,28,29,32,33,36,37,36,40,43,44,49],"p",{},[16,17,18],"strong",{},"Catch3 compatibility reference:"," This page describes the test-writing API Catch3 shares with Catch2: the macros, such as ",[21,22,23],"code",{},"TEST_CASE"," and ",[21,26,27],{},"REQUIRE",", and the ",[21,30,31],{},"Catch::"," namespace keep Catch2's names. Headers and build names are Catch3's own (",[21,34,35],{},"\u003CProgmasoft\u002FCatch3\u002FTestMacros.hpp>",", ",[21,38,39],{},"find_package(Catch3)",[21,41,42],{},"Catch3::Catch3WithMain","). See ",[45,46,48],"a",{"href":47},"\u002Fdocs\u002Fprogmasoft-catch3\u002F","Catch3 additions"," for Progmasoft APIs.",[51,52,5],"h1",{"id":53},"migrating-from-v2-to-v3",[13,55,56],{},"v3 is the next major version of Catch2 and brings three significant changes:",[58,59,60,64,67],"ul",{},[61,62,63],"li",{},"Catch2 is now split into multiple headers",[61,65,66],{},"Catch2 is now compiled as a static library",[61,68,69],{},"C++17 is the minimum required C++ version",[13,71,72],{},"There are many reasons why we decided to go from the old single-header\ndistribution model to a more standard library distribution model. The\nbig one is compile-time performance, but moving over to a split header\ndistribution model also improves the future maintainability and\nextendability of the codebase. For example v3 adds a new kind of matchers\nwithout impacting the compilation times of users that do not use matchers\nin their tests. The new model is also more friendly towards package\nmanagers, such as vcpkg and Conan.",[13,74,75,76,82],{},"The result of this move is a significant improvement in compilation\ntimes, e.g. the inclusion overhead of Catch2 in the common case has been\nreduced by roughly 80%. The improved ease of maintenance also led to\nvarious runtime performance improvements and the introduction of new features.\nFor details, look at ",[45,77,81],{"href":78,"rel":79},"https:\u002F\u002Fgithub.com\u002Fcatchorg\u002FCatch2\u002Fblob\u002Fdevel\u002Fdocs\u002Frelease-notes.md#301",[80],"nofollow","the release notes of Catch2 3.0.1",".",[13,84,85],{},[86,87,88],"em",{},"Note that we still provide one header + one translation unit (TU)\ndistribution but do not consider it the primarily supported option. You\nshould also expect that the compilation times will be worse if you use\nthis option.",[90,91,93],"h2",{"id":92},"how-to-migrate-projects-from-v2-to-v3","How to migrate projects from v2 to v3",[13,95,96],{},"To migrate to v3, there are two basic approaches to do so.",[98,99,100,109],"ol",{},[61,101,102,103,24,106,82],{},"Use ",[21,104,105],{},"catch_amalgamated.hpp",[21,107,108],{},"catch_amalgamated.cpp",[61,110,111],{},"Build Catch3 as a proper (static) library, and move to piecewise headers",[13,113,114,115,120,121,126,127,132,133,136,137,140,141,144],{},"Doing 1 means downloading the ",[45,116,119],{"href":117,"rel":118},"https:\u002F\u002Fgithub.com\u002FProgmasoft\u002Fcatch3\u002Fblob\u002Fdevel\u002Fextras\u002Fcatch_amalgamated.hpp",[80],"amalgamated header",",\nthe ",[45,122,125],{"href":123,"rel":124},"https:\u002F\u002Fgithub.com\u002FProgmasoft\u002Fcatch3\u002Fblob\u002Fdevel\u002Fextras\u002Fcatch_amalgamated.cpp",[80],"amalgamated sources"," and\n",[45,128,131],{"href":129,"rel":130},"https:\u002F\u002Fgithub.com\u002FProgmasoft\u002Fcatch3\u002Fblob\u002Fdevel\u002Fextras\u002Fcatch_amalgamated_third_party.hpp",[80],"the JSON and XML libraries they include","\nfrom ",[21,134,135],{},"extras",", dropping them into your test project, and rewriting your includes from\n",[21,138,139],{},"\u003Ccatch2\u002Fcatch.hpp>"," to ",[21,142,143],{},"\"catch_amalgamated.hpp\""," (or something similar,\nbased on how you set up your paths).",[13,146,147],{},"The disadvantage of using this approach are increased compilation times,\nat least compared to the second approach, but it does let you avoid\ndealing with consuming libraries in your build system of choice.",[13,149,150],{},"However, we recommend doing 2, and taking extra time to migrate to v3\nproperly. This lets you reap the benefits of significantly improved\ncompilation times in the v3 version. The basic steps to do so are:",[98,152,153,173,183,195,203],{},[61,154,155,156,158,159,161,162,165,166,169,170,82],{},"Change your CMakeLists.txt to ",[21,157,39],{}," and link against\nthe ",[21,160,42],{}," target if you use the default main, or against\n",[21,163,164],{},"Catch3::Catch3"," if you do not. If you use pkg-config, use\n",[21,167,168],{},"pkg-config catch3-with-main"," or ",[21,171,172],{},"pkg-config catch3",[61,174,175,176,169,179,182],{},"Delete TU with ",[21,177,178],{},"CATCH_CONFIG_RUNNER",[21,180,181],{},"CATCH_CONFIG_MAIN"," defined,\nas it is no longer needed.",[61,184,185,186,140,189,192,193],{},"Change ",[21,187,188],{},"#include \u003Ccatch2\u002Fcatch.hpp>",[21,190,191],{},"#include \u003CProgmasoft\u002FCatch3\u002FAll.hpp>",",\nor better, to the headers you need, such as ",[21,194,35],{},[61,196,197,198,202],{},"Check that everything compiles. You might have to modify namespaces,\nor perform some other changes (see the\n",[45,199,201],{"href":200},"#things-that-can-break-during-porting","Things that can break during porting","\nsection for the most common things).",[61,204,205,206,209,210,212,213,217],{},"Start migrating your test TUs from including ",[21,207,208],{},"\u003CProgmasoft\u002FCatch3\u002FAll.hpp>","\nto piecemeal includes. You will likely want to start by including\n",[21,211,35],{},", and then go from there. (see\n",[45,214,216],{"href":215},"#other-notes","other notes"," for further ideas)",[90,219,221],{"id":220},"other-notes","Other notes",[58,223,224,229],{},[61,225,226,227],{},"The main test include is now ",[21,228,35],{},[61,230,231,232,235,236],{},"Big \"subparts\" like Matchers, or Generators, have their own folder, and\nalso their own \"big header\", so if you just want to include all matchers,\nyou can include ",[21,233,234],{},"\u003CProgmasoft\u002FCatch3\u002FMatchers\u002FAll.hpp>",",\nor ",[21,237,238],{},"\u003CProgmasoft\u002FCatch3\u002FGenerators\u002FAll.hpp>",[90,240,201],{"id":241},"things-that-can-break-during-porting",[58,243,244],{},[61,245,246],{},"The namespaces of Matchers were flattened and cleaned up.",[13,248,249,250,253,254,257],{},"Matchers are no longer declared deep within an internal namespace and\nthen brought up into ",[21,251,252],{},"Catch"," namespace. All Matchers now live in the\n",[21,255,256],{},"Catch::Matchers"," namespace.",[58,259,260,270],{},[61,261,262,263,266,267,82],{},"The ",[21,264,265],{},"Contains"," string matcher was renamed to ",[21,268,269],{},"ContainsSubstring",[61,271,272],{},"The reporter interfaces changed in a breaking manner.",[13,274,275,276,280,281,285],{},"If you are using a custom reporter or listener, you will likely need to\nmodify them to conform to the new interfaces. Unlike before in v2,\nthe ",[45,277,279],{"href":278},"\u002Fdocs\u002Freporters\u002F","interfaces"," and the ",[45,282,284],{"href":283},"\u002Fdocs\u002Freporter-events\u002F","events","\nare now documented.",{"title":287,"searchDepth":288,"depth":288,"links":289},"",2,[290,291,292],{"id":92,"depth":288,"text":93},{"id":220,"depth":288,"text":221},{"id":241,"depth":288,"text":201},"md",{},true,"\u002Fdocs\u002Fmigrate-v2-to-v3",{"title":5,"description":287},"migrate-v2-to-v3","docs\u002Fmigrate-v2-to-v3.md","docs\u002Fmigrate-v2-to-v3","EhonTa-kh58eAoD0PLql1ZI2cQYAKlCbV5JsCdffj9E",1794961595207]