CMake 工程化实战：从单文件到大型项目

为什么是 CMake

C++ 生态长期缺乏统一的构建工具。Make 语法晦涩且难以跨平台，Ninja 需要先生成规则，各 IDE 的专属项目文件更是互不兼容。CMake 的价值在于它充当了一个"元构建系统"——用一套声明式脚本描述项目结构，再生成平台原生的构建文件（Makefile、Ninja、Visual Studio 工程、Xcode 工程）。如今在 GitHub 上搜索主流 C++ 开源项目，超过七成使用 CMake 作为首选构建系统，它已是事实上的行业标准。

CMake 真正的竞争力还体现在生态整合能力。CLion 直接原生支持，Visual Studio 2017 起内置 CMake 工作负载，VS Code 通过 CMake Tools 扩展可获得完整的配置-编译-调试体验。对于团队协作而言，这意味着无论成员使用 Windows、macOS 还是 Linux，都能用同一套脚本构建项目，消除了"在我机器上能跑"的隐患。

旧式 CMake 的陷阱

在 CMake 3.x 的早期版本中，开发者习惯于使用全局命令：

include_directories(${CMAKE_SOURCE_DIR}/third_party/boost)
add_definitions(-DUSE_OPENSSL)
link_libraries(pthread)

这些命令的问题在于作用域是目录级别甚至全局的。include_directories 会让当前目录及其子目录下的所有目标都继承头文件搜索路径，link_libraries 会让所有后续目标都链接指定库。当项目规模扩大后，依赖关系变得混沌不清：一个可执行文件究竟真正依赖了哪些库？某个第三方头文件泄漏到了不该去的地方？全局设置让这些问题难以回答，最终演变成"依赖地狱"。

Modern CMake：基于 Target 的核心哲学

CMake 3.0 引入了基于 Target 的现代范式，3.15+ 版本进一步完善了相关功能。核心思想是把每个库或可执行文件视为独立实体，通过属性的显式声明来描述其接口契约。Target 之间通过 PRIVATE、PUBLIC、INTERFACE 三种可见性控制依赖传播。

target_include_directories 是最常用的接口声明命令。如果一个头文件只在实现文件（.cpp）中被引用，使用 PRIVATE；如果头文件会出现在本库对外暴露的头文件中（即下游包含本库头文件时也需要这个路径），使用 PUBLIC；如果本库只依赖某个第三方实现但头文件完全不暴露（比如纯接口库），则用 INTERFACE。

target_include_directories(mylib
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
    PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}/src
)

target_compile_features 用于声明目标所需的 C++ 标准特性，CMake 会自动推导所需的编译器选项。这比手写 -std=c++20 更可靠，因为不同编译器的标准开关并不一致。

target_compile_features(myapp PRIVATE cxx_std_20)

target_link_libraries 在现代 CMake 中承担了依赖传播的角色。当目标 A 以 PUBLIC 链接目标 B 时，任何链接 A 的目标都会自动获得 B 的 include 路径和链接标志。这种传递性使得依赖链的配置大幅简化，每个目标只需要关心自己的直接依赖。

target_compile_options 和 target_compile_definitions 同样遵循 Target 作用域。建议始终使用这些命令替代全局的 add_compile_options 和 add_definitions，确保编译选项不会意外泄漏到不相关的目标上。

中大型项目的推荐目录结构

经过实践验证的目录布局可以有效控制项目复杂度。以下是一个中型 C++ 项目的典型结构：

myproject/
  cmake/              # 自定义模块和工具链文件
  include/myproject/  # 公开头文件（安装时导出）
  src/                # 实现文件和内部头文件
  tests/              # 单元测试
  external/           # 第三方依赖（FetchContent 缓存）
  CMakeLists.txt

根目录的 CMakeLists.txt 负责全局配置，各子模块通过 add_subdirectory() 引入。这种方式允许多个 Target 独立演进，也便于后续拆分为独立仓库。测试目录通常独立成一个子模块，仅在 BUILD_TESTING 为真时启用。

下面是一个完整的根 CMakeLists.txt，涵盖库、可执行文件和测试：

cmake_minimum_required(VERSION 3.15)
project(MyProject VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

option(BUILD_TESTING "Build tests" ON)

add_subdirectory(src)

if(BUILD_TESTING)
    enable_testing()
    add_subdirectory(tests)
endif()

src 目录下的 CMakeLists.txt：

add_library(mylib
    core/engine.cpp
    core/utils.cpp
)

target_include_directories(mylib
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
)

target_compile_features(mylib PUBLIC cxx_std_17)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE mylib)

tests 目录：

include(FetchContent)
FetchContent_Declare(
    Catch2
    GIT_REPOSITORY https://github.com/catchorg/Catch2.git
    GIT_TAG v3.5.0
)
FetchContent_MakeAvailable(Catch2)

add_executable(mytest test_engine.cpp)
target_link_libraries(mytest PRIVATE mylib Catch2::Catch2WithMain)

include(Catch)
catch_discover_tests(mytest)

第三方依赖管理方案对比

C++ 的依赖管理长期饱受诟病，CMake 生态提供了多种解决路径。

FetchContent 是 CMake 3.11 引入的内置模块，会在配置阶段从远程拉取源码并作为子项目构建。它的优势是零外部工具依赖，与 CMake 无缝集成；缺点是大型依赖（如 Boost）会导致配置时间显著增加，且每个项目都自行构建依赖而不是复用二进制包。

vcpkg 是微软维护的跨平台包管理器，拥有超过两千个移植库。它使用经典的 install + find_package 模式，支持版本锁定和自定义 Overlay 端口。对于团队而言，可以通过 NuGet 注册表或 Git 仓库共享二进制缓存，大幅减少重复编译。

Conan 的设计更接近现代语言包管理器，使用 Python 编写的 recipe 描述包的构建和消费方式。它支持构建配置（Debug/Release、编译器版本、ABI）的精确匹配，并提供远程仓库（ConanCenter）和企业级私有仓库方案。Conan 2.x 与 CMake 的集成通过 CMakeDeps 和 CMakeToolchain 生成器实现。

当依赖本身提供了 Config 文件（如 fmt、spdlog），优先使用 find_package(... CONFIG REQUIRED) 配合 target_link_libraries，这样可以完整获取目标的 include 目录、编译定义和传递依赖。

进阶主题

预设工作流（CMake 3.19+ 的 cmake --preset）将构建配置从命令行参数迁移到版本控制的 JSON 文件中。团队成员只需 cmake --preset=dev 即可获得一致的构建目录、生成器和编译器标志，彻底告别冗长的初始化命令。

{
  "version": 3,
  "configurePresets": [
    {
      "name": "dev",
      "generator": "Ninja",
      "binaryDir": "build",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "CMAKE_CXX_COMPILER_LAUNCHER": "ccache"
      }
    }
  ]
}

库的安装与导出。如果你正在开发一个供他人使用的库，需要编写安装规则和 CMake 配置导出文件，使下游项目可以通过 find_package(YourLib) 使用你的 Target。

include(GNUInstallDirs)
install(TARGETS mylib
    EXPORT MyLibTargets
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

install(EXPORT MyLibTargets
    FILE MyLibTargets.cmake
    NAMESPACE MyLib::
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyLib
)

CPack 可与打包格式（DEB、RPM、NSIS、DragNDrop）集成，一行 cpack 即可生成平台安装包，适合发布闭源 SDK 或内部工具。

自定义 Find 模块。当某个库未提供 Config 文件时，可在 cmake/ 目录下编写 FindXXX.cmake，通过 find_library 和 find_path 定位库文件并创建 IMPORTED Target。虽然 Modern CMake 鼓励库作者提供 Config 文件，但在维护老旧依赖时这仍是必备技能。

工程实践建议

始终坚持使用 target_* 系列命令配置 Target 属性，避免全局作用域污染。在 CMakeLists.txt 第一行显式声明 cmake_minimum_required，锁定所依赖的功能集合，防止旧版本 CMake 静默报错。构建目录必须与源码目录分离（out-of-source build），这是保留源码树洁净的唯一方式。

生成器首选 Ninja，它的构建速度显著优于传统 Makefile，且与并行编译配合更好。安装 ccache 并在 CMake 中通过 CMAKE_CXX_COMPILER_LAUNCHER 启用，可以在反复构建大型项目时节省大量时间。最终，保持 CMake 脚本的可读性和维护性——它也是项目代码的一部分，值得同样的工程投入。