工程化:CMake、库、测试与调试
用现代 CMake 组织多目录项目并接入测试与调试工具
#从「能编译」到「能交付」
前面四章都在写代码,这一章解决的是让代码可被别人编译、可被自动验证、出问题能被定位。如果你用过 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_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,顶层只负责组装。下面的例子把三个文件和动态库导出头合在一起展示:
# ===== 顶层 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 自动生成,代码里这样使用:
#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 则在配置阶段下载源码并当作子项目一起编译,适合没有系统包的小依赖。两者可以混用:
# ===== 方式一: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 单元测试入门
// 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:
# 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 能在越界访问发生的那一刻给出调用栈,而不是等到几分钟后随机崩溃。下面是调试、插桩、编译选项与风格工具的一张速查表:
# ===== 一、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 列」团队规范:
{
"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。
#练习
- 把现有练习项目改造成三层结构:
core(静态库)、app(可执行文件)、tests(GoogleTest)。要求app只写一行target_link_libraries(app PRIVATE core)就能编译成功。 - 在
core的PUBLIC头文件里增加一个依赖类型,体会PUBLIC与PRIVATE包含路径的差别:把某头文件路径改成PRIVATE,观察app的编译错误。 - 用
FetchContent引入fmt或nlohmann/json,锁定具体版本号,替换掉手写的字符串拼接代码;确认build/_deps下出现了下载内容。 - (进阶)为项目配置三套构建:Debug(
-g -O0)、Release(-O2 -DNDEBUG)、Asan(-fsanitize=address,undefined)。故意在一处 vector 访问中越界,验证 Asan 能给出精确调用栈。