C / C++ / 系统课时

用 FetchContent 拉取源码依赖

用 FetchContent 拉取源码依赖

当项目希望在配置阶段自动取得某个源码依赖,并把它作为当前构建的一部分时,可以使用 CMake 的 FetchContent。它能减少人工下载步骤,但网络访问也进入了构建流程,因此必须固定依赖版本并认真考虑 CI、缓存和离线构建。

学习目标

  • 使用 FetchContent_Declare 和 FetchContent_MakeAvailable 引入源码依赖
  • 理解被拉取项目如何变成当前工程可链接的 CMake 目标
  • 掌握版本固定、网络依赖和可重复构建的关键边界

FetchContent 解决什么问题

传统做法可能要求开发者先下载第三方源码,再约定一个本地目录供 add_subdirectory 使用。FetchContent 把“依赖从哪里来”也写进 CMake 配置:项目声明仓库和版本,配置时由 CMake 获取源码,并在依赖自身支持 CMake 的情况下把它加入当前构建。

它适合需要随项目源码一起构建、并希望统一第三方版本的依赖。已经由操作系统或 SDK 稳定提供的库,则往往更适合通过 find_package 使用,不必重复下载和编译。

声明和引入是两个阶段

FetchContent_Declare 只记录依赖的获取规则;FetchContent_MakeAvailable 才会确保内容可用,并在适用时把依赖的 CMake 项目加入当前构建。随后,主项目应继续通过依赖定义的目标建立关系,而不是进入下载目录手工寻找生成的库文件。

这种方式把“获取源码”和“消费目标”分开。即使依赖存放位置发生变化,只要它暴露的目标名称不变,调用方通常不需要修改头文件目录和链接路径。

拉取 cJSON 并链接到 C 程序

下面使用 cJSON 演示完整流程。版本固定为标签 v1.7.18,避免每次配置都跟随远端分支变化。将以下两个文件放在同一目录。

cmake
cmake_minimum_required(VERSION 3.24)
project(fetch_cjson C)

include(FetchContent)

FetchContent_Declare(
    cjson
    GIT_REPOSITORY https://github.com/DaveGamble/cJSON.git
    GIT_TAG v1.7.18
    GIT_SHALLOW TRUE
)

FetchContent_MakeAvailable(cjson)

add_executable(app main.c)
target_link_libraries(app PRIVATE cjson)

这里的 cjson 目标由被拉取项目自身定义。主项目只消费这个目标,因此其源码目录、编译选项和最终库文件位置无需由调用方硬编码。

c
#include <stdio.h>
#include "cJSON.h"

int main(void) {
    cJSON *root = cJSON_CreateObject();
    if (root == NULL) {
        return 1;
    }

    /* 任何创建失败都先释放已经成功创建的 JSON 对象。 */
    if (cJSON_AddStringToObject(root, "name", "anystack") == NULL) {
        cJSON_Delete(root);
        return 1;
    }

    char *text = cJSON_PrintUnformatted(root);
    if (text == NULL) {
        cJSON_Delete(root);
        return 1;
    }

    puts(text);
    cJSON_free(text);
    cJSON_Delete(root);
    return 0;
}

首次配置需要能够访问声明的 Git 仓库。以下命令以 Linux/macOS 的单配置构建目录为例:

bash
cmake -S . -B build
cmake --build build
./build/app

预期输出

text
{"name":"anystack"}

配置和构建日志会随 CMake 版本、生成器和编译器变化;程序最后输出上述 JSON,即可验证 cJSON 已参与构建并被 app 正确链接。

固定版本才能获得可重复构建

不要把长期使用的依赖固定在 main、master 或其他持续变化的分支上。远端分支今天和下周可能指向不同提交,同一份项目源码因此可能得到不同依赖代码。

固定发布标签比跟随分支稳定;对可重复性要求更高时,可以固定具体提交哈希。需要注意,Git 的浅克隆并不适合所有提交哈希场景,因此若把 GIT_TAG 改成任意提交哈希,应同时重新评估是否继续使用 GIT_SHALLOW TRUE。

把网络失败和源码失败分开判断

FetchContent 的常见故障有两层:源码没有成功取得,以及源码已经取得但依赖自身配置或编译失败。前者重点检查 Git、代理、证书、仓库地址和标签;后者应直接阅读被拉取项目产生的 CMake 或编译错误。

CI 环境中尤其不要默认“公网永远可用”。可以通过依赖缓存、内部镜像或预先准备源码降低外部网络波动的影响。FetchContent 带来的便利是自动获取和加入构建,而不是消除版本管理与供应链管理责任。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 FetchContent 拉取源码依赖

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通