构建、测试与 CI
现代 C++ 项目的工程质量不仅取决于代码本身,还依赖完善的构建系统、自动化测试和持续集成。本章覆盖 Modern CMake、包管理、Catch2 单元测试、Sanitizer 集成以及 GitHub Actions CI 配置。
Modern CMake:以 Target 为中心
现代 CMake(3.x)的核心理念是一切围绕 target,不再使用全局变量污染整个构建:
避免的旧式写法
# 旧式 CMake(不要这样写!)
include_directories(${SOME_INCLUDE_DIR}) # 全局污染
link_directories(${SOME_LIB_DIR}) # 全局污染
add_definitions(-DSOME_FLAG) # 全局污染
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall") # 全局修改
正确的现代 CMake 写法:
cmake_minimum_required(VERSION 3.20)
project(my_project
VERSION 1.0.0
LANGUAGES CXX
DESCRIPTION "现代 C++ 示例项目"
)
# 设置 C++ 标准(target 级别)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
# 定义库 target
add_library(mylib
src/math.cpp
src/string_utils.cpp
)
# target 级别的属性设置
target_include_directories(mylib
PUBLIC include # 使用者也能看到
PRIVATE src # 仅内部使用
)
target_compile_features(mylib PUBLIC cxx_std_20)
target_compile_options(mylib
PRIVATE
$<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic>
$<$<CXX_COMPILER_ID:MSVC>:/W4>
)
# 可执行文件 target
add_executable(app src/main.cpp)
target_link_libraries(app PRIVATE mylib) # 依赖传播
PUBLIC / PRIVATE / INTERFACE
PRIVATE:仅当前 target 使用,不传播给链接者PUBLIC:当前 target 使用,且传播给所有链接此 target 的消费者INTERFACE:仅传播给消费者,自身不使用(header-only 库常用)
依赖管理:vcpkg 与 Conan
vcpkg 集成
# 安装 vcpkg
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg && ./bootstrap-vcpkg.sh
# 安装依赖
./vcpkg install fmt catch2 spdlog
# CMake 中使用(通过 toolchain file)
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
# CMakeLists.txt 中直接 find_package
find_package(fmt CONFIG REQUIRED)
find_package(spdlog CONFIG REQUIRED)
target_link_libraries(app PRIVATE fmt::fmt spdlog::spdlog)
vcpkg.json 清单模式
// vcpkg.json(放在项目根目录)
{
"name": "my-project",
"version": "1.0.0",
"dependencies": [
"fmt",
"spdlog",
{
"name": "catch2",
"version>=": "3.4.0"
}
]
}
单元测试:Catch2
Catch2 是 C++ 最流行的单元测试框架之一,语法简洁、无需注册:
# CMakeLists.txt - 引入 Catch2
find_package(Catch2 3 REQUIRED)
add_executable(tests
tests/test_math.cpp
tests/test_string.cpp
)
target_link_libraries(tests PRIVATE Catch2::Catch2WithMain mylib)
# 自动发现测试用例并注册到 CTest
include(Catch)
catch_discover_tests(tests)
// tests/test_math.cpp
#include <catch2/catch_test_macros.hpp>
#include <catch2/matchers/catch_matchers_floating_point.hpp>
#include "math.h"
TEST_CASE("加法运算", "[math]") {
REQUIRE(add(2, 3) == 5);
REQUIRE(add(-1, 1) == 0);
REQUIRE(add(0, 0) == 0);
}
TEST_CASE("除法运算", "[math]") {
SECTION("正常除法") {
REQUIRE(divide(10, 2) == 5.0);
REQUIRE(divide(7, 2) == 3.5);
}
SECTION("除以零抛出异常") {
REQUIRE_THROWS_AS(divide(1, 0), std::invalid_argument);
}
SECTION("浮点数近似比较") {
using Catch::Matchers::WithinRel;
REQUIRE_THAT(divide(1, 3), WithinRel(0.3333, 0.01));
}
}
TEST_CASE("阶乘", "[math]") {
REQUIRE(factorial(0) == 1);
REQUIRE(factorial(1) == 1);
REQUIRE(factorial(5) == 120);
REQUIRE(factorial(10) == 3628800);
}
// SECTION 嵌套:共享 setup
TEST_CASE("容器操作", "[container]") {
std::vector<int> v = {1, 2, 3, 4, 5};
SECTION("查找元素") {
auto it = std::find(v.begin(), v.end(), 3);
REQUIRE(it != v.end());
REQUIRE(*it == 3);
}
SECTION("删除元素后大小减少") {
v.erase(v.begin());
REQUIRE(v.size() == 4);
SECTION("再删除一个") {
v.erase(v.begin());
REQUIRE(v.size() == 3);
}
}
// 每个 SECTION 都从 v = {1,2,3,4,5} 开始!
}
Catch2 核心断言宏
REQUIRE(expr)— 失败时终止当前测试CHECK(expr)— 失败时记录但继续执行REQUIRE_THROWS_AS(expr, exception)— 验证抛出指定异常REQUIRE_NOTHROW(expr)— 验证不抛出异常REQUIRE_THAT(expr, matcher)— 使用 Matcher 做复杂断言
Google Test 简介
Google Test (gtest) 是另一个广泛使用的框架,风格略有不同:
#include <gtest/gtest.h>
#include "math.h"
TEST(MathTest, Addition) {
EXPECT_EQ(add(2, 3), 5);
EXPECT_EQ(add(-1, 1), 0);
}
TEST(MathTest, DivisionByZero) {
EXPECT_THROW(divide(1, 0), std::invalid_argument);
}
// Fixture:共享测试状态
class StackTest : public ::testing::Test {
protected:
void SetUp() override {
stack.push(1);
stack.push(2);
}
std::stack<int> stack;
};
TEST_F(StackTest, PopReturnsTop) {
EXPECT_EQ(stack.top(), 2);
stack.pop();
EXPECT_EQ(stack.top(), 1);
}
CTest 集成
# 在顶层 CMakeLists.txt 中启用测试
enable_testing()
# 手动添加测试(简单方式)
add_test(NAME unit_tests COMMAND tests)
# 或使用 Catch2 自动发现(推荐)
include(Catch)
catch_discover_tests(tests
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
PROPERTIES TIMEOUT 30
)
# 运行测试
cmake --build build
cd build && ctest --output-on-failure
# 运行特定测试
ctest -R "Math" # 名称匹配
ctest -L "unit" # 标签匹配
ctest -j$(nproc) # 并行执行
ctest --rerun-failed # 只重跑失败的
Sanitizer 集成
Sanitizer 是发现内存错误、数据竞争和未定义行为的利器:
# CMake 中添加 Sanitizer 选项
option(ENABLE_ASAN "Enable AddressSanitizer" OFF)
option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)
option(ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF)
if(ENABLE_ASAN)
target_compile_options(mylib PUBLIC -fsanitize=address -fno-omit-frame-pointer)
target_link_options(mylib PUBLIC -fsanitize=address)
endif()
if(ENABLE_TSAN)
target_compile_options(mylib PUBLIC -fsanitize=thread)
target_link_options(mylib PUBLIC -fsanitize=thread)
endif()
if(ENABLE_UBSAN)
target_compile_options(mylib PUBLIC -fsanitize=undefined)
target_link_options(mylib PUBLIC -fsanitize=undefined)
endif()
# 构建时启用 ASan
cmake -B build -DENABLE_ASAN=ON
cmake --build build
./build/tests # ASan 会在运行时检测内存错误
Sanitizer 注意事项
- ASan 和 TSan 不能同时使用(互斥)
- Sanitizer 会使程序运行变慢 2-10 倍,仅用于测试/CI
- 务必在 CI 中运行 ASan + UBSan 构建,它们能发现大量隐藏 bug
- MSVC 支持 ASan(
/fsanitize=address),但不支持 TSan/UBSan
GitHub Actions CI 配置
完整的 C++ CI 工作流,覆盖多平台构建、测试和 Sanitizer:
# .github/workflows/ci.yml
name: C++ CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build-and-test:
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
build_type: [Release, Debug]
include:
- os: ubuntu-latest
build_type: Debug
sanitizer: ENABLE_ASAN
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- name: Install vcpkg dependencies
run: |
vcpkg install
- name: Configure CMake
run: |
cmake -B build \
-DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
-DCMAKE_TOOLCHAIN_FILE=$VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake \
-D${{ matrix.sanitizer || 'DUMMY' }}=ON
- name: Build
run: cmake --build build --config ${{ matrix.build_type }} -j
- name: Test
working-directory: build
run: ctest --build-config ${{ matrix.build_type }} --output-on-failure -j
sanitizer-check:
runs-on: ubuntu-latest
strategy:
matrix:
sanitizer: [ENABLE_ASAN, ENABLE_UBSAN, ENABLE_TSAN]
steps:
- uses: actions/checkout@v4
- name: Configure with Sanitizer
run: |
cmake -B build \
-DCMAKE_BUILD_TYPE=Debug \
-D${{ matrix.sanitizer }}=ON
- name: Build
run: cmake --build build -j
- name: Run Tests under Sanitizer
working-directory: build
run: ctest --output-on-failure
env:
ASAN_OPTIONS: "detect_leaks=1:abort_on_error=1"
UBSAN_OPTIONS: "print_stacktrace=1:halt_on_error=1"
代码覆盖率
# 覆盖率编译选项
option(ENABLE_COVERAGE "Enable code coverage" OFF)
if(ENABLE_COVERAGE)
target_compile_options(mylib PUBLIC --coverage -O0 -g)
target_link_options(mylib PUBLIC --coverage)
endif()
# 生成覆盖率报告
cmake -B build -DENABLE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build
cd build && ctest
# 使用 lcov 收集覆盖率数据
lcov --capture --directory . --output-file coverage.info
lcov --remove coverage.info '/usr/*' '*/test/*' --output-file coverage_filtered.info
# 生成 HTML 报告
genhtml coverage_filtered.info --output-directory coverage_report
# 打开 coverage_report/index.html 查看
# GitHub Actions 中上传覆盖率到 Codecov
- name: Upload coverage
if: matrix.build_type == 'Debug' && matrix.os == 'ubuntu-latest'
uses: codecov/codecov-action@v3
with:
files: build/coverage_filtered.info
推荐的项目结构
my-project/
├── CMakeLists.txt # 顶层构建文件
├── CMakePresets.json # 构建预设
├── vcpkg.json # 依赖清单
├── .github/
│ └── workflows/
│ └── ci.yml # CI 配置
├── include/
│ └── mylib/
│ ├── math.h
│ └── string_utils.h
├── src/
│ ├── CMakeLists.txt # 库的构建文件
│ ├── math.cpp
│ └── string_utils.cpp
├── app/
│ ├── CMakeLists.txt # 应用的构建文件
│ └── main.cpp
└── tests/
├── CMakeLists.txt # 测试的构建文件
├── test_math.cpp
└── test_string.cpp
本章小结
- Modern CMake 以 target 为中心,通过
target_*命令管理编译选项和依赖传播 - vcpkg/Conan 解决第三方依赖管理,
vcpkg.json清单模式最适合项目协作 - Catch2 的
TEST_CASE/SECTION/REQUIRE提供简洁的测试组织 - ASan/TSan/UBSan 是发现内存错误和未定义行为的强大工具,应集成到 CI
- GitHub Actions 可配置多平台矩阵构建,确保每次提交都经过完整验证