一、大型项目实战：多模块组织、第三方依赖管理、CI/CD中的CMake实践

说实话，很多人在小项目里用CMake用得挺溜的。但一旦项目膨胀到几十个模块、上百个第三方库，就开始手忙脚乱了。我见过不少团队，项目从几千行代码膨胀到几十万行时，CMakeLists.txt也跟着变成了"屎山"。

今天这一章，我就把我在几个大型嵌入式项目里踩过的坑、总结的经验，一次性倒出来给你。嗯，咱们从三个维度来拆解：多模块怎么组织、第三方依赖怎么管、CI/CD里怎么玩。

1. 多模块组织：别让CMakeLists.txt变成"意大利面"

先说说模块化。你想想看，一个大型项目，可能有几十个模块：网络层、协议栈、UI引擎、硬件抽象层……每个模块又分公共接口和内部实现。怎么组织？

我个人习惯用这种目录结构：

project_root/
├── CMakeLists.txt          # 顶层CMake
├── cmake/
│   ├── modules/            # 自定义Find模块
│   └── toolchain/          # 工具链文件
├── modules/
│   ├── core/               # 核心模块
│   │   ├── CMakeLists.txt
│   │   ├── include/
│   │   └── src/
│   ├── network/            # 网络模块
│   │   ├── CMakeLists.txt
│   │   ├── include/
│   │   └── src/
│   └── ui/                 # UI模块
│       ├── CMakeLists.txt
│       ├── include/
│       └── src/
├── third_party/            # 第三方依赖
│   ├── CMakeLists.txt
│   ├── fmt/
│   └── spdlog/
└── tests/                  # 测试
    ├── CMakeLists.txt
    └── unit/

顶层CMakeLists.txt只做三件事：设置全局属性、添加子目录、定义安装规则。千万别把具体编译逻辑塞进去。

我曾经在一个项目里看到有人把几十个include路径写在顶层CMake里，结果改一个路径，整个项目重新编译半小时。嗯，从那以后我立了个规矩：每个模块的include路径只在自己的CMakeLists.txt里定义。

2. 第三方依赖管理：FetchContent vs find_package

第三方库怎么管？这是个大问题。我见过三种主流做法：

方式	适用场景	优点	缺点
find_package	系统已安装的库	无需下载，编译快	版本不可控，依赖环境
FetchContent	小库、头文件库	自动下载，版本锁定	每次都要下载/更新
Git Submodule	大型第三方库	版本精确控制	管理麻烦，容易冲突

我个人现在偏向用FetchContent。为什么？因为它能锁定版本，而且不需要开发者手动安装任何东西。举个例子：

include(FetchContent)

# 锁定版本
set(FMT_VERSION 10.1.1)
set(SPDLOG_VERSION 1.12.0)

FetchContent_Declare(
    fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG ${FMT_VERSION}
    GIT_SHALLOW TRUE
)

FetchContent_Declare(
    spdlog
    GIT_REPOSITORY https://github.com/gabime/spdlog.git
    GIT_TAG ${SPDLOG_VERSION}
    GIT_SHALLOW TRUE
)

FetchContent_MakeAvailable(fmt spdlog)

# 然后直接链接
target_link_libraries(my_app PRIVATE fmt::fmt spdlog::spdlog)

但要注意，FetchContent有个坑：每次cmake --build都会检查更新。如果你在CI里频繁构建，建议加个缓存机制。我一般这样处理：

# 在CI中设置环境变量，跳过更新检查
if(DEFINED ENV{CI})
    set(FETCHCONTENT_UPDATES_DISCONNECTED TRUE)
endif()

3. CI/CD中的CMake实践：从"能编译"到"可靠编译"

CI/CD里CMake怎么玩？说白了就三个字：可复现。你在本地能编译，在CI里也得能编译，而且结果得一样。

我踩过最大的坑是什么？路径硬编码。有一次，一个同事在CMake里写了绝对路径：

# 千万别这么干！
set(THIRD_PARTY_DIR /home/zhangsan/libs)

结果换到CI机器上，直接编译失败。嗯，从那以后我强制团队用相对路径 + 缓存变量：

# 正确的做法
set(THIRD_PARTY_DIR "${CMAKE_SOURCE_DIR}/third_party" CACHE PATH "第三方库路径")

另外，CI里我建议用预设(presets)来管理不同配置。这样开发者只需要敲一行命令：

cmake --preset=ci-debug
cmake --build --preset=ci-debug

预设文件长这样：

{
    "version": 6,
    "configurePresets": [
        {
            "name": "ci-debug",
            "displayName": "CI Debug配置",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build/ci-debug",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Debug",
                "CMAKE_CXX_STANDARD": "17",
                "BUILD_TESTING": "ON",
                "ENABLE_COVERAGE": "ON"
            }
        },
        {
            "name": "ci-release",
            "displayName": "CI Release配置",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/build/ci-release",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Release",
                "CMAKE_CXX_STANDARD": "17",
                "BUILD_TESTING": "OFF"
            }
        }
    ],
    "buildPresets": [
        {
            "name": "ci-debug",
            "configurePreset": "ci-debug"
        },
        {
            "name": "ci-release",
            "configurePreset": "ci-release"
        }
    ]
}

4. 实战中的避坑指南

最后，分享几个我这些年总结的"血泪教训"：

• 不要用add_subdirectory嵌套太深。超过3层，依赖关系就乱成一锅粥了。我一般控制在2层以内。
• 慎用INTERFACE库。它虽然方便，但调试起来很痛苦。我建议只在纯头文件库时用。
• CI里一定要跑cmake --build --clean-first。别问我为什么，有一次缓存坏了，CI一直用旧版本编译，上线才发现问题。
• 版本号统一管理。我习惯在顶层CMake里定义版本号，然后通过target_compile_definitions传给所有模块：

# 顶层CMakeLists.txt
project(MyProject VERSION 2.5.1)

# 所有模块都能用
target_compile_definitions(my_app PRIVATE
    PROJECT_VERSION="${PROJECT_VERSION}"
    PROJECT_VERSION_MAJOR=${PROJECT_VERSION_MAJOR}
    PROJECT_VERSION_MINOR=${PROJECT_VERSION_MINOR}
)

好了，这一章的内容就到这里。多模块组织、第三方依赖管理、CI/CD实践，这三块是大型项目的"三座大山"。翻过它们，你的CMake水平就真正上了一个台阶。

---

公众号：蓝海资料掘金营，微信 deep3321