第 15 章：依赖管理

15.1 依赖管理方式概览

方式	使用场景	优点	缺点
`find_package`	系统已安装的库	简单、标准	需预先安装
`FetchContent`	CMake 项目依赖	自动下载、无缝集成	配置时下载、CMake 专属
`ExternalProject`	外部构建的项目	灵活、支持非 CMake	构建时下载、复杂
vcpkg	C/C++ 包管理	跨平台、微软维护	需额外安装
Conan	C/C++ 包管理	版本锁定、二进制缓存	学习曲线

15.2 FetchContent

15.2.1 基本用法

include(FetchContent)

FetchContent_Declare(
    fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG 10.2.1
)

FetchContent_MakeAvailable(fmt)

# 直接使用目标
add_executable(app main.cpp)
target_link_libraries(app PRIVATE fmt::fmt)

15.2.2 FetchContent 声明方式

# Git 仓库
FetchContent_Declare(mylib
    GIT_REPOSITORY https://github.com/example/mylib.git
    GIT_TAG v2.0.0
    GIT_SHALLOW TRUE           # 浅克隆
    GIT_SUBMODULES ""          # 不拉取子模块
)

# Git 分支
FetchContent_Declare(mylib
    GIT_REPOSITORY https://github.com/example/mylib.git
    GIT_TAG main
    GIT_PROGRESS TRUE
)

# URL 下载
FetchContent_Declare(mylib
    URL https://github.com/example/mylib/archive/v2.0.0.tar.gz
    URL_HASH SHA256=abc123def456...
)

# URL 自动检测哈希
FetchContent_Declare(mylib
    URL https://github.com/example/mylib/archive/v2.0.0.tar.gz
    URL_HASH AUTO
)

# 本地路径（开发模式）
FetchContent_Declare(mylib
    SOURCE_DIR /home/user/dev/mylib
)

15.2.3 FetchContent 属性

属性	说明
`GIT_REPOSITORY`	Git 仓库 URL
`GIT_TAG`	Git 标签/分支/提交
`GIT_SHALLOW`	浅克隆
`GIT_SUBMODULES`	子模块列表
`GIT_PROGRESS`	显示进度
`URL`	下载 URL
`URL_HASH`	文件哈希
`SOURCE_DIR`	本地源码目录
`PATCH_COMMAND`	打补丁命令
`FIND_PACKAGE_ARGS`	先尝试 find_package（CMake 3.24+）
`SYSTEM`	标记为系统头文件（CMake 3.25+）

15.2.4 控制行为

# 先尝试 find_package，找不到再下载
FetchContent_Declare(fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG 10.2.1
    FIND_PACKAGE_ARGS
)
FetchContent_MakeAvailable(fmt)
# 等价于：先 find_package(fmt)，失败才 FetchContent

# 先尝试 find_package 并指定版本
FetchContent_Declare(fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG 10.2.1
    FIND_PACKAGE_ARGS 10.0
)

15.2.5 仅声明不立即使用

FetchContent_Declare(fmt ...)
FetchContent_Declare(spdlog ...)

# 延迟获取
FetchContent_GetProperties(fmt)
if(NOT fmt_POPULATED)
    FetchContent_Populate(fmt)
    add_subdirectory(${fmt_SOURCE_DIR} ${fmt_BINARY_DIR})
endif()

# 或者批量获取
FetchContent_MakeAvailable(fmt spdlog)

15.2.6 SYSTEM 头文件（CMake 3.25+）

# 将 FetchContent 的依赖标记为系统头文件，避免警告
FetchContent_Declare(fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG 10.2.1
    SYSTEM                       # 新特性
)

15.3 ExternalProject

15.3.1 基本用法

include(ExternalProject)

ExternalProject_Add(
    my_external
    GIT_REPOSITORY https://github.com/example/somelib.git
    GIT_TAG v1.0.0
    CMAKE_ARGS
        -DCMAKE_INSTALL_PREFIX=${CMAKE_BINARY_DIR}/external
        -DCMAKE_BUILD_TYPE=Release
    BUILD_COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config Release
    INSTALL_COMMAND ${CMAKE_COMMAND} --install <BINARY_DIR>
)

15.3.2 ExternalProject 与 FetchContent 区别

特性	FetchContent	ExternalProject
执行时机	配置时	构建时
集成方式	`add_subdirectory`	独立构建
目标访问	可直接链接目标	需手动链接
使用场景	CMake 项目依赖	任何项目依赖
性能	配置时下载	构建时下载

15.3.3 使用 ExternalProject 查找已安装的库

include(ExternalProject)

ExternalProject_Add(
    zlib_ext
    URL https://zlib.net/zlib-1.3.1.tar.gz
    URL_HASH SHA256=...
    CMAKE_ARGS
        -DCMAKE_INSTALL_PREFIX=${CMAKE_BINARY_DIR}/deps
        -DCMAKE_BUILD_TYPE=Release
)

# 创建导入目标
add_library(ZLIB::ZLIB SHARED IMPORTED)
set_target_properties(ZLIB::ZLIB PROPERTIES
    IMPORTED_LOCATION ${CMAKE_BINARY_DIR}/deps/lib/libz.so
    INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_BINARY_DIR}/deps/include
)
add_dependencies(ZLIB::ZLIB zlib_ext)

15.4 vcpkg

15.4.1 安装 vcpkg

# 克隆
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh

# 设置环境变量
export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH

15.4.2 vcpkg.json 配置

{
    "name": "myproject",
    "version": "1.0.0",
    "dependencies": [
        "fmt",
        "spdlog",
        {
            "name": "openssl",
            "version>=": "3.0.0"
        },
        {
            "name": "boost",
            "features": ["filesystem", "system", "thread"]
        }
    ],
    "builtin-baseline": "a42af01b72c28a8e1d7b48107b33e4f286a55ef6"
}

15.4.3 使用 vcpkg 工具链

# 命令行方式
cmake -S . -B build \
    -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

# CMakePresets.json 方式
{
    "version": 6,
    "configurePresets": [
        {
            "name": "vcpkg",
            "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Release"
            }
        }
    ]
}

15.4.4 vcpkg 常用命令

# 安装包
vcpkg install fmt
vcpkg install spdlog:x64-linux

# 查找包
vcpkg search openssl

# 列出已安装
vcpkg list

# 版本管理
vcpkg x-update-ports   # 更新 ports
vcpkg x-update-baseline # 更新 baseline

15.4.5 自定义端口

custom-ports/
└── mylib/
    ├── portfile.cmake
    └── vcpkg.json

{
    "name": "mylib",
    "version": "2.0.0",
    "dependencies": []
}

# portfile.cmake
vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO example/mylib
    REF v2.0.0
    SHA512 ...
)

vcpkg_cmake_configure(SOURCE_PATH ${SOURCE_PATH})
vcpkg_cmake_install()
vcpkg_cmake_config_fixup()

15.5 Conan

15.5.1 安装 Conan

pip install conan

# 创建默认配置
conan profile detect

15.5.2 conanfile.txt

[requires]
fmt/10.2.1
spdlog/1.13.0
openssl/3.2.1

[generators]
CMakeDeps
CMakeToolchain

[layout]
cmake_layout

15.5.3 conanfile.py

from conan import ConanFile
from conan.tools.cmake import cmake_layout

class MyProjectConan(ConanFile):
    name = "myproject"
    version = "1.0.0"
    settings = "os", "compiler", "build_type", "arch"
    
    requires = (
        "fmt/10.2.1",
        "spdlog/1.13.0",
    )
    
    generators = "CMakeDeps", "CMakeToolchain"
    
    def layout(self):
        cmake_layout(self)
    
    def configure(self):
        if self.settings.os == "Linux":
            self.options["spdlog"].shared = True

15.5.4 使用 Conan

# 安装依赖
conan install . --build=missing

# 使用生成的工具链
cmake -S . -B build \
    -DCMAKE_TOOLCHAIN_FILE=build/Release/generators/conan_toolchain.cmake \
    -DCMAKE_BUILD_TYPE=Release

# 或使用 CMakePresets.json
# Conan 会生成 CMakeUserPresets.json
cmake --preset conan-release

15.5.5 Conan 的 CMakePresets 集成

# Conan 2 自动生成 CMakeUserPresets.json
conan install . --output-folder=build --build=missing

# 直接使用预设
cmake --preset default

15.5.6 vcpkg vs Conan 对比

特性	vcpkg	Conan
开发者	Microsoft	JFrog
配置文件	vcpkg.json	conanfile.txt/py
CMake 集成	工具链文件	生成器/预设
版本管理	baseline + port 版本	recipe 版本
二进制缓存	vcpkg binary caching	Conan binary cache
包仓库	vcpkg registry	ConanCenter
自定义包	Custom ports	Local recipes
学习曲线	较低	中等
社区包数	2000+	1500+

15.6 混合策略

15.6.1 查找优先级

# 优先级：系统包 > vcpkg/Conan > FetchContent

# 1. 先尝试系统查找
find_package(fmt QUIET)

# 2. 再尝试 vcpkg/Conan（通过 CMAKE_PREFIX_PATH）
if(NOT fmt_FOUND)
    find_package(fmt CONFIG QUIET)
endif()

# 3. 最后使用 FetchContent
if(NOT fmt_FOUND)
    include(FetchContent)
    FetchContent_Declare(fmt
        GIT_REPOSITORY https://github.com/fmtlib/fmt.git
        GIT_TAG 10.2.1
    )
    FetchContent_MakeAvailable(fmt)
endif()

# 或使用 CMake 3.24+ 的 FIND_PACKAGE_ARGS
FetchContent_Declare(fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG 10.2.1
    FIND_PACKAGE_ARGS
)
FetchContent_MakeAvailable(fmt)

15.6.2 选项控制

option(USE_SYSTEM_FMT "使用系统 fmt 库" OFF)
option(USE_VCPKG "使用 vcpkg 管理依赖" OFF)

if(USE_SYSTEM_FMT)
    find_package(fmt REQUIRED)
elseif(USE_VCPKG)
    # vcpkg 工具链会自动处理
    find_package(fmt REQUIRED)
else()
    include(FetchContent)
    FetchContent_Declare(fmt
        GIT_REPOSITORY https://github.com/fmtlib/fmt.git
        GIT_TAG 10.2.1
    )
    FetchContent_MakeAvailable(fmt)
endif()

15.7 业务场景

场景：选择依赖管理策略

项目规模评估
├── 小型项目（< 5 个依赖）
│   └── 推荐：FetchContent（最简单）
├── 中型项目（5-20 个依赖）
│   └── 推荐：vcpkg 或 Conan
├── 大型项目（> 20 个依赖）
│   └── 推荐：Conan + 私有仓库
└── 跨团队共享
    └── 推荐：vcpkg + 自定义注册表

场景：CI 中的依赖管理

# GitHub Actions 示例
# .github/workflows/build.yml
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      
      # vcpkg 方式
      - name: Setup vcpkg
        uses: lukka/run-vcpkg@v11
        with:
          vcpkgGitCommitId: 'a42af01b72c28a8e1d7b48107b33e4f286a55ef6'
      
      - name: Configure
        run: cmake --preset vcpkg
      
      - name: Build
        run: cmake --build --preset vcpkg

15.8 注意事项

问题	说明
FetchContent 配置时间	大量依赖会增加配置时间
版本锁定	使用 tag 或 hash 锁定版本
缓存利用	vcpkg 和 Conan 支持二进制缓存
网络问题	CI 环境可能需要代理或离线模式
依赖冲突	不同依赖可能需要同一库的不同版本

15.9 扩展阅读

上一章：第 14 章 — 模块系统 | 下一章：第 16 章 — Docker 与 CI/CD →

强曰为道

第 15 章：依赖管理

第 15 章：依赖管理

15.1 依赖管理方式概览

15.2 FetchContent

15.2.1 基本用法

15.2.2 FetchContent 声明方式

15.2.3 FetchContent 属性

15.2.4 控制行为

15.2.5 仅声明不立即使用

15.2.6 SYSTEM 头文件（CMake 3.25+）

15.3 ExternalProject

15.3.1 基本用法

15.3.2 ExternalProject 与 FetchContent 区别

15.3.3 使用 ExternalProject 查找已安装的库

15.4 vcpkg

15.4.1 安装 vcpkg

15.4.2 vcpkg.json 配置

15.4.3 使用 vcpkg 工具链

15.4.4 vcpkg 常用命令

15.4.5 自定义端口

15.5 Conan

15.5.1 安装 Conan

15.5.2 conanfile.txt

15.5.3 conanfile.py

15.5.4 使用 Conan

15.5.5 Conan 的 CMakePresets 集成

15.5.6 vcpkg vs Conan 对比

15.6 混合策略

15.6.1 查找优先级

15.6.2 选项控制

15.7 业务场景

场景：选择依赖管理策略

场景：CI 中的依赖管理

15.8 注意事项

15.9 扩展阅读