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 构建都重拉一遍。
立即学习“C++免费学习笔记（深入）”；
提速关键参数：
-
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) <h1>✅ 必须在这一步设置，影响后续 add_subdirectory</h1><p>set(SPDLOG_BUILD_TESTS OFF CACHE BOOL "") set(SPDLOG_FMT_EXTERNAL ON CACHE BOOL "")</p><p>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可能跳转到错误副本
所以，中大型项目建议分层：
- 基础通用库（fmt、range-v3、expected-lite）→ 用
vcpkg/conan统一安装 +find_package - 专用/私有/快速迭代模块 → 用
FetchContent内联，便于 patch 和调试
最易被忽略的一点：一旦用了 FetchContent，你就承担了维护该依赖构建兼容性的责任——比如 CMake 版本升级后子项目 CMakeLists.txt 报错，你得进去修，而不是换一个 package manager 配置。
