add compat.catch2 v3.15.2 and compat.catch2-v2 v2.13.10

Catch2 is a modern C++ test framework.

- compat.catch2 (v3): C-source compat static library built from individual
  source files under src/catch2/. Includes generated catch_user_config.hpp
  (normally CMake-generated). Default main suppressed via
  -DCATCH_AMALGAMATED_CUSTOM_MAIN; `main` feature gates a generated
  default main TU (same pattern as compat.gtest).
- compat.catch2-v2 (v2): header-only, single-include via
  single_include/catch2/catch.hpp with anchor TU. `main` feature gates
  a generated TU with CATCH_CONFIG_MAIN.

Both use GitHub tag archive tarballs. No CN mirror yet (no mcpp-res
write access). Local `mcpp test -p catch2` and `mcpp test -p catch2-v2`
pass on mcpp 0.0.108 (x86_64-windows-msvc).

Author: ZheFeng7110

.agents/docs/2026-07-26-add-catch2-plan.md

@@ -0,0 +1,109 @@
+# Design doc: add Catch2 to mcpp-index
+
+Date: 2026-07-26
+
+## Source
+
+- Repo: [catchorg/Catch2](https://github.com/catchorg/Catch2)
+- License: BSL-1.0 (Boost Software License 1.0)
+- Upstream release model: amalgamated files published as GitHub release assets
+
+Catch2 has two major versions with incompatible APIs and source layouts:
+
+| Version | Source layout | Shape |
+|---------|--------------|-------|
+| v2.13.10 | `single_include/catch2/catch.hpp` (single amalgamated header) | **header-only** |
+| v3.15.2 | `src/catch2/**/*.{hpp,cpp}` (individual source files) | **C-source compat (static lib)** |
+
+The v2→v3 jump changed the repo layout completely (`single_include/` → `src/catch2/`),
+so the two versions cannot share a single `mcpp` block. Two separate packages are used:
+
+- `compat.catch2` — v3, C-source compat (static library from individual source files)
+- `compat.catch2-v2` — v2, header-only
+
+## Package shape decision
+
+### compat.catch2 (v3)
+
+- **Shape**: C-source compat static library (same as compat.cjson / compat.gtest)
+- **Sources**: `*/src/catch2/**/*.cpp` — all Catch2 implementation files (107 TUs)
+- **include_dirs**: `{ "*/src", "mcpp_generated" }` — exposes `<catch2/catch_all.hpp>`
+  etc. from the source tree, and `catch2/catch_user_config.hpp` from generated files
+- **catch_user_config.hpp**: materialised via `generated_files` (normally
+  CMake-generated; provides `CATCH_CONFIG_DEFAULT_REPORTER` and
+  `CATCH_CONFIG_CONSOLE_WIDTH`). Both value-defines use `#ifndef` guards so
+  users can override them via `cxxflags = ["-DCATCH_CONFIG_DEFAULT_REPORTER=xml"]`
+  in their own `mcpp.toml`. Other boolean toggles (e.g. `CATCH_CONFIG_WCHAR`)
+  are auto-detected by `catch_compiler_capabilities.hpp` and can likewise be
+  forced on/off via `-D` flags.
+- **catch_main.cpp**: provides a default `main()`. Excluded from the default
+  source set via `!` negation (`"!*/src/catch2/internal/catch_main.cpp"`);
+  only compiled when `features = ["main"]` is requested (same pattern as
+  `compat.gtest`'s `main` feature gating `gtest_main.cc`)
+
+### compat.catch2-v2 (v2)
+
+- **Shape**: header-only (same as compat.eigen / compat.opengl)
+- **include_dirs**: `{ "*/single_include" }` — consumers `#include <catch2/catch.hpp>`
+- **Anchor**: trivial `.c` TU (`mcpp_generated/catch2_v2_anchor.c`) to give mcpp
+  a buildable lib target
+- **`main` feature**: gates a generated `main.cpp` that defines
+  `CATCH_CONFIG_MAIN` and includes `<catch2/catch.hpp>`, providing a ready-made
+  `main()`. Excluded by default
+
+## Download URLs
+
+Both packages use GitHub tag archive tarballs (not individual release assets)
+because xpm supports one URL per version.
+
+| Package | Version | GitHub archive URL | SHA256 |
+|---------|---------|--------------------|--------|
+| compat.catch2 | 3.15.2 | `https://github.com/catchorg/Catch2/archive/refs/tags/v3.15.2.tar.gz` | `acfae120892c2b67a74142d36d060c0caa96f1c3aaa8aabd96e19961163d0420` |
+| compat.catch2-v2 | 2.13.10 | `https://github.com/catchorg/Catch2/archive/refs/tags/v2.13.10.tar.gz` | `d54a712b7b1d7708bc7a819a8e6e47b2fde9536f487b89ccbca295072a7d9943` |
+
+### Individual release asset SHAs (for reference)
+
+| File | Release URL | SHA256 |
+|------|------------|--------|
+| catch.hpp (v2.13.10) | `https://github.com/catchorg/Catch2/releases/download/v2.13.10/catch.hpp` | `3725c0f0a75f376a5005dde31ead0feb8f7da7507644c201b814443de8355170` |
+| catch_amalgamated.cpp (v3.15.2) | `https://github.com/catchorg/Catch2/releases/download/v3.15.2/catch_amalgamated.cpp` | `1ec0b0c0d6133f76fea521295be3e69e3aa5464ab92972897414ca59b7f674d5` |
+| catch_amalgamated.hpp (v3.15.2) | `https://github.com/catchorg/Catch2/releases/download/v3.15.2/catch_amalgamated.hpp` | `f0573f46ac989896a20c524085307b633f01c8e1cdbbe6d9b39f63827c2d6c5e` |
+
+## CN mirror
+
+Not configured yet — no `mcpp-res` write access. Using plain-string upstream URLs
+(no `{ GLOBAL=…, CN=… }` table). CN users will fall back to the upstream source.
+Mirrors can be added later by a maintainer.
+
+## Test examples
+
+- **tests/examples/catch2/**: v3 static library build. Includes
+  `<catch2/catch_all.hpp>`, provides own `main()` using
+  `Catch::Session().run()`, runs two `TEST_CASE`s.
+- **tests/examples/catch2-v2/**: v2 header-only. Defines `CATCH_CONFIG_MAIN` to
+  get a built-in main, includes `<catch2/catch.hpp>`, runs two `TEST_CASE`s
+  within a single TU.
+
+## Verification
+
+- SHA256 computed twice (confirmed stable) via `sha256sum` on the codeload tarballs
+- File paths confirmed by `tar -tzf` against tag archives
+- Both packages pass `mcpp xpkg parse` lint
+- `mcpp test -p catch2` → **test result ok** (2 assertions in 2 test cases)
+- `mcpp test -p catch2-v2` → **test result ok** (2 assertions in 2 test cases)
+- Tested with mcpp 0.0.108 (matching CI `MCPP_VERSION`) on x86_64-windows-msvc
+
+## Notes
+
+- Catch2 v3 static library requires `catch_user_config.hpp` (normally
+  CMake-generated). A minimal version is materialised via `generated_files` at
+  `mcpp_generated/catch2/catch_user_config.hpp` with `#ifndef` guards on the
+  two value-defines (`CATCH_CONFIG_DEFAULT_REPORTER` and
+  `CATCH_CONFIG_CONSOLE_WIDTH`), allowing users to override them via `-D` flags.
+- `catch_main.cpp` is gated via `!` negation in `sources` + feature listing,
+  following the exact `compat.gtest` pattern. No `-DCATCH_AMALGAMATED_CUSTOM_MAIN`
+  needed.
+- Catch2 v3 requires C++14 or later; v2 requires C++11; both compatible with
+  mcpp's `language = "c++23"`.
+- No `c_standard` needed for v3 (pure C++); anchor for v2 uses
+  `c_standard = "c11"`.

README.md

@@ -35,6 +35,7 @@ mcpp self config --mirror CN   # 切换至国内镜像,默认使用 GLOBAL 上
 | 原生模块库(Form A) | [`mcpplibs.xpkg`](pkgs/x/xpkg.lua) · [`mcpplibs.tinyhttps`](pkgs/t/tinyhttps.lua) · [`tensorvia-cpu`](pkgs/t/tensorvia-cpu.lua) · [`ffmpeg`](pkgs/f/ffmpeg.lua)(模块层,源码经 `compat.ffmpeg` 直编) · [`opencv`](pkgs/o/opencv.lua)(单仓库:模块层与 OpenCV 5 全源码构建同在包内,索引侧只留本描述符) |
 | C 源码 compat(含 `features`) | [`compat.cjson`](pkgs/c/compat.cjson.lua) · [`compat.zlib`](pkgs/c/compat.zlib.lua) |
 | header-only(含 `features`) | [`compat.eigen`](pkgs/c/compat.eigen.lua) |
+| 单包多 major(形态随版本切换) | [`compat.catch2`](pkgs/c/compat.catch2.lua)(3.x 编 `src/catch2/` 出静态库;2.x 走 `single_include/` header-only) |
 | 外部构建系统(`install()` 从源码构建) | [`compat.openblas`](pkgs/c/compat.openblas.lua)(Make) · [`compat.openssl`](pkgs/c/compat.openssl.lua)(Perl Configure + Make,静态 libssl/libcrypto) |
 | 全源码直编(config 快照 + 源列表,零外部构建系统) | [`compat.ffmpeg`](pkgs/c/compat.ffmpeg.lua)(2281 TU 含 NASM 汇编,28 个目录 glob 声明) |
 | C++23 module wrapper | [`nlohmann.json`](pkgs/n/nlohmann.json.lua) · [`marzer.tomlplusplus`](pkgs/m/marzer.tomlplusplus.lua) |

mcpp.toml

@@ -11,6 +11,8 @@ members = [
     "tests/examples/asio-module",
     "tests/examples/asio-ssl",
     "tests/examples/build-mcpp",
+    "tests/examples/catch2",
+    "tests/examples/catch2-v2",
     "tests/examples/cjson",
     "tests/examples/core",
     "tests/examples/eigen",

pkgs/c/compat.catch2-v2.lua

@@ -0,0 +1,69 @@
+-- Form B inline descriptor for Catch2 v2 — a modern C++ test framework.
+-- v2 is HEADER-ONLY: the amalgamated single header (catch.hpp) contains
+-- the full implementation. Define `CATCH_CONFIG_MAIN` before including it
+-- in exactly one TU to get a ready-made main(), or define
+-- `CATCH_CONFIG_RUNNER` to write your own.
+--
+-- This descriptor exposes the header via include_dirs and carries a tiny
+-- anchor TU so mcpp always has a buildable lib target (same shape as
+-- compat.eigen / compat.opengl / compat.khrplatform).
+--
+-- Features (sources-only gate):
+--   `main` — compiles a generated TU that defines CATCH_CONFIG_MAIN and
+--   includes <catch2/catch.hpp>, providing a default main(). Excluded by
+--   default; request features = ["main"] for a no-config entry point.
+--
+-- All `mcpp` paths are GLOBS relative to the verdir; the leading `*`
+-- absorbs the GitHub tarball's `Catch2-<tag>/` wrap layer.
+package = {
+    spec        = "1",
+    namespace   = "compat",
+    name        = "catch2-v2",
+    description = "A modern, C++-native test framework for unit-tests, TDD and BDD — v2 (C++11, header-only)",
+    licenses    = {"BSL-1.0"},
+    repo        = "https://github.com/catchorg/Catch2",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["2.13.10"] = {
+                url    = "https://github.com/catchorg/Catch2/archive/refs/tags/v2.13.10.tar.gz",
+                sha256 = "d54a712b7b1d7708bc7a819a8e6e47b2fde9536f487b89ccbca295072a7d9943",
+            },
+        },
+        macosx = {
+            ["2.13.10"] = {
+                url    = "https://github.com/catchorg/Catch2/archive/refs/tags/v2.13.10.tar.gz",
+                sha256 = "d54a712b7b1d7708bc7a819a8e6e47b2fde9536f487b89ccbca295072a7d9943",
+            },
+        },
+        windows = {
+            ["2.13.10"] = {
+                url    = "https://github.com/catchorg/Catch2/archive/refs/tags/v2.13.10.tar.gz",
+                sha256 = "d54a712b7b1d7708bc7a819a8e6e47b2fde9536f487b89ccbca295072a7d9943",
+            },
+        },
+    },
+
+    mcpp = {
+        language     = "c++23",
+        import_std   = false,
+        c_standard   = "c11",
+        include_dirs = { "*/single_include" },
+        generated_files = {
+            ["mcpp_generated/catch2_v2_anchor.c"] = [==[
+int mcpp_compat_catch2_v2_anchor(void) { return 0; }
+]==],
+            ["mcpp_generated/catch2_v2_main.cpp"] = [==[
+#define CATCH_CONFIG_MAIN
+#include <catch2/catch.hpp>
+]==],
+        },
+        sources      = { "mcpp_generated/catch2_v2_anchor.c" },
+        targets      = { ["catch2-v2"] = { kind = "lib" } },
+        features     = {
+            ["main"] = { sources = { "mcpp_generated/catch2_v2_main.cpp" } },
+        },
+        deps         = { },
+    },
+}

pkgs/c/compat.catch2.lua

@@ -0,0 +1,82 @@
+-- Form B inline descriptor for Catch2 v3 — a modern C++ test framework.
+-- Built as a static library from the individual source files under
+-- src/catch2/ (NOT the amalgamated distribution). Consumers include
+-- <catch2/catch_all.hpp> (or more specific headers) and provide their
+-- own main() using Catch::Session, or request the `main` feature for a
+-- ready-made default entry point.
+--
+-- Features (sources-only gate):
+--   `main` — compiles catch_main.cpp (upstream's default main via
+--   Catch::Session). Excluded from the default source set via `!`
+--   negation; only compiled when features = ["main"] is requested
+--   (same pattern as compat.gtest's `main` feature).
+--
+-- All `mcpp` paths are GLOBS relative to the verdir; the leading `*`
+-- absorbs the GitHub tarball's `Catch2-<tag>/` wrap layer.
+package = {
+    spec        = "1",
+    namespace   = "compat",
+    name        = "catch2",
+    description = "A modern, C++-native test framework for unit-tests, TDD and BDD — v3 (C++14+)",
+    licenses    = {"BSL-1.0"},
+    repo        = "https://github.com/catchorg/Catch2",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["3.15.2"] = {
+                url    = "https://github.com/catchorg/Catch2/archive/refs/tags/v3.15.2.tar.gz",
+                sha256 = "acfae120892c2b67a74142d36d060c0caa96f1c3aaa8aabd96e19961163d0420",
+            },
+        },
+        macosx = {
+            ["3.15.2"] = {
+                url    = "https://github.com/catchorg/Catch2/archive/refs/tags/v3.15.2.tar.gz",
+                sha256 = "acfae120892c2b67a74142d36d060c0caa96f1c3aaa8aabd96e19961163d0420",
+            },
+        },
+        windows = {
+            ["3.15.2"] = {
+                url    = "https://github.com/catchorg/Catch2/archive/refs/tags/v3.15.2.tar.gz",
+                sha256 = "acfae120892c2b67a74142d36d060c0caa96f1c3aaa8aabd96e19961163d0420",
+            },
+        },
+    },
+
+    mcpp = {
+        language     = "c++23",
+        import_std   = false,
+        -- expose src/ so that #include <catch2/…> resolves to
+        -- Catch2-<tag>/src/catch2/…
+        -- mcpp_generated/ provides catch2/catch_user_config.hpp (normally
+        -- CMake-generated; we materialise a reasonable default here).
+        include_dirs = { "*/src", "mcpp_generated" },
+        -- catch_main.cpp provides a default main(). Excluded via `!`
+        -- negation from the default source set; only compiled when
+        -- features = ["main"] is requested (same pattern as compat.gtest).
+        generated_files = {
+            ["mcpp_generated/catch2/catch_user_config.hpp"] = [==[
+#ifndef CATCH_USER_CONFIG_HPP_INCLUDED
+#define CATCH_USER_CONFIG_HPP_INCLUDED
+
+#ifndef CATCH_CONFIG_DEFAULT_REPORTER
+#define CATCH_CONFIG_DEFAULT_REPORTER "console"
+#endif
+#ifndef CATCH_CONFIG_CONSOLE_WIDTH
+#define CATCH_CONFIG_CONSOLE_WIDTH 80
+#endif
+
+#endif
+]==],
+        },
+        sources      = {
+            "*/src/catch2/**/*.cpp",
+            "!*/src/catch2/internal/catch_main.cpp",
+        },
+        targets      = { ["catch2"] = { kind = "lib" } },
+        features     = {
+            ["main"] = { sources = { "*/src/catch2/internal/catch_main.cpp" } },
+        },
+        deps         = { },
+    },
+}

tests/examples/catch2-v2/mcpp.toml

@@ -0,0 +1,12 @@
+# Catch2 v2 test project: depends on compat.catch2-v2 (header-only via this
+# repo's own index) and asserts behavior under `mcpp test`.
+# Part of the mcpp-index self-referential workspace.
+[package]
+name = "catch2-v2-tests"
+version = "0.1.0"
+
+[indices]
+compat = { path = "../../.." }
+
+[dependencies.compat]
+catch2-v2 = "2.13.10"

tests/examples/catch2-v2/tests/main.cpp

@@ -0,0 +1,14 @@
+#define CATCH_CONFIG_MAIN
+#include <catch2/catch.hpp>
+
+static unsigned int factorial(unsigned int n) {
+    return n <= 1 ? 1 : n * factorial(n - 1);
+}
+
+TEST_CASE("factorial of 5 is 120", "[math]") {
+    REQUIRE(factorial(5) == 120);
+}
+
+TEST_CASE("factorial of 0 is 1", "[math]") {
+    REQUIRE(factorial(0) == 1);
+}

tests/examples/catch2/mcpp.toml

@@ -0,0 +1,12 @@
+# Catch2 v3 test project: depends on compat.catch2 (compiled from amalgamated
+# source via this repo's own index) and asserts behavior under `mcpp test`.
+# Part of the mcpp-index self-referential workspace.
+[package]
+name = "catch2-tests"
+version = "0.1.0"
+
+[indices]
+compat = { path = "../../.." }
+
+[dependencies.compat]
+catch2 = "3.15.2"

tests/examples/catch2/tests/main.cpp

@@ -0,0 +1,17 @@
+#include <catch2/catch_all.hpp>
+
+static unsigned int factorial(unsigned int n) {
+    return n <= 1 ? 1 : n * factorial(n - 1);
+}
+
+TEST_CASE("factorial of 5 is 120", "[math]") {
+    REQUIRE(factorial(5) == 120);
+}
+
+TEST_CASE("factorial of 0 is 1", "[math]") {
+    REQUIRE(factorial(0) == 1);
+}
+
+int main(int argc, char* argv[]) {
+    return Catch::Session().run(argc, argv);
+}