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

上一篇:张高兴的 Xamarin.Android 学习笔记:(三)活动生命周期


下一篇:大数据中心技术的工程数智化指挥中心