12、自定义下载逻辑：使用PATCH_COMMAND打补丁、使用UPDATE_DISCONNECTED优化、自定义CONFIGURE_COMMAND

说实话，FetchContent 用顺手之后，你会发现它确实方便。但项目一复杂，问题就来了——依赖的源码下载下来，不一定能直接用。要么需要改几行代码，要么每次构建都重新拉取一遍，浪费时间。今天我就聊聊怎么自定义这些下载逻辑，让 FetchContent 真正为你所用。

12.1 为什么需要自定义下载逻辑？

默认情况下，FetchContent 做的事情很简单：下载源码、配置、构建。但现实世界哪有那么完美？

• 源码需要打补丁：有些第三方库有小 bug，或者需要适配你的项目。你不能等上游修复，得自己动手。
• 重复下载太慢：每次构建都重新拉取？我遇到过一个大项目，依赖十几个库，每次构建光下载就要等 5 分钟。这谁受得了？
• 配置方式不同：有些库不用 CMake，或者需要特殊的配置参数。默认的 configure 步骤根本走不通。

说白了，FetchContent 给了你一套默认流程，但也留了后门——你可以随时插手，替换掉其中任何一步。

12.2 PATCH_COMMAND：给源码打补丁

先说说最常见的需求——打补丁。我记得有一次，项目依赖了一个老版本的 libcurl，有个安全漏洞需要修复。但那个版本已经停止维护了，怎么办？自己打补丁呗。

FetchContent 提供了 PATCH_COMMAND 选项，让你在源码下载完成后、配置开始前，执行任意命令。通常我们用 patch 工具来应用 .patch 文件。

FetchContent_Declare(
  mylib
  GIT_REPOSITORY https://github.com/example/mylib.git
  GIT_TAG v1.2.3
  PATCH_COMMAND patch -p1 < ${CMAKE_CURRENT_SOURCE_DIR}/patches/fix-bug.patch
)

FetchContent_MakeAvailable(mylib)

这里有几个要点：

• patch -p1 是标准用法，-p1 表示跳过路径中的第一级目录（通常是仓库名）。
• 补丁文件路径建议用绝对路径，或者基于 CMAKE_CURRENT_SOURCE_DIR 构造，避免路径问题。
• 如果补丁文件不存在，构建会直接报错。所以记得把补丁文件提交到你的版本控制里。

12.3 UPDATE_DISCONNECTED：别再重复下载了

这个选项是我最喜欢的优化之一。默认情况下，每次 CMake 重新运行，FetchContent 都会检查依赖是否有更新。如果是 Git 仓库，它会执行 git fetch 或 git pull。这听起来没什么，但如果你有十几个依赖，每次构建都联网检查一遍，那叫一个慢。

UPDATE_DISCONNECTED 的作用就是告诉 FetchContent：「别联网了，用本地已有的源码就行。」

FetchContent_Declare(
  mylib
  GIT_REPOSITORY https://github.com/example/mylib.git
  GIT_TAG v1.2.3
  UPDATE_DISCONNECTED ON
)

FetchContent_MakeAvailable(mylib)

设置成 ON 之后，只要源码已经下载到本地，FetchContent 就不会再尝试更新。构建速度能快不少。

我曾经在一个 CI 环境里吃过这个亏——改了依赖版本号，但构建一直用旧代码。排查了半天才发现是 UPDATE_DISCONNECTED 在「捣乱」。嗯，这里要注意：调试阶段可以关掉它，稳定了再打开。

12.4 自定义 CONFIGURE_COMMAND：不走寻常路

有些库不是用 CMake 构建的。比如一些老旧的 C 库，用的是 autotools 或者手写的 Makefile。这时候 FetchContent 默认的 configure 步骤（调用 CMake）就失效了。

解决办法？用 CONFIGURE_COMMAND 替换掉默认的配置命令。你可以指定任何可执行文件或脚本。

FetchContent_Declare(
  mylib
  GIT_REPOSITORY https://github.com/example/mylib.git
  GIT_TAG v1.2.3
  CONFIGURE_COMMAND ./configure --prefix=${CMAKE_BINARY_DIR}/install
)

FetchContent_MakeAvailable(mylib)

这里有几个坑，我帮你踩过了：

• 工作目录：CONFIGURE_COMMAND 默认在源码根目录执行。如果你的脚本在子目录里，记得用 cd 切换。
• 跨平台问题：Windows 上没有 ./configure。你需要用条件判断来区分平台。
• 输出目录：如果库需要安装到特定位置，记得指定 --prefix 或类似选项，否则后续的 build 步骤可能找不到文件。

12.5 知识体系总览

下面这张图展示了自定义下载逻辑的核心流程。你可以看到，默认流程和自定义流程的区别就在于那几个「钩子」位置。

从图中可以清楚看到：默认流程只有 4 步，而自定义流程在「下载」和「配置」之间插入了打补丁步骤，并且替换了配置命令。再加上 UPDATE_DISCONNECTED 这个「加速器」，整个流程就灵活多了。

12.6 综合示例：一个完整的自定义流程

最后，我给你一个完整的例子。假设我们要集成一个叫 legacy_lib 的库，它用 autotools 构建，而且需要打一个补丁。同时我们不想每次构建都重新下载。

# 先定义补丁命令
set(PATCH_CMD
    ${CMAKE_COMMAND} -E echo "Applying patch..."
    && patch -p1 < ${CMAKE_CURRENT_SOURCE_DIR}/patches/legacy_lib_fix.patch
)

# 定义配置命令（autotools 风格）
set(CONFIGURE_CMD
    cd ${legacy_lib_SOURCE_DIR}
    && ./configure --prefix=${CMAKE_BINARY_DIR}/install_legacy
)

FetchContent_Declare(
  legacy_lib
  GIT_REPOSITORY https://github.com/example/legacy_lib.git
  GIT_TAG v2.0.1
  PATCH_COMMAND ${PATCH_CMD}
  CONFIGURE_COMMAND ${CONFIGURE_CMD}
  UPDATE_DISCONNECTED ON
)

FetchContent_MakeAvailable(legacy_lib)

好了，这一章的内容就到这里。自定义下载逻辑其实不复杂，关键是要知道 FetchContent 给了你哪些「钩子」。用好了，你的项目构建会又快又稳。

---