vcpkg：C++ 包管理器安装与使用指南

06-01 1422阅读

vcpkg：C++ 包管理器安装与使用指南

1. 简介

vcpkg 是微软开发的一款跨平台的 C++ 包管理器，旨在简化 C++ 库的获取、构建和集成过程。它支持 Windows、Linux 和 macOS，并能与 CMake、MSBuild 等构建系统无缝集成。

使用 vcpkg 的主要优势：

优势说明
简化依赖管理自动处理库的下载、编译和安装
跨平台支持在不同操作系统上提供一致的体验
与构建系统集成通过工具链文件轻松集成到 CMake 等项目中
版本控制支持清单模式，实现可复现的构建和依赖版本锁定
社区驱动拥有庞大的社区和不断增长的库支持

本文档将指导您完成 vcpkg 的安装、环境配置、IDE 集成（重点是 VSCode）以及项目中的使用方法。

2. 安装 vcpkg

2.1 获取 vcpkg

获取 vcpkg 的推荐方式是使用 Git 克隆其仓库：

  1. 打开终端或命令提示符。

  2. 导航到您希望安装 vcpkg 的父目录（例如 C:\dev 或 ~/dev）。

  3. 运行克隆命令：

    # Windows (PowerShell)
git clone https://github.com/microsoft/vcpkg.git

    # Linux/macOS
git clone https://github.com/microsoft/vcpkg.git

    这会将 vcpkg 克隆到当前目录下的 vcpkg 文件夹中。

💡 提示： 您也可以将 vcpkg 作为项目的 Git 子模块添加：

git submodule add https://github.com/microsoft/vcpkg.git

替代方法（不推荐）： 您也可以从 vcpkg GitHub Releases 下载 ZIP 压缩包并解压，但这不利于后续更新 vcpkg。

2.2 引导 vcpkg (Bootstrap)

克隆完成后，需要运行引导脚本来编译 vcpkg 工具本身：

  1. 进入 vcpkg 目录：

    cd vcpkg

  2. 根据您的操作系统运行对应的引导脚本：

    操作系统命令
    Windows (PowerShell).\bootstrap-vcpkg.bat
    Windows (CMD)bootstrap-vcpkg.bat
    Linux / macOS./bootstrap-vcpkg.sh

引导脚本执行成功后，vcpkg.exe (Windows) 或 vcpkg (Linux/macOS) 可执行文件就会生成在 vcpkg 根目录下。

🔍 注意： 首次引导可能需要一些时间，因为它需要编译 vcpkg 可执行文件。请确保您的系统已安装所需的构建工具（如 Visual Studio Build Tools 或 GCC）。

vcpkg：C++ 包管理器安装与使用指南
（图片来源网络，侵删）

3. 配置环境变量 (可选但推荐)

配置环境变量可以让您在系统的任何位置调用 vcpkg 命令，并简化与 CMake 等工具的集成。您可以选择全局配置或项目级配置。

3.1 环境变量说明
  • VCPKG_ROOT: 指向 vcpkg 的安装根目录（包含 vcpkg.exe 或 vcpkg 可执行文件的目录）。这是最重要的环境变量，许多工具（如 CMake）会依赖它来找到 vcpkg 工具链。
  • PATH: 将 vcpkg 根目录添加到系统的 PATH 环境变量中，允许您直接在终端中运行 vcpkg 命令，而无需指定完整路径。
  • VCPKG_DEFAULT_TRIPLET: (可选) 设置默认的目标平台架构（称为 “triplet”）。如果不设置，vcpkg 会根据您的系统自动选择一个默认值（例如 x64-windows 或 x64-linux）。设置此变量可以简化 vcpkg install 命令，无需每次都指定 --triplet 参数。常见 Triplets 请参见 章节 6。
    3.2 全局配置 (影响所有项目)

    适用于需要在多个项目中频繁使用相同 vcpkg 实例的情况。

    vcpkg：C++ 包管理器安装与使用指南
    （图片来源网络，侵删）

    • Windows:

      1. 搜索 “编辑系统环境变量” 并打开。
      2. 点击 “环境变量…” 按钮。
      3. 在 “系统变量” (或 “用户变量”) 区域：
        • 点击 “新建…”，变量名输入 VCPKG_ROOT，变量值输入 vcpkg 的完整路径 (例如 C:\dev\vcpkg)。
        • (可选) 点击 “新建…”，变量名输入 VCPKG_DEFAULT_TRIPLET，变量值输入您希望的默认 Triplet (例如 x64-windows)。
        • 找到 Path 变量，点击 “编辑…”，然后点击 “新建”，输入 %VCPKG_ROOT%。
        • 点击 “确定” 保存所有更改。您可能需要重启终端或 VSCode 才能使更改生效。

    • Linux / macOS:

      vcpkg：C++ 包管理器安装与使用指南
      （图片来源网络，侵删）

      编辑您的 shell 配置文件（例如 ~/.bashrc, ~/.zshrc, ~/.profile 等），在文件末尾添加以下行：

      export VCPKG_ROOT="/path/to/your/vcpkg" # 替换为实际路径
export PATH="$VCPKG_ROOT:$PATH"
# export VCPKG_DEFAULT_TRIPLET="x64-linux" # 可选，替换为所需 Triplet

      保存文件后，运行 source ~/.bashrc (或相应的文件名) 或重启终端使更改生效。

      3.3 项目级配置 (推荐用于隔离)

      更推荐的方式是在项目级别配置 vcpkg，特别是当您希望将 vcpkg 作为项目的一部分（例如 Git 子模块）或者不同项目需要不同 vcpkg 版本/配置时。

      • 在终端中临时设置 (仅当前会话有效):
        • Windows PowerShell:
          $env:VCPKG_ROOT="C:\path\to\vcpkg" # 或 $env:VCPKG_ROOT="${workspaceFolder}\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"
# $env:VCPKG_DEFAULT_TRIPLET="x64-windows" # 可选
        • Linux / macOS Bash:
          export VCPKG_ROOT="/path/to/vcpkg" # 或 export VCPKG_ROOT="${PWD}/vcpkg"
export PATH="$VCPKG_ROOT:$PATH"
# export VCPKG_DEFAULT_TRIPLET="x64-linux" # 可选
        • 使用 VSCode 工作区设置 (推荐):

          这是在 VSCode 中为特定项目配置 vcpkg 环境的最佳方式，尤其是当 vcpkg 位于项目文件夹内时。

          1. 在 VSCode 中打开您的项目工作区。

          2. 打开命令面板 (Ctrl+Shift+P)，搜索并选择 “Preferences: Open Workspace Settings (JSON)”。 3. 在打开的 settings.json 文件中，添加或修改 terminal.integrated.env.* 配置：

            {
  "terminal.integrated.env.windows": {
    "VCPKG_ROOT": "${workspaceFolder}\\vcpkg",
    "PATH": "${workspaceFolder}\\vcpkg;${env:PATH}",
    "VCPKG_DEFAULT_TRIPLET": "x64-windows"
  },
  "terminal.integrated.env.linux": {
    "VCPKG_ROOT": "${workspaceFolder}/vcpkg",
    "PATH": "${workspaceFolder}/vcpkg:${env:PATH}",
    "VCPKG_DEFAULT_TRIPLET": "x64-linux"
  },
  "terminal.integrated.env.osx": {
    "VCPKG_ROOT": "${workspaceFolder}/vcpkg",
    "PATH": "${workspaceFolder}/vcpkg:${env:PATH}",
    "VCPKG_DEFAULT_TRIPLET": "x64-osx"
  }
}
            • terminal.integrated.env.windows/linux/osx: 为不同操作系统的VSCode集成终端设置环境变量
            • VCPKG_ROOT: 指向vcpkg的安装路径，此处使用工作区相对路径
            • PATH: 将vcpkg目录添加到系统路径
            • VCPKG_DEFAULT_TRIPLET: 设置默认目标平台架构

            • 说明:

              • ${workspaceFolder} 是 VSCode 提供的变量，指向当前工作区的根目录。
              • ${env:PATH} 会将系统原有的 PATH 变量包含进来。
              • 请根据您的 vcpkg 实际位置和目标平台调整路径和 Triplet。
              • 保存 settings.json 后，新打开的 VSCode 集成终端 (`Ctrl+``) 将自动应用这些环境变量。
              • 将 .vscode/settings.json 文件提交到版本控制系统，可以确保团队成员共享相同的开发环境配置。

          4. IDE 集成

          4.1 Visual Studio Code (推荐)

          VSCode 通过 CMake Tools 扩展可以与 vcpkg 良好集成。

          1. 安装必要扩展:

            • C/C++: 来自 Microsoft，提供语言支持、调试等。
            • CMake Tools: 来自 Microsoft，提供 CMake 项目管理、构建和调试支持。

            • 配置 CMake 以使用 vcpkg:

              核心是告知 CMake 使用 vcpkg 提供的工具链文件 (scripts/buildsystems/vcpkg.cmake)。推荐使用 CMakePresets.json 或 CMakeUserPresets.json 文件进行配置。 * 创建/编辑 CMakePresets.json 或 CMakeUserPresets.json:

              在项目根目录下创建（或由 CMake Tools 自动生成）该文件。一个典型的配置如下：

          {
  "version": 3,
  "configurePresets": [
    {
      "name": "default",
      "displayName": "Default Config with vcpkg",
      "description": "Uses vcpkg toolchain",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/${presetName}",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/vcpkg/scripts/buildsystems/vcpkg.cmake",
        "VCPKG_TARGET_TRIPLET": "x64-windows"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default-debug",
      "configurePreset": "default",
      "configuration": "Debug"
    },
    {
      "name": "default-release",
      "configurePreset": "default",
      "configuration": "Release"
    }
  ],
  "testPresets": []
}

          CMakePresets.json 配置说明:

          字段说明
          versionCMake Presets格式版本，3或更高版本
          name预设名称，可以是任何描述性名称
          generatorCMake生成器，如Ninja或"Visual Studio 17 2022"
          binaryDir构建文件输出目录
          CMAKE_TOOLCHAIN_FILE 指向vcpkg工具链文件的路径，有三种方式指定：
          1. 相对路径：${sourceDir}/vcpkg/scripts/buildsystems/vcpkg.cmake
          2. 环境变量：$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake
          3. 绝对路径(不推荐)：C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake
          VCPKG_TARGET_TRIPLET可选，设置目标平台架构

          选择配置预设:

          1. 保存 CMakePresets.json 文件。

          2. 在 VSCode 底部状态栏，CMake Tools 会自动检测到预设。点击状态栏上的 “[No Configure Preset Selected]” 或当前预设名称。

          3. 从弹出的列表中选择您定义的配置预设（例如 default）。

          4. CMake Tools 将使用选定的预设（包括 vcpkg 工具链）来配置项目。 * 替代方法 (不推荐): .vscode/settings.json

          您也可以在 .vscode/settings.json 中设置 cmake.configureSettings，但这不如 Presets 灵活，且优先级较低。

          {
  "cmake.configureSettings": {
    "CMAKE_TOOLCHAIN_FILE": "${workspaceFolder}/vcpkg/scripts/buildsystems/vcpkg.cmake",
    "VCPKG_TARGET_TRIPLET": "x64-windows"
  }
}
          4.2 Visual Studio (Classic)

          对于 Visual Studio 用户，vcpkg 提供了全局集成命令：

          # 确保在正确的 vcpkg 目录下执行，或者 VCPKG_ROOT 已设置
vcpkg integrate install

          此命令会将 vcpkg 与 MSBuild 集成，使得在 Visual Studio 中打开的 C++ 项目能够自动发现并使用通过 vcpkg 安装的库（无需手动配置项目属性）。

          注意事项:

          • 潜在冲突: 如果您的 Visual Studio 安装程序也安装了 vcpkg 的某个版本，或者系统中有多个 vcpkg 实例，integrate install 可能会导致混淆。建议在运行此命令前，通过设置 VCPKG_ROOT 环境变量明确指定要集成的 vcpkg 实例。
            # PowerShell 示例
$env:VCPKG_ROOT="C:\path\to\your\preferred\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"
vcpkg integrate install
          • 移除集成: 如果需要移除全局集成，可以运行 vcpkg integrate remove。
          • VSCode 用户: vcpkg integrate install 主要影响 Visual Studio (MSBuild)，对基于 CMake 和 VSCode 的工作流影响不大（CMake 通过 CMAKE_TOOLCHAIN_FILE 集成）。

            5. 在 CMake 项目中使用 vcpkg

            vcpkg 提供了两种主要的工作模式来管理项目依赖：经典模式 (Classic Mode) 和清单模式 (Manifest Mode)。

            5.1 经典模式与清单模式对比

            特性经典模式清单模式
            配置文件无专用配置文件vcpkg.json
            依赖范围全局安装到 vcpkg 实例项目本地安装
            依赖声明使用命令行安装在 vcpkg.json 中声明
            版本控制难以实现通过 builtin-baseline 可锁定版本
            团队协作需手动同步环境将配置文件加入版本控制即可
            推荐用途个人开发团队项目

            5.2 经典模式 (Classic Mode)

            这是 vcpkg 最初的工作方式。您需要手动在 vcpkg 实例中安装库，然后在 CMake 中查找它们。

            1. 安装库:

              在终端中，使用 vcpkg install 命令安装您需要的库。需要指定库名和目标 Triplet（除非设置了 VCPKG_DEFAULT_TRIPLET）。

              # Windows PowerShell 示例
# 安装 fmt 库，用于 64 位 Windows 静态链接
vcpkg install fmt:x64-windows
# 安装 boost 库，使用默认 Triplet
vcpkg install boost
# 安装多个库
vcpkg install zlib eigen3 nlohmann-json

              vcpkg 会将安装的库放置在其根目录下的 installed 文件夹中（按 Triplet 分隔）。

            📝 注意： 安装格式为 :，如果省略 : 部分，则使用默认 Triplet

            1. 在 CMakeLists.txt 中查找库:

              确保您的 CMake 配置使用了 vcpkg 工具链文件（见 章节 4.1）。然后在 CMakeLists.txt 中使用 find_package 命令。

              # filepath: /CMakeLists.txt
cmake_minimum_required(VERSION 3.15) # 推荐使用较新版本
project(MyAwesomeProject LANGUAGES CXX)
# vcpkg 工具链会自动处理查找路径，只需调用 find_package
find_package(fmt CONFIG REQUIRED)
find_package(Boost REQUIRED COMPONENTS system filesystem) # 查找 Boost 特定组件
add_executable(my_app main.cpp)
# 链接库
target_link_libraries(my_app PRIVATE fmt::fmt Boost::system Boost::filesystem)

            经典模式的缺点:

            • 依赖关系不直观，未在项目代码中明确声明。
            • 需要手动管理 vcpkg 实例中的库安装。
            • 团队协作时，需要确保所有成员的 vcpkg 环境一致。
            • 不利于构建可复现性。

              5.3 清单模式 (Manifest Mode - 推荐)

              清单模式是现代且推荐的使用方式。它允许您在项目根目录下的 vcpkg.json 文件中声明项目依赖，vcpkg 会根据此文件自动安装和管理所需的库。

              1. 启用清单模式:

                只需在项目根目录下创建一个 vcpkg.json 文件即可。您可以使用命令快速开始：

                # 在项目根目录下运行
vcpkg new --application # 对于可执行文件项目
# 或
vcpkg new --library # 对于库项目

                这会创建一个基础的 vcpkg.json 和一个可选的 vcpkg-configuration.json 文件。

              2. 编辑 vcpkg.json 声明依赖:

                手动编辑 vcpkg.json 或使用 vcpkg add port 命令添加依赖。

                {
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "name": "my-awesome-project",
  "version": "0.1.0",
  "dependencies": [
    "fmt",
    {
      "name": "boost",
      "features": ["system", "filesystem"]
    },
    {
      "name": "eigen3",
      "version>=": "3.4.0"
    },
    {
      "name": "openssl",
      "platform": "windows | linux"
    }
  ],
  "builtin-baseline": "a1b2c3d4e5f6..."
}

                vcpkg.json 字段说明：

                字段描述
                name项目名称，小写，允许使用连字符
                version项目版本
                dependencies项目依赖列表
                fmt简单依赖，直接使用包名
                boost 对象带特定组件的依赖，使用features字段指定需要的组件
                eigen3 对象指定最低版本要求，使用version>=字段
                openssl 对象特定平台依赖，仅在Windows或Linux上安装
                builtin-baseline锁定vcpkg官方仓库的某个提交状态，确保依赖版本一致性，应替换为实际的commit哈希

              💡 提示： 要获取当前 vcpkg 的 commit hash 作为 builtin-baseline，可以在 vcpkg 目录中运行 git rev-parse HEAD

              1. 安装依赖:

                当 CMake 配置项目时（并且 CMAKE_TOOLCHAIN_FILE 指向 vcpkg），vcpkg 会自动读取 vcpkg.json 并安装其中声明的所有依赖项到项目本地的 vcpkg_installed 目录中。

                您也可以手动触发安装：

                # 在项目根目录下运行
vcpkg install
# 指定 Triplet
vcpkg install --triplet=x64-windows-static

              2. 在 CMakeLists.txt 中使用:

                与经典模式类似，只需使用 find_package 即可。CMake 会自动在 vcpkg_installed 目录中查找。

                # filepath: /CMakeLists.txt
cmake_minimum_required(VERSION 3.18) # 清单模式推荐 CMake 3.18+
project(MyAwesomeProject LANGUAGES CXX)
# find_package 用法与经典模式相同
find_package(fmt CONFIG REQUIRED)
find_package(Boost REQUIRED COMPONENTS system filesystem)
find_package(Eigen3 REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE fmt::fmt Boost::system Boost::filesystem Eigen3::Eigen)

              3. 依赖版本控制:

                有几种方法可以控制依赖版本：

                方法语法用途
                builtin-baseline"builtin-baseline": "commit-hash"锁定整个注册表的状态
                版本约束"version>=": "1.2.3"指定最低版本要求
                精确版本"version=": "1.2.3"要求特定版本
                版本范围"version>=": "1.0.0", "version
免责声明：我们致力于保护作者版权，注重分享，被刊用文章因无法核实真实出处，未能及时与作者取得联系，或有版权异议的，请联系管理员，我们会立即处理! 部分文章是来自自研大数据AI进行生成,内容摘自(百度百科,百度知道,头条百科,中国民法典,刑法,牛津词典,新华词典,汉语词典,国家院校,科普平台)等数据,内容仅供学习参考,不准确地方联系删除处理! 图片声明：本站部分配图来自人工智能系统AI生成,觅知网授权图片,PxHere摄影无版权图库和百度，360，搜狗等多加搜索引擎自动关键词搜索配图，如有侵权的图片，请第一时间联系我们。

相关阅读

目录[+]

取消
微信二维码
微信二维码
支付宝二维码