什么是清单模式？

项目
08/09/2024

vcpkg 有两种运行模式：经典模式和清单模式。建议大多数用户采用清单模式。

清单模式使用声明性 JSON 文件来描述有关项目或包的元数据。清单文件需要具有 vcpkg.json 名称。

在工作目录中有清单文件 (vcpkg.json) 时，通过运行 vcpkg install 命令来进入清单模式。请继续阅读，详细了解如何在清单模式下安装包。

使用版本控制和自定义注册表等高级功能也需要清单模式。

端口中的清单文件

所有 vcpkg 端口都必须包含描述有关它们所安装的包的元数据的 vcpkg.json 文件。

Vcpkg 将包清单中的元数据用于各种目的，例如计算依赖项树、按名称或描述搜索包、解析功能等。

包清单示例

{
  "name": "fmt",
  "version": "10.1.1",
  "description": "Formatting library for C++. It can be used as a safe alternative to printf or as a fast alternative to IOStreams.",
  "homepage": "https://github.com/fmtlib/fmt",
  "license": "MIT",
  "dependencies": [
    {
      "name": "vcpkg-cmake",
      "host": true
    },
    {
      "name": "vcpkg-cmake-config",
      "host": true
    }
  ]
}

项目中的清单文件

在项目中使用清单文件的主要目的是声明依赖项。使用项目清单时，可以指定版本约束和覆盖，以锁定依赖项的特定版本。此功能在经典模式中不可用。

项目清单示例

{
  "dependencies": [ "fmt", "zlib" ],
  "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
  "overrides": [
    { "name": "zlib", "version": "1.2.8" }
  ]
}

配置文件

vcpkg 可以通过 vcpkg-configuration.json 文件进行配置，以添加更多包注册表或覆盖端口和三元组位置。

配置文件示例

{
  "default-registry": {
    "kind": "git",
    "baseline": "7476f0d4e77d3333fbb249657df8251c28c4faae",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/microsoft/vcpkg-docs",
      "reference": "vcpkg-registry",
      "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
      "packages": [ "beicode", "beison" ]
    }
  ],
  "overlay-ports": [
    "C:\\dev\\my_vcpkg_ports"
  ]
}

在清单模式下安装包

若要使用清单文件安装包，请使用 vcpkg install 命令，而不使用任何包参数。该命令必须从包含清单 (vcpkg.json) 文件的目录执行，或者使用 --x-manifest-root=<path> 选项提供的清单文件的路径执行。

在清单模式下安装的包不会像在经典模式下那样安装在全局 installed 目录中。相反，每个清单将获取其自己名为 vcpkg_installed 的安装目录；vcpkg_installed 目录是在包含清单文件的同一目录中创建的。

每个清单都有独立的安装树，可以分离不同项目之间的依赖项。这规避了经典模式的关键限制，即仅允许每个端口安装一个版本。清单模式保留每个项目分隔的端口版本。

使用项目清单中的功能

清单文件可以通过使用 "features" 来定义功能、行为和依赖项的累加集。

在项目中，可以定义用于启用或禁用应用于各个项目部分的依赖项的功能。例如，如果项目包含多个组件，可能希望将常见依赖项保留在 "dependencies" 列表中，但将其他一些依赖项限制为相应的组件。

若要启用项目的功能，可以使用以下方法之一：

将 --x-feature 选项传递给 vpckg install 命令。
在 CMake 上，在第一次调用 project() 前设置 VCPKG_MANIFEST_FEATURES。
在 MSBuild 上，通过 `VcpkgAdditionalInstallOptions 传递 --x-feature 选项。

示例：项目清单中的功能

{
  "name": "my-game",
  "dependencies": [ "grpc" ],
  "features": {
    "client": {
      "description": "client game executable",
      "dependencies": [ "sdl2", "bullet3" ]
    },
    "server": {
      "description": "multiplayer server executable",
      "dependencies": [ "proxygen" ]
    },
    "tests": {
      "description": "development tests",
      "dependencies": [ "gtest" ]
    }
  }
}

若要仅生成“客户端”组件的依赖项，请运行：

vcpkg install --x-feature=client

后续步骤

以下是接下来要尝试的一些任务：

完成清单模式教程
读取 vcpkg.json 和 vcpkg-configuration.json 参考文章。
使用版本控制锁定版本实现可重复构建

通过