vcpkg.json 参考

有关将清单与 vcpkg 配合使用的概述，请参阅清单模式。

清单是严格的 JSON 文档。 其中不能包含 C++样式注释 (//)，后面也不能接逗号。 不过，可以使用以 $ 开头的字段名称在任何具有定义完善的一组密钥的对象中编写注释。 任何允许使用用户定义的密钥（如 "features"）的对象中都不能使用这些注释字段。

可以在 https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json 处获取最新的 JSON 架构。 具有 JSON 架构支持（例如 Visual Studio 和 Visual Studio Code）的 IDE 可以使用此文件提供自动完成和语法检查。 大多数 IDE 应将 vcpkg.json 中的 "$schema" 设置为此 URL。

示例

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "boost-system",
    {
      "name": "cpprestsdk",
      "default-features": false
    },
    "libxml2",
    "yajl"
  ]
}

此示例演示了某款使用 boost-system、cpprestsdk、libxml2 和 yajl 的应用的清单。 此示例还包含一个 $schema 引用，以提供更出色的 IDE 验证和自动完成。

顶级字段

名称	必需	类型​​	描述
builtin-baseline	否	string	构建为顶级时要使用的版本引脚
默认功能	否	功能对象[]	要求列为 on-by-default 的功能
依赖项	否	依赖项[]	构建和使用此项目所需的依赖项列表
说明	Libraries	String 或 String[]	项目说明
文档	否	string	上游项目文档的 URI
功能	否	{string： Feature}	对项目用户提供的可选功能
主页	否	string	上游项目主页的 URI
license	否	string 或 null	SPDX 许可证表达式
维护人员	否	String 或 String[]	包文件的维护人员
name	Libraries	string	项目名
overrides	否	Override[]	构建为顶级时要使用的版本引脚
port-version	否	integer	端口文件修订
支持	否	平台表达式	支持的平台和版本配置
版本 version-semver version-date version-string	Libraries	string	上游版本信息

"builtin-baseline"

在默认注册表为版本解决指定 "baseline" 的快捷方式。 一个字符串。 可选，仅供顶级项目使用。

该字段指示 https://github.com/microsoft/vcpkg 的提交，为清单提供全局最小版本信息。 使用版本控制，没有指定 "default-registry" 的顶级清单文件必填。 它具有与定义默认注册表相同的语义：

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<value>"
  }
}

有关更多语义详细信息，请参阅版本控制和使用注册表。

"default-features"

没有其他自定义的合理行业所需的功能集。

如果满足以下任意一种情况，则自动选择默认功能：

1. 端口到端口依赖项具有 "default-features": true，即默认值。
2. 顶级清单不具有端口 "default-features": false 的依赖项。

默认功能可处理具体情况：为顶级项目可能不了解的转换依赖项提供一个“默认”配置。 其他项目使用的端口应几乎始终使用 "default-features": false 作为其依赖项。

可通过使用功能对象来定义特定于平台的默认功能：

{
  "name": "my-port",
  "default-features": [
    "png",
    {
      "name": "winssl",
      "platform": "windows"
    }
  ]
}

有关功能的详细信息，请参阅 "features"。

"description"

端口的说明。 一个字符串或一组字符串。 对库而言是必填项，对顶级项目而言是选填项。

用于帮助用户发现库作为 search 或 find 命令的一部分，并了解库的作用。

"dependencies"

项目所需的依赖项列表。 依赖项对象的数组。 可选。

此字段列出构建和使用库或应用程序所需的所有依赖项。

示例端口依赖项

"dependencies": [
  {
    "name": "arrow",
    "default-features": false,
    "features": [
      "json",
      {
        "name": "mimalloc",
        "platform": "windows"
      }
    ]
  },
  "boost-asio",
  "openssl",
  {
    "name": "picosha2",
    "platform": "!windows"
  }
]

"documentation"

上游项目文档的 URI。 一个字符串。 可选。

"features"

项目用户可使用的功能。 名称到功能对象的映射。 可选。

功能是布尔标志，用于向版本添加其他行为和依赖项。 请参阅清单概念文档，详细了解功能。

"homepage"

项目主页的 URI。 一个字符串。 可选。

"license"

项目的 SPDX 短许可证表达式。 string 或 null。 可选。

"license" 应该要么是 SPDX 3.19 许可证表达式，要么是 null 以指示用户必须阅读部署的 /share/<port>/copyright 文件。 不支持 DocumentRefs。

注意

vcpkg 注册表中为每个包提供的许可信息代表了 Microsoft 对许可要求的最佳理解。 然而，这些信息可能不是最终的。 建议用户核实他们打算使用的每个包的确切许可要求，因为确保遵守适用的许可证最终是他们的责任。

示例许可证字符串

• MIT
• LGPL-2.1-only AND BSD-2-Clause
• GPL-2.0-or-later WITH Bison-exception-2.2

EBNF

vcpkg 使用以下 EBNF 分析许可证字段：

idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;

(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;

with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;

simple-expression = [ whitespace ], (
  | license-id
  | license-id, "+"
  | license-ref
  ), [ whitespace ] ;

(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
  | simple-expression
  | [ whitespace ], "(", or-expression, ")", [ whitespace ] ;

with-expression =
  | parenthesized-expression
  | simple-expression, with, license-exception-id, [ whitespace ] ;

(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;

license-expression = or-expression ;

"maintainers"

包维护人员列表。 一个字符串或一组字符串。 可选。

建议使用“姓名<电子邮件>”的格式。

"name"

项目的名称。 一个字符串。 对库而言是必填项，对顶级项目而言是选填项。

名称必须为小写 ASCII 字母、数字或连字符 (-)。 不得以连字符开头或结尾。 鼓励库包含其组织或框架名称作为前缀（如 msft- 或 boost-），帮助用户查找和描述关联的库。

例如，官方名称是 Boost.Asio 的库可以命名为“boost-asio”。

"overrides"

用于特定依赖项的具体版本引脚。 一 组 Override 对象。 可选。

会忽略转换清单（即依赖项）中的 "overrides"。 仅使用顶级项目定义的替代。

名称	必需	类型​​	说明
name	是	string	端口名称
version	是	string	要固定的上游版本信息。
version-semver version-date version-string	是	string	version 命名特定方案的已弃用替代方法。
port-version	否	integer	要固定的端口文件修订。 已弃用，支持将其置于版本本身中。

应将 "port-version" 指定为 "version" 中的 #N 后缀。 例如，"version": "1.2.3#7" 命名版本 1.2.3 端口版本 7。

另请参阅版本控制，详细了解语义。

版本替代示例

  "overrides": [
    {
      "name": "arrow", "version": "1.2.3#7"
    },
    {
      "name": "openssl", "version": "1.1.1h#3"
    }
  ]

"port-version"

区分打包文件的修订的版本后缀。 {1}一个整数。{2} 默认为 0。

每当发布的新版本端口不更改上游源版本，"port-version" 都应该递增。 当上游源版本更改时，版本字段应更改且应将 "port-version" 重置为 0（或已删除）。

有关详细信息，请参阅版本控制。

"supports"

支持的平台和版本配置。 一个平台表达式。 可选。

此字段记录某个项目不会在某些平台配置下成功构建或运行。

例如，如果库不支持为 Linux 构建，则应使用 "supports": "!linux"。

"vcpkg-configuration"

允许在 vcpkg.json 文件中嵌入 vcpkg 配置属性。 vcpkg-configuration 属性中的所有内容均被视为在 vcpkg-configuration.json 文件中被定义一样。 有关更多详细信息，请参阅 vcpkg-configuration.json 文档。

如果在 vcpkg.json 中已经定义了一个 vcpkg-configuration，则不允许同时还有一个 vcpkg-configuration.json 文件，并且会导致 vcpkg 命令终止，收到错误消息。

嵌入的 vcpkg-configuration 示例

{
  "name": "test",
  "version": "1.0.0",
  "dependencies": [ "beison", "zlib" ],
  "vcpkg-configuration": {
    "registries": [
      {
        "kind": "git",
        "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
        "repository": "https://github.com/microsoft/vcpkg-docs",
        "reference": "vcpkg-registry",
        "packages": [ "beicode", "beison" ]
      }
    ],
    "overlay-ports": [ "./my-ports/fmt", 
                       "./team-ports"
    ]
  }

上游 项目的版本。 一个字符串。 对库而言是必填项，对顶级项目而言是选填项。

清单必须最多包含一个版本字段。 每个版本字段对应于不同的版本控制方案：

• "version" - 宽松的语义版本 2.0.0，允许多于或少于 3 个主要数字。 示例：1.2.3.4.10-alpha1
• "version-semver" - 严格的语义版本 2.0.0。 示例： 2.0.1-rc5
• "version-date" - 格式设置为 YYYY-MM-DD 的日期，其中可选尾随以句点分隔的数字序列。 用于没有数字版本的包（例如，Live-at-HEAD）。 示例： 2022-12-09.314562
• "version-string" - 任意字符串。 用于没有可排序版本的包。 应很少使用，不过在其他版本字段之前创建的所有端口会引入使用此方案。

有关详细信息，请参阅版本控制。

储藏项字段

每个依赖项都是一个具有以下字段的字符串或对象：

名称	必需	类型​​	描述
默认功能	否	布尔	要求列为 on-by-default 的功能
features	否	功能对象[]	要求的其他功能列表
host	否	布尔	需要主机的依赖项而不是目标
name	是	string	依赖项的名称
平台	否	平台表达式	哪个平台可以使用依赖项的条件标准
version>=	否	string	所需的最低版本。 端口版本使用 #N 后缀标识，例如，1.2.3#7 会命名端口版本 7。

字符串解释为定义为字符串值的名称的对象。

依赖项："default-features"

一个布尔值，指示项目依赖于依赖项的“默认”功能。 默认为 true。

大多数情况下应定义为 false，并且任何需要的功能应明确依赖。

依赖项："features"

要求的其他功能列表。 一组功能对象。 可选。

功能对象是具有以下字段的对象：

• name - 功能的名称。 一个字符串。 必需。
• platform - 1 个平台表达式，用来限制哪些平台需要此功能。 可选。

简单字符串也是一个有效的 Feature Object，等效于 { "name": "<feature-name>" }。

例如，

{
  "name": "ffmpeg",
  "default-features": false,
  "features": [
    "mp3lame",
    {
      "name": "avisynthplus",
      "platform": "windows"
    }  
  ]
}

使用支持 mp3 编码的 ffmpeg 库。 仅在 Windows 上，还实现支持 avisynthplus。

依赖项："host"

一个布尔值，指示依赖项必须是为主机三联密码而非当前端口的三联密码而构建。 默认为 false。

任何提供工具或者应在某个版本（例如 buildsystems、代码生成器或帮助程序等）期间“执行”的脚本的依赖项，都应标记为“"host": true”。 如果目标不是可执行文件，则启用正确的交叉编译，例如编译 arm64-android 时。

有关详细信息，请参阅主机依赖项。

依赖项："name"

依赖项的名称。 一个字符串。 必需。

与项目的 "name" 属性遵循相同限制。

依赖项："platform"

一个表达式，用于限制需要依赖项的平台。 一个平台表达式。 可选。

如果表达式与当前配置不匹配，则不会使用依赖项。 例如，如果依赖项具有 "platform": "!windows"，则仅当面向非 Windows 系统时才需要它。

依赖项："version>="

依赖项的最低版本约束。

此字段指定依赖项的最低版本，（可选操作）使用 #N 后缀指定最低端口版本（如果需要）。

有关版本控制语义的更多信息，请参阅版本控制。

功能字段

每个功能都是具有以下字段的一个对象：

名称	必需	类型​​	说明
说明	是	string	功能的说明
dependencies	否	依赖项[]	依赖项列表
支持	否	平台表达式	哪些平台和配置支持此功能的条件标准
license	否	string 或 null	SPDX 许可证表达式

请查看清单模式文档，从概念层面了解功能概述。

包含功能的示例端口

{
  "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"
      ]
    }
  }
}

功能："dependencies"

功能所需要的依赖项列表。 依赖项对象的数组。 可选。

此字段列出了构建和使用该功能所需的任何其他依赖项。

功能："description"

功能的说明。 一个字符串或一组字符串。 必需。

用于帮助用户了解作为 search 或 find 命令的一部分的该功能，并了解该功能的作用。

功能："supports"

该功能支持的平台和版本配置。 一个平台表达式。 可选。

此字段用于记录该功能会在其中成功构建和运行的平台配置。

功能："license"

功能的 SPDX 短许可证表达式。 string 或 null。 可选。 如果未提供许可证，则许可证与顶级许可证字段中指定的相同。

注意

vcpkg 注册表中为每个包提供的许可信息代表了 Microsoft 对许可要求的最佳理解。 然而，这些信息可能不是最终的。 建议用户核实他们打算使用的每个包的确切许可要求，因为确保遵守适用的许可证最终是他们的责任。

平台表达式

平台表达式是一个 JSON 字符串，用于描述何时需要依赖项或应构建库或功能。

表达式是从基元标识符、逻辑运算符和分组构建的：

• !<expr>、not <expr> - 求反
• <expr>|<expr>、<expr>,<expr>逻辑 OR（虽然保留关键字 or，但在平台表达式中无效）
• <expr>&<expr>、<expr> and <expr> - 逻辑 AND
• (<expr>) - 分组优先

以下标识符基于三联密码设置和版本配置进行定义：

Identifier	三联密码条件
x64	VCPKG_TARGET_ARCHITECTURE == "x64"
x86	VCPKG_TARGET_ARCHITECTURE == "x86"
arm	VCPKG_TARGET_ARCHITECTURE == "arm" 或 VCPKG_TARGET_ARCHITECTURE == "arm64"
arm32	VCPKG_TARGET_ARCHITECTURE == "arm"
arm64	VCPKG_TARGET_ARCHITECTURE == "arm64"
arm64ec	VCPKG_TARGET_ARCHITECTURE == "arm64ec"
wasm32	VCPKG_TARGET_ARCHITECTURE == "wasm32"
mips64	VCPKG_TARGET_ARCHITECTURE == "mips64"
windows	VCPKG_CMAKE_SYSTEM_NAME == "" 或 VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" 或 VCPKG_CMAKE_SYSTEM_NAME == "MinGW"
mingw	VCPKG_CMAKE_SYSTEM_NAME == "MinGW"
uwp	VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore"
xbox	定义 VCPKG_CMAKE_SYSTEM_NAME == "" 和 XBOX_CONSOLE_TARGET。
linux	VCPKG_CMAKE_SYSTEM_NAME == "Linux"
osx	VCPKG_CMAKE_SYSTEM_NAME == "Darwin"
ios	VCPKG_CMAKE_SYSTEM_NAME == "iOS"
freebsd	VCPKG_CMAKE_SYSTEM_NAME == "FreeBSD"
openbsd	VCPKG_CMAKE_SYSTEM_NAME == "OpenBSD"
android	VCPKG_CMAKE_SYSTEM_NAME == "Android"
emscripten	VCPKG_CMAKE_SYSTEM_NAME == "Emscripten"
qnx	VCPKG_CMAKE_SYSTEM_NAME == "QNX"
vxworks	VCPKG_CMAKE_SYSTEM_NAME == "VxWorks"
static	VCPKG_LIBRARY_LINKAGE == "static"
staticcrt	VCPKG_CRT_LINKAGE == "static"
native	TARGET_TRIPLET == HOST_TRIPLET

平台表达式示例

• 在非 Windows 上，需要 picosha2 才能进行 sha256，但在 Windows (BCrypt) 会从 OS 中获取

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

• 在 arm64 Windows 和 amd64 Linux 上需要 zlib

{
  "name": "zlib",
  "platform": "(windows & arm64) | (linux & x64)"
}