鸭梨公共文档

主题

vcpkg 入门指南 ​

vcpkg 是 Microsoft 开发的跨平台 C++ 包管理器，用于简化 C++ 库的获取和管理。本文档将带您从零开始了解如何安装和使用 vcpkg。

什么是 vcpkg ​

vcpkg 是一个免费的开源包管理器，专为 C++ 库设计。它提供了：

  • 跨平台支持：支持 Windows、Linux 和 macOS
  • 大量库支持：包含超过 2000 个经过验证的开源库
  • 简单易用：通过命令行轻松管理依赖项
  • 工具链集成：与 Visual Studio、VS Code 和 CMake 无缝集成

先决条件 ​

在开始之前，请确保您的系统已安装以下工具：

  • 终端（命令行界面）
  • C++ 编译器
    • Windows：Visual Studio 的 MSVC
    • Linux：GCC 或 Clang
    • macOS：Xcode 命令行工具
  • CMake：用于构建项目
  • Git：用于克隆 vcpkg 仓库

1. 安装 vcpkg ​

1.1 克隆 vcpkg 仓库 ​

首先从 GitHub 克隆 vcpkg 仓库：

bash
git clone https://github.com/microsoft/vcpkg.git

1.2 运行引导脚本 ​

进入 vcpkg 目录并运行引导脚本：

Windows (CMD/PowerShell):

cmd
cd vcpkg
.\bootstrap-vcpkg.bat

Linux/macOS:

bash
cd vcpkg
./bootstrap-vcpkg.sh

引导脚本会执行先决条件检查并下载 vcpkg 可执行文件。

1.3 配置环境变量 ​

为了方便使用，建议配置环境变量：

Windows (PowerShell):

powershell
$env:VCPKG_ROOT = "C:\path\to\vcpkg"
$env:PATH = "$env:VCPKG_ROOT;$env:PATH"

Linux/macOS (Bash):

bash
export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH

💡 提示：为了让环境变量永久生效，请将其添加到系统环境变量中。

2. 创建项目 ​

2.1 创建项目目录 ​

bash
mkdir helloworld && cd helloworld

2.2 初始化 vcpkg 清单 ​

使用 vcpkg 命令创建清单文件：

bash
vcpkg new --application

这会在项目目录中创建 vcpkg.json 和 vcpkg-configuration.json 文件。

3. 添加依赖项 ​

3.1 添加库依赖 ​

以 fmt 库为例，添加依赖项：

bash
vcpkg add port fmt

此时 vcpkg.json 文件内容如下：

json
{
    "dependencies": [
        "fmt"
    ]
}

3.2 创建 CMakeLists.txt ​

创建 CMakeLists.txt 文件：

cmake
cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)

CMakeLists.txt 文件解析：

  • cmake_minimum_required(VERSION 3.10)：指定最低 CMake 版本
  • project(HelloWorld)：设置项目名称
  • find_package(fmt CONFIG REQUIRED)：查找 fmt 库
  • add_executable(HelloWorld helloworld.cpp)：创建可执行文件
  • target_link_libraries(HelloWorld PRIVATE fmt::fmt)：链接 fmt 库

3.3 创建源码文件 ​

创建 helloworld.cpp 文件：

cpp
#include <fmt/core.h>

int main()
{
    fmt::print("Hello World!\n");
    return 0;
}

4. 构建和运行项目 ​

4.1 配置 CMake 预设 ​

创建 CMakePresets.json 文件：

json
{
  "version": 2,
  "configurePresets": [
    {
      "name": "vcpkg",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

创建 CMakeUserPresets.json 文件：

json
{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "vcpkg",
      "environment": {
        "VCPKG_ROOT": "<path to vcpkg>"
      }
    }
  ]
}

⚠️ 注意：将 <path to vcpkg> 替换为您的 vcpkg 安装路径。

4.2 配置项目 ​

bash
cmake --preset=default

4.3 构建项目 ​

bash
cmake --build build

4.4 运行程序 ​

Windows:

cmd
.\build\HelloWorld.exe

Linux/macOS:

bash
./build/HelloWorld

输出结果：

text
Hello World!

5. 常用 vcpkg 命令 ​

5.1 搜索包 ​

bash
vcpkg search <package-name>

5.2 安装包（经典模式） ​

bash
vcpkg install <package-name>

5.3 列出已安装的包 ​

bash
vcpkg list

5.4 移除包 ​

bash
vcpkg remove <package-name>

5.5 更新所有包 ​

bash
vcpkg upgrade

6. 清单模式 vs 经典模式 ​

6.1 清单模式（推荐） ​

  • 使用 vcpkg.json 文件管理依赖项
  • 项目级别的依赖管理
  • 更好的版本控制支持
  • 适合团队协作

6.2 经典模式 ​

  • 全局安装包
  • 系统级别的包管理
  • 适合快速原型开发

7. 与 IDE 集成 ​

7.1 Visual Studio ​

vcpkg 与 Visual Studio 有原生集成支持：

bash
vcpkg integrate install

7.2 VS Code ​

安装 CMake Tools 扩展，并在 settings.json 中配置：

json
{
    "cmake.configureSettings": {
        "CMAKE_TOOLCHAIN_FILE": "${env:VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
    }
}

8. 最佳实践 ​

8.1 版本管理 ​

  • 将 vcpkg.json 和 vcpkg-configuration.json 添加到版本控制
  • 不要提交 CMakeUserPresets.json（包含本地路径）

8.2 依赖项管理 ​

  • 优先使用清单模式
  • 定期更新依赖项版本
  • 使用版本约束确保兼容性

8.3 团队协作 ​

  • 统一 vcpkg 版本
  • 共享 CMake 预设配置
  • 文档化依赖项选择理由

9. 常见问题 ​

9.1 编译器找不到包 ​

确保正确设置了 CMAKE_TOOLCHAIN_FILE：

cmake
set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake")

9.2 包安装失败 ​

检查：

  • 网络连接
  • 编译器配置
  • 磁盘空间

9.3 版本冲突 ​

使用 vcpkg-configuration.json 指定版本约束：

json
{
  "registries": [
    {
      "kind": "git",
      "baseline": "baseline-commit-hash",
      "repository": "https://github.com/Microsoft/vcpkg"
    }
  ]
}

10. 进阶用法 ​

10.1 自定义端口 ​

创建自定义包：

bash
vcpkg create <package-name> <source-url>

10.2 覆盖端口 ​

在项目中创建 ports 目录，添加自定义端口定义。

10.3 私有注册表 ​

配置私有包注册表：

json
{
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/your-org/your-registry",
      "packages": ["your-package"]
    }
  ]
}

总结 ​

vcpkg 是一个强大而易用的 C++ 包管理器，通过本指南您应该能够：

  1. ✅ 安装和配置 vcpkg
  2. ✅ 创建使用外部库的 C++ 项目
  3. ✅ 理解清单模式和经典模式的区别
  4. ✅ 与各种 IDE 和构建系统集成
  5. ✅ 解决常见问题

参考资源 ​