如何使用CMake的FetchContent模块管理c++项目的源码依赖？ (现代CMake)_技术教程

FetchContent_Declare仅声明依赖，必须调用FetchContent_MakeAvailable才能下载、配置并生成target；未调用则target_link_libraries会因找不到target而失败。

FetchContent_Declare 之后必须调用 FetchContent_MakeAvailable 才能真正拉取和配置依赖

很多人写完 FetchContent_Declare 就以为依赖已就绪，结果 target_link_libraries 报错说找不到 target —— 因为 FetchContent_Declare 只是注册一个声明，不触发下载、解压或 add_subdirectory。真正让内容“可用”的是 FetchContent_MakeAvailable，它会按需执行完整流程。

常见错误写法：

FetchContent_Declare(
  fmt
  GIT_REPOSITORY https://github.com/fmtlib/fmt.git
  GIT_TAG 10.2.1
)
# ❌ 缺少 MakeAvailable，fmt::fmt 还不存在
target_link_libraries(myapp PRIVATE fmt::fmt)

正确顺序：

FetchContent_Declare(
  fmt
  GIT_REPOSITORY https://github.com/fmtlib/fmt.git
  GIT_TAG 10.2.1
)
FetchContent_MakeAvailable(fmt)  # ✅ 必须加这行
target_link_libraries(myapp PRIVATE fmt::fmt)

声明和可用之间可以插入其他逻辑（比如检查变量、设置选项），但 MakeAvailable 必须在首次引用其 targets 前调用
多次调用 MakeAvailable 对同一名称是安全的（CMake 内部会跳过重复操作）
如果依赖本身没有导出 install 或 export targets（如纯头文件库且没写 install(EXPORT ...)），MakeAvailable 仍能通过 add_subdirectory 拉起它的 CMakeLists.txt，生成内部 target

用 GIT_SHALLOW 和 FETCHCONTENT_FULLY_DISCONNECTED 减少 CI 构建时间

默认情况下，FetchContent 会克隆完整 Git 历史，对大型仓库（如 LLVM、Boost）非常慢。CI 环境尤其敏感——每次 clean 构建都重拉一遍。

提速关键参数：

GIT_SHALLOW TRUE：只拉最新 commit，跳过历史（注意：某些项目在 configure 阶段读 .git 提取版本号，此时会失败）
FETCHCONTENT_FULLY_DISCONNECTED ON：禁止联网（包括 git fetch / submodule update），强制使用本地缓存；适合离线构建或锁定依赖快照
搭配 FETCHCONTENT_BASE_DIR 指向共享缓存目录（如 /tmp/cmake-fetch-cache），避免多个项目重复拉取

示例（兼顾速度与可重现性）：

set(FETCHCONTENT_BASE_DIR "${CMAKE_BINARY_DIR}/_deps")
set(FETCHCONTENT_FULLY_DISCONNECTED OFF)
FetchContent_Declare(
  spdlog
  GIT_REPOSITORY https://github.com/gabime/spdlog.git
  GIT_TAG v1.14.1
  GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(spdlog)

覆盖子项目的 CMake 变量（如 BUILD_TESTS、SPDLOG_FMT_EXTERNAL）要趁早

很多第三方库提供 CMake 选项控制构建行为（例如是否编译测试、是否链接外部 fmt）。这些变量必须在 FetchContent_MakeAvailable **之前** 设置，否则会被子项目 CMakeLists.txt 的默认值覆盖。

原因：MakeAvailable 内部实际执行的是 add_subdirectory，而子项目的 option() / set(.

.. CACHE) 在第一次 project() 或 cmake_minimum_required() 后立即求值。

✅ 正确：在 Declare 后、MakeAvailable 前，用 set(... CACHE) 或 set(... FORCE) 预设
❌ 错误：在 MakeAvailable 之后再 set，已无效

以 spdlog 为例（它默认开启测试并捆绑 fmt）：

FetchContent_Declare(spdlog GIT_REPOSITORY https://github.com/gabime/spdlog.git GIT_TAG v1.14.1)
✅ 必须在这一步设置，影响后续 add_subdirectory
set(SPDLOG_BUILD_TESTS OFF CACHE BOOL "")
set(SPDLOG_FMT_EXTERNAL ON CACHE BOOL "")
FetchContent_MakeAvailable(spdlog)

FetchContent 不适合替代包管理器处理系统级依赖或 ABI 兼容性问题

FetchContent 是源码内联方案，不是包管理器。它无法解决以下真实工程问题：

不同项目共用同一份 fmt 库时，若各自拉取不同 Git TAG，会导致 ODR 违规（One Definition Rule）——符号冲突、RTTI 失败、dynamic_cast 崩溃
无法跨工具链复用（比如 Windows 上用 MSVC 编译的 spdlog 不能直接给 MinGW 链接）
没有依赖传递解析：A 依赖 B，B 依赖 C，FetchContent 不自动拉 C，得手动声明
调试信息路径硬编码进二进制，多项目嵌套后 step into 可能跳转到错误副本

所以，中大型项目建议分层：