构建、测试与 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 可配置多平台矩阵构建,确保每次提交都经过完整验证