Catch2 贡献指南：测试分层、构建流程与编码规范实战详解

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用

本指南以仓库内置的 Catch2 测试框架（位于third_party/clingo-sys/clingo/third_party/catch/，作为 clingo 的第三方测试依赖引入）的官方贡献文档为主体，系统讲解为其提交代码的完整规范：从 Git 协作流程、分层测试体系与一键构建命令，到文档编写模板、C++14 编码约束与CATCH_CONFIG扩展流程。读完本文，你将能够按照官方标准为 Catch2 贡献 bug 修复与新特性，并能在本地复现其全部测试链路（SelfTest、Approval Tests、CTest 集成测试等）。

引言：贡献什么都可以，但先读规则

Catch2 的维护者欢迎一切形式的贡献——无论是 bug 修复、新特性、对新编译器的支持，还是文档修正；问题报告、评论与疑问同样被重视。官方建议把提问放到 Discord 而不是 issue 跟踪器，而代码库层面的贡献则应遵循本文所述的规范。这份指南覆盖四块核心内容：Git 协作方式、测试变更、编写文档与编写代码，并最终以行为准则（CoC）收尾。

一、Git 协作规范：分支、提交与合入节奏

开发分支

Catch2 的持续开发发生在devel分支（面向 v3），而 v2 版本的维护更新在v2.x分支上进行。这意味着任何新功能都应基于devel，只有针对 v2 的缺陷修复才提交到v2.x。

提交应当"小而原子"

• 原子性：一个提交在应用后，代码库（连同测试）仍应像预期一样工作。即"可独立回退、不影响整体可用性"。
• 小提交：小且原子的提交让后续的bisect（二分定位回归）、revert（回退）等 git 历史操作更容易。

提交 PR 时的两条硬性要求

1. 不要包含合并后的单文件发行包（amalgamated distribution files）：Catch2 通过generateAmalgamatedFiles.py生成extras/catch_amalgamated.cpp/catch_amalgamated.hpp这类聚合文件（仓库中extras/目录下可确认），提交 PR 时请勿把对这些文件的改动纳入 git 提交。
2. 回应 review 意见时不要立即 rebase/squash：立即压缩提交会让审阅者难以追踪新增改动、拖慢合入节奏。正确做法是在分支上追加新提交，仅在 MR 准备合入时才压缩。官方推荐用git commit --fixup（或--squash）创建新提交，最后用git rebase --autosquash自动完成压缩。

二、测试你的变更：Catch2 的分层测试体系

运行 Catch2 自身的测试依赖 Python3。Catch2 的测试分为多层，全部由 CI 驱动执行：

构建基础测试：basic-testspreset

在 Catch2 根目录执行：

cmake -B basic-test-build -S . -DCMAKE_BUILD_TYPE=Debug --preset basic-tests

从仓库的 CMakePresets.json 可以看到，basic-testspreset 的实质是仅开启CATCH_DEVELOPMENT_BUILD=ON，即"构建成本低的开发构建"。

按需开启各类测试

通过 CMake 选项逐类启用：

-DCATCH_BUILD_EXAMPLES=ON # 启用 examples 编译示例 -DCATCH_BUILD_EXTRA_TESTS=ON # 启用高成本 ExtraTests -DCATCH_ENABLE_CONFIGURE_TESTS=ON # 启用 CMake 配置测试

一键构建并运行全部测试：all-testspreset

all-tests继承basic-tests，并额外开启CATCH_BUILD_EXAMPLES、CATCH_BUILD_EXTRA_TESTS、CATCH_BUILD_SURROGATES、CATCH_ENABLE_CONFIGURE_TESTS与CATCH_ENABLE_CMAKE_HELPER_TESTS（见 CMakePresets.json）。官方给出的完整流程（Debug 模式，构建并运行全部测试）为：

# 1. 重新生成聚合发行文件（部分测试基于它构建） ./tools/scripts/generateAmalgamatedFiles.py # 2. 配置全量测试构建 cmake -B debug-build -S . -DCMAKE_BUILD_TYPE=Debug --preset all-tests # 3. 执行实际构建 cmake --build debug-build # 4. 用 CTest 运行测试 ctest -j 4 --output-on-failure -C Debug --test-dir debug-build

以上命令与仓库中 buildAndTest.sh 的catch2-build-and-test代码片段完全一致，可直接运行该脚本完成同样操作：

cd Catch2 ./tools/scripts/buildAndTest.sh

Windows 用户可使用同目录下的tools\scripts\buildAndTest.cmd。

新测试的审批（Approval）流程

如果你新增了测试，大概率会看到ApprovalTests失败——这是正常的，因为新输出与基线不同。确认输出差异符合预期后，运行tools/scripts/approve.py将新输出确认为基线，并把基线变更一并提交。

三、编写文档的规范

为 Catch2 新增特性必须有文档，否则其他用户无法使用。官方文档规范分为"技术细节"与"内容建议"两部分。

技术细节

• 新文档模板：新页面应使用固定模板，提供页面顶部锚点#top及返回文档首页的反链：

<a id="top"></a> # Cool feature > [Introduced](https://github.com/catchorg/Catch2/pull/123456) in Catch2 X.Y.Z Text that explains how to use the cool feature. --- [Home](https://link.gitcode.com/i/73272e13e5eeb01b0dfb26ba91008ee6)

（此处 PR 链接仅示意，实际编写时替换为对应 issue/PR 地址。）

• 跨页链接：链接到其他页面时应指向其top锚点，形如[link to contributing](https://link.gitcode.com/i/a956110d1f044cf9c34aeb43dbe863a2)。
• 版本标签：文档需标记特性的引入版本，新写文档使用占位符，发布时替换为真实版本。两种风格：
  • 小节标题后：> Introduced in Catch2 X.Y.Z
  • 子部分（如列表项）内：> X (Y and Z) was introduced in Catch2 X.Y.Z
• 目录（ToC）：超过 4 个子标题的页面须在顶部提供目录。由于 GitHub Markdown 不支持自动生成 ToC，需半手动维护：新增子标题后，手动或在scripts/目录下运行updateDocumentToC.py（仓库实际位于 tools/scripts/updateDocumentToC.py）更新。

内容建议

• 示例宜短：行内代码片段保持简短以免降低可读性；更复杂、可编译的示例应新增.cpp文件放入examples/目录。
• 敢于开新页：现有文档偏长，部分是历史遗留，不必在过长的旧页面上硬塞内容。
• 风格一致：在已有页面上增补信息时，格式与行文应与该页其余部分保持一致。
• 面向三类读者：初学者（需要更贴近的用法指导）、进阶用户（想自定义用法）、专家（需要完整能力参考），文档应尽量兼顾。

四、编写代码的规范

C++ 标准版本：C++14 为底线

Catch2 目前以C++14 为最低支持版本，更高标准的特性仅在"收益明显超过维护成本"时克制地使用。文档给出了正反两例：

• 好的 polyfill 示例：对conjunction的处理——可用时用std::conjunction，否则提供自有实现。维护面很小，且std::conjunction能直接用编译器内建函数，编译收益显著。
• 坏的 polyfill 示例：在字符串化实现里同时维护两套模板元编程（一套 C++14 兼容 TMP、一套 C++17if constexpr）。尽管 C++17 版本编译更快，但维护成本过高，得不偿失。

格式化：clang-format 只作用于新改代码

Catch2 提供自己的clang-format配置，但目前无法用 clang-format 完整还原现有 Catch2 格式，对整文件重排会产生巨大 diff。因此：只对新修改的代码运行 clang-format，保持 diff 规模可控。

需要警惕的代码构造

这部分列出的问题构造"很不幸地不完整"，且不一定被 CI 捕获，需要贡献者自觉：

1. 裸异常与异常相关函数：抛异常必须通过internal/catch_enforce.hpp中的CATCH_ERROR或CATCH_RUNTIME_ERROR宏。从源码（catch_enforce.hpp）可见其内部根据CATCH_CONFIG_DISABLE_EXCEPTIONS区分编译路径，统一处理"启用/禁用异常"两种编译模式。某些平台（如 IAR）对std::current_exception这类异常相关函数也有问题；如确需使用，应放在CATCH_CONFIG_DISABLE_EXCEPTIONS宏之后。
2. 避免std::move与std::forward：它们本质上是特定static_cast的语义化名称，但作为函数模板编译开销惊人，在低优化级别构建下还有负面性能影响。应改用 catch_move_and_forward.hpp 中的CATCH_MOVE/CATCH_FORWARD宏，其实现直接展开为对应static_cast，避开函数模板开销：

#define CATCH_MOVE(...) static_cast<std::remove_reference_t<decltype(__VA_ARGS__)>&&>(__VA_ARGS__) #define CATCH_FORWARD(...) static_cast<decltype(__VA_ARGS__)&&>(__VA_ARGS__)

3. C 标准库函数必须限定调用：使用 C stdlib 函数时，应以<cfoo>形式包含头文件并限定调用（如std::printf）。"两者没区别"的常识是错的——QNX 与 VxWorks 上若以<cfoo>包含头文件却不限定调用，将无法编译。
4. 为 Catch2 类型声明用户自定义字面量（UDL）的写法：受-Wreserved-identifier在 Clang 上的不理想实现影响，应避免Approx operator "" _a(long double);这种在""与后缀之间有空格的声明，改为无空格写法：

Approx operator ""_a(long double);

新源文件模板

每个新源文件必须以许可头开始：

// Copyright Catch2 Authors // Distributed under the Boost Software License, Version 1.0. // (See accompanying file LICENSE.txt or copy at // https://www.boost.org/LICENSE_1_0.txt) // SPDX-License-Identifier: BSL-1.0

头文件的 include guard 遵循{FILENAME}_INCLUDED模式：catch_matchers_foo.hpp对应CATCH_MATCHERS_FOO_HPP_INCLUDED，catch_generators_bar.hpp对应CATCH_GENERATORS_BAR_HPP_INCLUDED，以此类推。

新增CATCH_CONFIG选项的完整流程

新增编译期配置选项需要同时改动多处，官方清单如下：

五、行为准则与结语

本项目有 行为准则（CoC），贡献期间请遵守。Catch2 官方文档自述"永远处于进行中状态"——随着新信息的出现会持续更新，因此这份指南也应被当作活文档对待。

回到本仓库的实践视角：Catch2 以第三方依赖形式存在于 third_party/clingo-sys/clingo/third_party/catch/，其SelfTest单元测试、CTest 集成测试与 Approval 基线对比的分层测试思想，以及CATCH_MOVE/CATCH_FORWARD宏避免编译开销、CATCH_ERROR宏统一异常处理路径等工程技巧，都可作为阅读与借鉴对象——无论是向上游提交补丁，还是在本项目内复用其测试组织方式，这份规范都提供了清晰可执行的标准。

• 人工智能
• AI Agent
• 多模态
• 语音
• AI 应用