Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorMartin Hořeňovský2021-07-29 23:19:48 +0200
committerMartin Hořeňovský2021-07-29 23:19:48 +0200
commit02e5951f11bce578b0d20ac0f87aa527c9b67609 (patch)
treeb07c9d1b56bd09ac99cbfaa4b851d51327ae6f94 /docs
parent1ecc79bb56ac2fdccaf5d29c635c8c7f6575777d (diff)
downloadcatch3-02e5951f11bce578b0d20ac0f87aa527c9b67609.tar.gz
Add major changes and their motivation to v2 -> v3 migration docs
Closes #2135
Diffstat (limited to 'docs')
-rw-r--r--docs/migrate-v2-to-v3.md34
1 files changed, 28 insertions, 6 deletions
diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md
index 2ee0c9f0..41c4d470 100644
--- a/docs/migrate-v2-to-v3.md
+++ b/docs/migrate-v2-to-v3.md
@@ -1,12 +1,34 @@
<a id="top"></a>
-# Changes overview
-- Catch2 now suggests statically compiled library as its distribution model.
-- Functionality is split into multiple header files.
-- ...
-
# Migrating from v2 to v3
-If you want to migrate to v3, there are two basic approaches to do so.
+v3 is the next major version of Catch2 and brings three significant changes:
+ * Catch2 is now split into multiple headers
+ * Catch2 is now compiled as a static library
+ * C++14 is the minimum required C++ version
+
+There are many reasons why we decided to go from the old single-header
+distribution model to a more standard library distribution model. The
+big one is compile-time performance, but moving over to a split header
+distribution model also improves the future maintainability and
+extendability of the codebase. For example v3 adds a new kind of matchers
+without impacting the compilation times of users that do not use matchers
+in their tests. The new model is also more friendly towards package
+managers, such as vcpkg and Conan.
+
+The result of this move is a significant improvement in compilation
+times, e.g. the inclusion overhead of Catch2 in the common case has been
+reduced by roughly 80%. The improved ease of maintenance also led to
+various runtime performance improvements and the introduction of new features.
+For details, look at [the release notes of 3.0.1](release-notes.md#301).
+
+_Note that we still provide one header + one TU distribution but do
+not consider it the primarily supported option. You should also expect
+that the compilation times will be worse if you use this option._
+
+
+## How to migrate projects from v2 to v3
+
+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