大型项目实战：项目结构设计、模块化构建、版本管理、持续集成、文档生成

说实话，学到这里，你已经掌握了 CMake 的绝大部分核心技能。但真正考验人的，从来不是单个知识点，而是怎么把这些东西组合起来，去支撑一个真正的大型项目。

我这些年参与过好几个百万行级别的 C++ 项目，踩过的坑比写过的代码还多。今天这一章，我就把那些血泪教训浓缩成一套实战方案。你想想看，一个大型项目最怕什么？结构混乱、构建缓慢、版本失控、集成痛苦、文档缺失。嗯，咱们一个一个来解决。

1. 项目结构设计：别让代码变成一团乱麻

我个人习惯，在项目根目录下只放三样东西：顶层 CMakeLists.txt、src/ 源码目录、以及 cmake/ 模块目录。其他什么 build/、docs/、tests/ 都平级放，但绝不混进源码里。

我曾经接手过一个项目，所有 .cpp 和 .h 文件堆在一个目录下，足足两千多个文件。那感觉，就像走进一个没有货架的大仓库，找东西全靠运气。所以，模块化是第一步。

my_project/
├── CMakeLists.txt          # 顶层构建文件
├── cmake/                  # 自定义 CMake 模块
│   ├── FindMyLib.cmake
│   └── CompilerSettings.cmake
├── src/                    # 源码
│   ├── CMakeLists.txt
│   ├── core/               # 核心模块
│   ├── network/            # 网络模块
│   └── ui/                 # 界面模块
├── tests/                  # 测试
│   ├── CMakeLists.txt
│   └── test_core.cpp
├── docs/                   # 文档
├── scripts/                # 构建/部署脚本
└── .github/                # CI 配置
    └── workflows/

每个子模块内部，我要求必须有自己的 CMakeLists.txt。这样做的目的很明确：每个模块都可以独立构建和测试。说白了，就是解耦。

2. 模块化构建：用 add_subdirectory 搭积木

模块化构建的核心，就是 add_subdirectory()。但这里有个坑：很多人把整个项目的所有源文件都扔到一个 add_executable() 里，然后靠 add_subdirectory 去包含头文件路径。这其实只是「伪模块化」。

真正的模块化，每个子目录应该生成一个 库目标（静态库或动态库），然后顶层可执行文件只负责链接这些库。

# src/core/CMakeLists.txt
add_library(core
    core_engine.cpp
    data_manager.cpp
)
target_include_directories(core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
target_link_libraries(core PUBLIC fmt::fmt)

# src/CMakeLists.txt
add_subdirectory(core)
add_subdirectory(network)
add_subdirectory(ui)

# 顶层 CMakeLists.txt
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE core network ui)

这样做的好处，我在项目中深有体会：编译速度提升明显。因为每个库可以单独缓存，修改一个模块只需要重新编译那个模块和链接步骤，而不是全量编译。

3. 版本管理：别让版本号成为噩梦

版本管理不只是 Git 的事，CMake 里也要管。我见过最离谱的情况：项目发布后，用户报了个 bug，开发人员花了三天才搞清楚用户用的是哪个版本的代码——因为 CMakeLists.txt 里根本没写版本号。

我的习惯是在顶层 CMakeLists.txt 最前面定义版本：

cmake_minimum_required(VERSION 3.20)
project(MyProject
    VERSION 2.1.0
    DESCRIPTION "A powerful C++ framework"
    LANGUAGES CXX
)

# 版本号可以随处使用
message(STATUS "Building ${PROJECT_NAME} version ${PROJECT_VERSION}")
add_definitions(-DVERSION="${PROJECT_VERSION}")

然后配合 Git 标签，每次发布时打上 v2.1.0 这样的标签。CMake 甚至可以通过 git describe 自动获取版本号，但我建议手动维护，更可控。

4. 持续集成：让机器替你打工

持续集成（CI）说白了就是：每次你 push 代码，服务器自动帮你编译、跑测试、甚至打包发布。我刚开始做项目时，总觉得 CI 是「大公司才用的东西」，直到有一次我合并了一个破坏编译的 PR，整个团队等我修复等了两个小时……从那以后，CI 就成了我的标配。

CMake 在 CI 中的配置其实很简单。以 GitHub Actions 为例：

# .github/workflows/build.yml
name: Build and Test

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure
        run: cmake -B build -DCMAKE_BUILD_TYPE=Release
      - name: Build
        run: cmake --build build --parallel
      - name: Test
        run: ctest --test-dir build --output-on-failure

这里有个小技巧：--parallel 参数会自动利用所有 CPU 核心，编译速度翻倍。我当年不知道这个，每次 CI 跑半小时，后来加了这参数，十分钟搞定。

5. 文档生成：用 Doxygen 自动生成 API 文档

文档这件事，说实话，大部分开发者都不爱写。但用户需要文档，新同事需要文档，甚至三个月后的你自己也需要文档。我的解决方案是：让 CMake 帮你生成文档。

Doxygen 是 C++ 文档生成的事实标准。你只需要在代码里写注释，然后 CMake 调用 Doxygen 就能生成 HTML 或 PDF 文档。

# docs/CMakeLists.txt
find_package(Doxygen REQUIRED)

doxygen_add_docs(docs
    ${PROJECT_SOURCE_DIR}/src
    COMMENT "Generate API documentation"
)

# 让 docs 目标成为构建的一部分
add_dependencies(docs ${PROJECT_NAME})

然后在代码里这样写注释：

/**
 * @brief 计算两个数的和
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两数之和
 */
int add(int a, int b);

运行 cmake --build . --target docs，一份漂亮的 HTML 文档就生成了。我个人习惯把文档生成放在 CI 的最后一个步骤，每次发布新版本时自动更新在线文档。

知识体系总览

下面这张图，是我对本章内容的总结。你可以把它当作一张「大型项目构建路线图」：

避坑指南：我踩过的那些坑

• 不要用 file(GLOB) 收集源文件。我曾经这么干过，结果添加新文件后 CMake 不重新配置，编译一直失败。后来我改成手动列出源文件，虽然麻烦点，但稳定可靠。
• 版本号不要硬编码在代码里。用 CMake 的 project() 定义，然后通过 configure_file() 生成头文件。这样改版本号只需要改一处。
• CI 里不要用 make，用 cmake --build。后者跨平台，Windows 下也能用。我见过有人在 CI 里写死 make -j4，结果换到 Windows runner 上直接报错。
• 文档注释要写，但别写废话。比如 // 这是一个加法函数 这种注释，还不如不写。要写就写清楚参数含义、返回值、异常情况。

好了，这一章的内容就到这里。大型项目的构建管理，说白了就是「把复杂的事情拆简单，把简单的事情自动化」。你按照上面这套方案去搭建，至少能省掉一半的维护精力。