VCPKG 特性 - Manifest

背景

VCPKG目前有2种模式使用提供的库，经典模式和manifest 模式，经典模式最早安装使用库的方式，是为了区分manifest模式给出的名称，manifest 可以理解为清单模式。

经典模式下 ，当您在私有项目中使用vcpkg安装的库时，必须首先通过vcpkg install命令安装了依赖的库才可以使用，而且所有安装在vcpkg installed 目录下的库对当前所有项目都是可见的。

这会带一些问题，例如2个项目需要各依赖同一个库的不同版本，2个项目中各自依赖的2个库互相冲突，以往的解决方案是给每一个项目单独配置vcpkg 库，单独去集成，这样很不方便，使用manifest模式能很方便的解决这个问题。

Manifest(清单)模式

当使用 vcpkg install 命令安装库时，被安装的库的依赖是通过 ports/PORT_NAME/CONTROL 或 ports/PORT_NAME/vcpkg.json 中的 "Build-depends" 或 "Depends" 关键字确定的。同样的，我们需要创建一个文件并指定私有项目的依赖以通过vcpkg读取该依赖并自动安装它们。这个清单文件的文件名称被指定为 vcpkg.json，通常放置在最顶级的 CMakeLists.txt 的同级目录下。

注意：manifest模式与传统模式不能同时使用，您通过install命令安装的依赖库将在manifest模式中被重新构建。

Manifest字段详解

vcpkg.json 文件：

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json",
  "name": "my-application",
  "version": "0.15.2",
  "dependencies": [
    "boost-system",
    "libxml2",
    "yajl"
  ]
}

Manifest文件是json格式的，并且不能包含注释，但您可以使用 "$" 开头的字段并将注释加入其键值中，例如示例文件的第二行 "$schema"。

每个清单文件必须包含 name，version 及 dependencies 字段，以下是这些字段的定义。

必选字段

name

您的私有项目名称，不一定与project名称一致，但对应键值必须是以小写字母，数字和连接字符 "-" 拼接而成。并且不能以连接字符开头或结尾。

例如"Boost.Asio"可命名为"boost-asio"。

version

您的私有项目版本号，该键名可为以下几种之一：

键名	说明
version	使用点（.）分隔的数字版本号
version-semver	SemVer的兼容版本号（请查看相关文档semver）
version-date	格式为YYYY-MM-DD的日期版本号
version-string	任意字符串版本号

dependencies

您的项目依赖表，它是一个字符串和对象组成的数组，可以以下两种方式声明：

1. 字符串依赖是最简单的依赖方式（例如 "dependencies": [ "zlib" ]）。由于不声明该依赖项的版本，平台限制，特性及默认特性，vcpkg会安装指定的依赖库(包括默认特性)。

2. 对象依赖（例如 "dependencies": [ { "name": "zlib" } ]）。该方式允许您声明该依赖项的版本，平台限制，特性及默认特性。示例：

vcpkg.json

"dependencies": [
  {
    "name": "arrow",
    "default-features": false,
    "features": [ "json" ]
  },
  "boost-asio",
  "openssl"
]

其中："name"为依赖项的名称。"default-features"为是否启用默认特性。"features"为依赖项的指定特性。

 platform

"platform"为当前依赖指定的平台，若编译环境不在该平台上则不会生成该依赖。

这是一个字符串字段，它采用形式为<identifier>， !expression， expression { & expression & expression...} 与布尔表达式 { | expression | expression...}以及括号来表示优先级。

例如，仅安装在 Windows 操作系统、ARM64 架构和 x64 上的 Linux 上的依赖项将被写入(windows & arm64) | (linux & x64)。

常见的标识符有：

操作系统：windows、uwp、linux、osx（包括 macOS）、android、emscripten

架构：x86, x64, wasm32, arm64, arm（由于向后兼容，包括 arm32 和 arm64）

示例: vcpkg.json

{
  "name": "zlib",
  "platform": "!windows"
}

可选字段

除了以上三个必选字段外，还有以下几个可选字段：

 description

您可添加该字段来描述您的项目，键值为字符串或字符串数组。当您使用字符串数组时，数组中第一个字符串默认为摘要信息，而其余字符串默认为完整信息。

 builtin-baseline

此字段表示vcpkg的commit，为您清单文件中未声明版本的依赖项提供默认版本信息。详情请参阅版本控制。

 overrides

您可使用该字段强制声明依赖项的具体版本号和补丁版本号，该版本的优先度最高。示例：

vcpkg.json 文件：

"overrides": [
    {
      "name": "arrow", "version": "1.2.3", "port-version": 7
    }
  ]

请勿将此字段加入"dependencies"中，而应当与其他关键字并列。更多信息请参阅版本控制。

 supports

若您的该私有项目不支持所有平台，可声明该字段并将支持的平台值传入键值中。可选键值请参考"platform"。

 features 与 default-features

若您的项目有可选特性，则可使用该字段声明，以让其他项目（非默认的或默认的）开启或关闭这些特性。它的值为一个对象，其中包含以下字段:

1. "description" 为该特性的描述信息，键值为字符串。该项为必选项。详情请参阅description字段。

2. "dependencies" 为特性的依赖项，该项可选。键值请参阅dependencies字段。

3. "supports" 为该特性支持的平台，该项可选。键值请参阅supports。

若您希望某一个特性应当被默认启动，请将该特性名称加入 "default-features" 中。该字段为字符串数组，示例：

vcpkg.json文件：

{
  "name": "libdb",
  "version": "1.0.0",
  "description": [
    "An example database library.",
    "Optionally can build with CBOR, JSON, or CSV as backends."
  ],
  "$default-features-explanation": "Users using this library transitively will get all backends automatically",
  "default-features": [ "cbor", "csv", "json" ],
  "features": {
    "cbor": {
      "description": "The CBOR backend",
      "dependencies": [
        {
          "$explanation": [
            "This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
          ],
          "name": "libdb",
          "default-features": false,
          "features": [ "json" ]
        }
      ]
    },
    "csv": {
      "description": "The CSV backend",
      "dependencies": [
        "fast-cpp-csv-parser"
      ]
    },
    "json": {
      "description": "The JSON backend",
      "dependencies": [
        "jsoncons"
      ]
    }
  }
}

以上就是清单文件中所有的关键字。

参考：https://github.com/microsoft/vcpkg/blob/master/docs/users/manifests.md

首次发布于：https://www.cnblogs.com/vcpkg/p/15019867.html