QC++ / Qt 学习之路

工程化:CMake、库、测试与调试

用现代 CMake 组织多目录项目并接入测试与调试工具

进阶第 15 / 48 章第二篇 · C++ 进阶与工程实践

#从「能编译」到「能交付」

前面四章都在写代码,这一章解决的是让代码可被别人编译、可被自动验证、出问题能被定位。如果你用过 Java 的 Maven/Gradle 或 Python 的 Poetry,CMake 的角色类似——但它不是包管理器,而是构建系统生成器:CMake 读取 CMakeLists.txt,生成 Makefile 或 Ninja 文件,再由真正的构建工具编译。JS 生态的 npm + webpack 组合最接近这个分层,但 CMake 的历史包袱更重,存在两套截然不同的写法。本章只讲现代 CMake(3.15+),核心思想一句话:围绕 target 组织,而不是围绕目录和全局变量。

先建立最重要的心智模型:CMake 里的 target 就是一个构建产物(可执行文件、库)。所有属性(头文件路径、链接库、编译选项、C++ 标准)都挂在 target 上,并通过 PRIVATE / PUBLIC / INTERFACE 三个关键字决定是否传递给依赖者。老式写法用 include_directories() / link_libraries() 这类全局命令,污染所有 target,是必须摒弃的。

关键字自己用传递给依赖者典型用途
PRIVATE是否源文件内部实现、私有头文件
INTERFACE否是纯头文件库的需求
PUBLIC是是头文件里暴露的类型、对外 API

#现代 CMake 的最小骨架

CMake
cmake_minimum_required(VERSION 3.16)
project(MyApp VERSION 1.0.0 LANGUAGES CXX)

# 全局默认标准,可被 target 覆盖
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)      # 关闭 -std=gnu++17,用纯 -std=c++17

# 可执行文件 target
add_executable(my_app
    src/main.cpp
    src/app.cpp
)

# 头文件搜索路径:src/ 对外可见,src/detail/ 只自己用
target_include_directories(my_app
    PUBLIC  ${CMAKE_CURRENT_SOURCE_DIR}/include
    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src
)

# 编译选项(PRIVATE 表示不影响链接本 target 的人)
target_compile_options(my_app PRIVATE
    $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic>
    $<$<CXX_COMPILER_ID:MSVC>:/W4>
)

# 预处理器宏
target_compile_definitions(my_app PRIVATE VERSION_STRING="1.0.0")

$<...> 是生成器表达式,在生成构建系统时才求值,可以做条件判断(上面按编译器 ID 分支)和按配置分支($<$<CONFIG:Debug>:-g>)。这是现代 CMake 表达「条件配置」的标准方式,比 if() 语句更精确,因为它能正确处理多配置生成器(如 Visual Studio)。

#多目录项目与库的拆分

真实项目不会只有一个目录。做法是在每个子目录放一个 CMakeLists.txt,顶层用 add_subdirectory() 串起来:子目录负责定义自己的 target,顶层只负责组装。下面的例子把三个文件和动态库导出头合在一起展示:

CMake
# ===== 顶层 CMakeLists.txt =====
cmake_minimum_required(VERSION 3.16)
project(SuperCalc VERSION 0.1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)   # 生成 compile_commands.json,clangd/VSCode 需要

option(SUPERCALC_BUILD_TESTS "Build unit tests" ON)

add_subdirectory(core)      # 定义 core 库
add_subdirectory(app)       # 定义 supercalc 可执行文件

if(SUPERCALC_BUILD_TESTS)
    enable_testing()
    add_subdirectory(tests)
endif()

# ===== core/CMakeLists.txt =====
add_library(core SHARED           # STATIC / SHARED / OBJECT,不写则看 BUILD_SHARED_LIBS
    src/parser.cpp
    src/evaluator.cpp
)

# 关键:把头文件路径绑到 target 上,依赖 core 的人自动获得
target_include_directories(core
    PUBLIC  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
            $<INSTALL_INTERFACE:include>
    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src
)

target_compile_features(core PUBLIC cxx_std_17)   # 标准要求也随 target 传播

# 动态库导出头:处理 Windows 的 dllexport/dllimport
include(GenerateExportHeader)
generate_export_header(core EXPORT_FILE_NAME ${CMAKE_CURRENT_BINARY_DIR}/core_export.h)
target_include_directories(core PUBLIC ${CMAKE_CURRENT_BINARY_DIR})

# ===== app/CMakeLists.txt =====
add_executable(supercalc src/main.cpp)
target_link_libraries(supercalc PRIVATE core)     # 自动继承 core 的 PUBLIC 包含路径

注意 target_compile_features(core PUBLIC cxx_std_17):它比 set(CMAKE_CXX_STANDARD) 更推荐,因为标准要求会沿依赖链传播,保证整个依赖图里的 C++ 标准一致。而 app 只需一行 target_link_libraries 就能拿到 core 的公开头文件路径——这正是 PUBLIC 关键字的价值,也是老式全局 include_directories() 做不到的事。

#静态库与动态库的取舍

动态库导出的头文件由上面的 generate_export_header 自动生成,代码里这样使用:

C++
#include <core_export.h>          // 由 generate_export_header 生成
#include <string>

class CORE_EXPORT Parser {        // 宏在 Windows 上展开为 dllexport/dllimport
public:
    explicit Parser(std::string text);
    double eval();
private:
    std::string text_;
};

取舍建议:静态库(.a/.lib)链接进最终产物,部署简单、无运行时依赖,但体积大且无法单独更新;动态库(.so/.dylib/.dll)可被多个程序共享、支持热更新,但存在「DLL Hell」和符号可见性问题。同一份源码编译成动态库时,务必用 -fvisibility=hidden + 显式导出宏,只暴露必要的符号。

#第三方依赖:find_package 与 FetchContent

find_package 查找已安装在系统里的库(如 Qt、OpenSSL、Boost),成功后提供导入 target(形如 Qt6::Core、OpenSSL::SSL);FetchContent 则在配置阶段下载源码并当作子项目一起编译,适合没有系统包的小依赖。两者可以混用:

CMake
# ===== 方式一:find_package,适用于系统/包管理器已安装的依赖 =====
find_package(Qt6 6.5 REQUIRED COMPONENTS Core Widgets)
find_package(OpenSSL REQUIRED)

target_link_libraries(my_app PRIVATE
    Qt6::Core
    Qt6::Widgets
    OpenSSL::SSL
)

# Qt 项目还需要开启自动 moc / uic / rcc
set_target_properties(my_app PROPERTIES
    AUTOMOC ON
    AUTOUIC ON
    AUTORCC ON
)

# ===== 方式二:FetchContent,配置期下载源码并一起构建 =====
include(FetchContent)

FetchContent_Declare(fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG        10.2.1          # 务必锁定版本,别用 main
    GIT_SHALLOW    TRUE
)
FetchContent_MakeAvailable(fmt)     # 下载 + add_subdirectory

target_link_libraries(my_app PRIVATE fmt::fmt)

FetchContent 比老式的 ExternalProject 好用得多,因为下载来的 target 可以直接链接,不必等到构建期才处理。

对比一下生态:Java 的 Maven 从中央仓库拉 jar,Python 的 pip 拉 wheel,JS 的 npm 拉源码包——它们都是「解析声明 + 下载 + 缓存」的一体化流程。C++ 至今没有官方包管理器(Conan / vcpkg 是社区方案),FetchContent 是最接近内置体验的做法,但它会把依赖的编译时间算进你的构建里。团队协作时建议优先 find_package + vcpkg/Conan 管理二进制,依赖很少时再用 FetchContent。

#GoogleTest 单元测试入门

C++
// tests/test_parser.cpp
#include <gtest/gtest.h>
#include <core/parser.h>      // 被测代码

// TEST(测试套件名, 测试名)
TEST(ParserTest, HandlesSimpleAddition) {
    Parser p("1+2");
    EXPECT_DOUBLE_EQ(p.eval(), 3.0);
}

TEST(ParserTest, HandlesWhitespace) {
    Parser p("  2 * 3 ");
    EXPECT_DOUBLE_EQ(p.eval(), 6.0);
}

// 参数化测试:同一逻辑跑多组数据
class ParserParamTest : public ::testing::TestWithParam<std::pair<std::string, double>> {};

TEST_P(ParserParamTest, EvaluatesCorrectly) {
    auto [expr, expected] = GetParam();     // 结构化绑定,见 p2-03
    Parser p(expr);
    EXPECT_DOUBLE_EQ(p.eval(), expected);
}

INSTANTIATE_TEST_SUITE_P(BasicCases, ParserParamTest,
    ::testing::Values(
        std::make_pair("1+1", 2.0),
        std::make_pair("10/4", 2.5),
        std::make_pair("2*(3+4)", 14.0)
    ));

// 多个测试共享的夹具
class ParserFixture : public ::testing::Test {
protected:
    void SetUp() override { /* 每个 TEST_F 前执行 */ }
    void TearDown() override { /* 每个 TEST_F 后执行 */ }
    Parser make(const std::string& s) { return Parser(s); }
};

TEST_F(ParserFixture, RejectsEmptyInput) {
    EXPECT_THROW(make("").eval(), std::runtime_error);
}

配套 CMake:

CMake
# tests/CMakeLists.txt
add_executable(unit_tests
    test_parser.cpp
    test_evaluator.cpp
)
target_link_libraries(unit_tests PRIVATE core GTest::gtest_main)

include(GoogleTest)
gtest_discover_tests(unit_tests)    # 让 ctest 自动发现每个 TEST

然后 cmake -S . -B build && cmake --build build && cd build && ctest --output-on-failure。断言分两类:EXPECT_* 失败后继续执行当前测试,ASSERT_* 失败立即返回——前者能一次看到多个问题,后者用于「后续代码依赖前置条件」的场合。

#调试:GDB/LLDB 与 AddressSanitizer

命令行调试器值得掌握,尤其在服务器和无 GUI 环境里。GDB(GCC)和 LLDB(Clang/macOS)命令基本对应,常用命令已列在下表第一部分。

真正让 C++ 调试效率质变的是 Sanitizer——编译器插桩,在运行时捕获内存错误。AddressSanitizer 能在越界访问发生的那一刻给出调用栈,而不是等到几分钟后随机崩溃。下面是调试、插桩、编译选项与风格工具的一张速查表:

Shell
# ===== 一、GDB / LLDB 常用命令(编译时必须带 -g,并用 -O0)=====
g++ -g -O0 -std=c++17 src/*.cpp -o app
gdb ./app                    # macOS 用 lldb ./app
# (gdb) break parser.cpp:42  # 按文件:行号下断点
# (gdb) break Parser::eval   # 按函数名下断点
# (gdb) run / next / step    # 启动 / 单步不进函数 / 单步进函数
# (gdb) print expr_          # 打印变量
# (gdb) backtrace / frame 2  # 查看调用栈(崩溃后第一件事)/ 切换栈帧
# (gdb) watch counter        # 变量被修改时停下
# (gdb) continue

# ===== 二、Sanitizer:越界 / use-after-free / double free / 数据竞争 =====
g++ -g -O1 -fsanitize=address,undefined -fno-omit-frame-pointer -std=c++17 src/*.cpp -o app_asan
./app_asan                              # 出错瞬间打印详细报告 + 调用栈
ASAN_OPTIONS=detect_leaks=1 ./app_asan  # 顺带检测内存泄漏

g++ -g -O1 -fsanitize=thread -std=c++17 src/*.cpp -o app_tsan   # 配合 p2-02 的并发代码

# CMake 中做成独立构建类型:cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=Asan
# set(CMAKE_CXX_FLAGS_ASAN "-g -O1 -fsanitize=address,undefined -fno-omit-frame-pointer")

# ===== 二、优化级别 =====
# -O0  不优化,调试默认,变量不被优化掉
# -O1  基础优化,配合 Sanitizer 使用
# -O2  发布默认,绝大多数项目的选择
# -O3  激进优化(含自动向量化),可能增大体积、偶发数值差异
# -Os  优化体积            -flto 链接期优化,跨单元内联,收益明显但链接变慢

# ===== 三、常用诊断与加固 =====
# -Wall -Wextra -Wpedantic  开启警告;-Werror 警告即错误,CI 强烈推荐
# -Wshadow -Wconversion     变量遮蔽与隐式转换,严格项目开启
# -g 调试信息   -fno-omit-frame-pointer 保留栈帧   -DNDEBUG 关闭 assert
# -march=native 用本机指令集,注意产物不可跨机器分发

# ===== 四、风格与静态分析 =====
clang-format -i src/*.cpp include/**/*.h     # -i 原地格式化
clang-format --dry-run -Werror src/          # CI 中只检查不修改
clang-tidy src/main.cpp -- -std=c++17 -Iinclude

对比 Java/Python 的体验:它们有运行时边界检查,越界立刻抛 ArrayIndexOutOfBoundsException 或 IndexError,崩溃点就是出错点;Python 还有引用计数兜底,几乎不会出现 use-after-free。C++ 两者都没有——越界是未定义行为,可能静默破坏几十行之外的内存,等你发现时现场早已消失。所以 Sanitizer 不是可选项,而应成为开发流程的默认配置,CI 里至少跑一套 Asan + Tsan + UBSan 的测试,这相当于给 C++ 临时装上 Java 和 Python 自带的那些运行时护栏。

CMake 的对应写法是用 CMAKE_CXX_FLAGS_RELEASE 或在 target 上加 target_compile_options。建议在 Debug 构建里保留 -g -O0,Release 用 -O2 -DNDEBUG,CI 额外加一套 Asan 构建,三套配置并存,用 -DCMAKE_BUILD_TYPE 切换。

#代码风格与 clang-format

风格统一靠工具而非自觉——争论括号该不该换行没有意义,把规则写进配置文件、交给工具执行才有意义。.clang-format 放在仓库根目录,主流预设选 LLVM、Google 或 Microsoft,Qt 项目通常用自定义配置。下面这份等价于常见的「4 空格缩进 + 100 列」团队规范:

JSON
{
  "BasedOnStyle": "Google",
  "IndentWidth": 4,
  "ColumnLimit": 100,
  "AllowShortFunctionsOnASingleLine": "Inline",
  "SortIncludes": "CaseSensitive",
  "BreakBeforeBraces": "Attach"
}

把 clang-format 接到编辑器的保存钩子上,把 clang-tidy 和编译警告接到 CI,风格争论就自然消失了。这也呼应了第一篇的命名约定:代码风格的意义在于让 diff 只显示真正的逻辑变化。

#小结

  • 现代 CMake 围绕 target 组织:target_include_directories / target_link_libraries 配 PRIVATE/PUBLIC/INTERFACE 控制属性传播,摒弃全局命令。
  • 多目录项目用 add_subdirectory(),子目录定义 target、顶层组装;标准要求用 target_compile_features(... PUBLIC cxx_std_17) 传播。
  • 静态库部署简单、动态库可共享更新;动态库需 generate_export_header 处理 Windows 导出符号,并隐藏非必要符号。
  • 依赖管理优先 find_package(系统安装的 Qt/OpenSSL),轻量依赖用 FetchContent(务必锁定版本);GoogleTest 配 gtest_discover_tests 接入 ctest。
  • 调试用 GDB/LLDB 的 break/backtrace/watch;ASan/TSan/UBSan 应在开发和 CI 中默认开启;风格统一交给 clang-format 与 clang-tidy。

#练习

  1. 把现有练习项目改造成三层结构:core(静态库)、app(可执行文件)、tests(GoogleTest)。要求 app 只写一行 target_link_libraries(app PRIVATE core) 就能编译成功。
  2. 在 core 的 PUBLIC 头文件里增加一个依赖类型,体会 PUBLIC 与 PRIVATE 包含路径的差别:把某头文件路径改成 PRIVATE,观察 app 的编译错误。
  3. 用 FetchContent 引入 fmt 或 nlohmann/json,锁定具体版本号,替换掉手写的字符串拼接代码;确认 build/_deps 下出现了下载内容。
  4. (进阶)为项目配置三套构建:Debug(-g -O0)、Release(-O2 -DNDEBUG)、Asan(-fsanitize=address,undefined)。故意在一处 vector 访问中越界,验证 Asan 能给出精确调用栈。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。