kmpkg.json 参考文档

关于 kmpkg 清单的使用概述，请参考 清单模式。

清单是严格的 JSON 文档，不支持 C++ 风格注释（//）和尾随逗号。但你可以在所有具有明确定义键集的对象中，使用以 $ 开头的字段名添加注释。这些注释字段不允许出现在任何允许用户自定义键的对象中（如 "features"）。

最新的 JSON Schema 可在以下地址获取：https://raw.githubusercontent.com/kumose/kmpkg-tool/main/docs/kmpkg.schema.json。支持 JSON Schema 的 IDE（如 Visual Studio、Visual Studio Code）可通过该文件提供自动补全和语法检查功能。大多数 IDE 要求在 kmpkg.json 中设置 "$schema" 字段指向该 URL。

示例

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

该示例展示了一个应用程序的清单，依赖 boost-system、cpprestsdk、libxml2 和 yajl。示例中还包含了 $schema 引用，以启用更完善的 IDE 验证和自动补全功能。

顶级字段

名称	是否必填	类型	描述
builtin-baseline	否	string	作为顶层项目构建时使用的版本固定值
default-features	否	功能对象	要求默认启用的 功能
dependencies	否	依赖项[] 数组	构建和使用该项目所需的依赖项列表
description	库必填	string 或 string[]	项目描述
documentation	否	string	上游项目文档的 URI
features	否	string: 功能 映射	项目用户可选择的 功能
homepage	否	string	上游项目主页的 URI
license	否	string 或 null	SPDX 许可证表达式
maintainers	否	string 或 string[]	包文件的维护者
name	库必填	string	项目名称
overrides	否	覆盖项[] 数组	作为顶层项目构建时使用的版本固定值
port-version	否	integer	端口文件修订版本
supports	否	平台表达式	支持的平台和构建配置
version version-semver version-date version-string	库必填	string	上游版本信息

"builtin-baseline"

指定默认注册表中版本解析的 "baseline" 快捷方式。类型为字符串，可选，仅由顶层项目使用。

该字段指定 https://github.com/kumose/kmpkg 的提交哈希，为清单提供全局最低版本信息。对于未指定 "default-registry" 但使用版本控制的顶层清单文件，该字段是必需的。其语义等同于将默认注册表定义为：

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

更多语义细节，请参考 版本控制 和 使用注册表。

"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 简化许可证表达式。类型为字符串或 null，可选。

"license" 应为 SPDX 3.19 许可证表达式，或设为 null（表示用户必须阅读部署后的 /share/<port>/copyright 文件）。不支持 DocumentRefs。

信息

kmpkg 注册表中每个包提供的许可证信息是 Microsoft 对许可证要求的最佳理解，但可能并非最终结论。建议用户在使用每个包前核实确切的许可证要求，确保合规是用户的最终责任。

许可证字符串示例

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

扩展巴科斯-瑙尔范式（EBNF）

kmpkg 使用以下 EBNF 解析许可证字段：

idchar = ? 正则表达式 /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;

(* 注意：未识别的许可证和许可证例外 ID 会触发警告 *)
license-id = idstring ;
license-exception-id = idstring ;
(* 注意：本实现不支持 DocumentRefs *)
license-ref = "LicenseRef-", idstring ;

with = [ 空白字符 ], "WITH", [ 空白字符 ] ;
and = [ 空白字符 ], "AND", [ 空白字符 ] ;
or = [ 空白字符 ], "OR", [ 空白字符 ] ;

simple-expression = [ 空白字符 ], (
  | license-id
  | license-id, "+"
  | license-ref
  ), [ 空白字符 ] ;

(* 以下拆分是为了明确优先级 *)
parenthesized-expression =
  | simple-expression
  | [ 空白字符 ], "(", or-expression, ")", [ 空白字符 ] ;

with-expression =
  | parenthesized-expression
  | simple-expression, with, license-exception-id, [ 空白字符 ] ;

(* 注意："a AND b OR c" 解析为 "(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"

特定依赖项的精确版本固定。类型为覆盖项对象数组，可选。

传递清单（即依赖项中的清单）的 "overrides" 会被忽略，仅使用顶层项目定义的覆盖项。

名称	是否必填	类型	描述
name	是	string	端口名称
version	是	string	要固定的上游版本信息
version-semver version-date version-string	是	string	version 的废弃替代字段，指定特定版本方案
port-version	否	integer	要固定的端口文件修订版本（已废弃，建议在 version 中指定）

"port-version" 应作为 #N 后缀添加到 "version" 中。例如，"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"

区分端口文件修订版本的后缀。类型为整数，默认值为 0。

当发布不改变上游源码版本的新端口版本时，应递增 "port-version"；当上游源码版本变更时，应修改 版本字段 并将 "port-version" 重置为 0（或省略）。

更多细节，请参考 版本控制。

"supports"

支持的平台和构建配置。类型为 平台表达式，可选。

该字段用于说明项目在某些平台配置下可能无法成功构建或运行。

例如，若你的库不支持 Linux 构建，可设置 "supports": "!linux"。

"configuration"

允许在 kmpkg.json 中嵌入 kmpkg 配置属性。configuration 内的所有内容均视为在 kmpkg-configuration.json 中定义。更多细节，请参考 kmpkg-configuration.json 文档。

kmpkg-configuration 是该字段的旧拼写，功能完全相同。

不允许同时在 kmpkg.json 中定义 configuration/kmpkg-configuration 和单独的 kmpkg-configuration.json 文件，否则 kmpkg 命令会报错终止。

嵌入 configuration 示例

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

"version"、"version-semver"、"version-date"、"version-string"

上游项目的版本。类型为字符串。库必填，顶层项目可选。

一个清单最多只能包含一个版本字段，每个字段对应不同的版本方案：

• "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 的日期，可选尾随点分隔的数字序列。用于无数字版本的包（如实时 HEAD 版本）。示例：2022-12-09.314562
• "version-string" - 任意字符串。用于无有序版本的包。该方案应极少使用，但所有在其他版本字段引入前创建的端口均使用此方案。

更多细节，请参考 版本控制。

依赖项字段

每个依赖项可以是字符串，或包含以下字段的对象：

名称	是否必填	类型	描述
default-features	否	bool	是否需要依赖项的默认启用功能
features	否	功能对象数组	需要的额外功能列表
host	否	bool	是否为宿主机器而非目标机器要求依赖项
name	是	string	依赖项名称
platform	否	平台表达式	限制依赖项适用的平台
version>=	否	string	最低要求版本。端口版本通过 #N 后缀指定，例如 1.2.3#7 表示端口版本 7。

字符串形式的依赖项会被解析为仅包含 name 字段的对象。

依赖项: "default-features"

指定项目是否依赖依赖项的“默认启用”功能。默认值为 true。

大多数情况下，应设置为 false，并显式依赖所需的功能。

依赖项: "features"

需要的额外功能列表。类型为功能对象数组，可选。

功能对象包含以下字段：

• name - 功能名称。字符串，必填。
• platform - 限制功能适用平台的 平台表达式。可选。

简单字符串也视为有效的功能对象，等价于 { "name": "<功能名称>" }。

功能对象示例

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

使用带有 MP3 编码支持的 ffmpeg 库；仅在 Windows 平台上启用 avisynthplus 支持。

依赖项: "host"

指定依赖项是否必须为 宿主三元组 而非当前端口的三元组构建。默认值为 false。

任何提供构建期间“执行”所需工具或脚本的依赖项（如构建系统、代码生成器或辅助工具），都应标记为 "host": true。这确保了在目标平台不可执行的交叉编译场景（如编译 arm64-android）中能正确构建。

更多信息，请参考 宿主依赖项。

依赖项: "name"

依赖项名称。类型为字符串，必填。

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

依赖项: "platform"

限制依赖项适用平台的表达式。类型为 平台表达式，可选。

若表达式与当前配置不匹配，依赖项将不会被使用。例如，若依赖项设置 "platform": "!windows"，则仅在目标为非 Windows 系统时才会被要求。

依赖项: "version>="

依赖项的最低版本约束。

该字段指定依赖项的最低版本，可选通过 #N 后缀指定最低端口版本。

更多版本语义信息，请参考 版本控制。

功能字段

每个功能是包含以下字段的对象：

名称	是否必填	类型	描述
description	是	string	功能描述
dependencies	否	依赖项[] 数组	依赖项列表
supports	否	平台表达式	功能支持的平台和配置
license	否	string 或 null	SPDX 许可证表达式

功能的概念概述，请参考 清单模式 文档。

带功能的端口示例

{
  "features": {
    "cbor": {
      "description": "CBOR 后端",
      "dependencies": [
        {
          "$explanation": [
            "告知 kmpkg cbor 功能依赖该包的 json 功能"
          ],
          "name": "libdb",
          "default-features": false,
          "features": [ "json" ]
        }
      ]
    },
    "csv": {
      "description": "CSV 后端",
      "dependencies": [
        "fast-cpp-csv-parser"
      ]
    },
    "json": {
      "description": "JSON 后端",
      "dependencies": [
        "jsoncons"
      ]
    }
  }
}

[功能][]: "dependencies"

功能 所需的依赖项列表。类型为 依赖项对象 数组，可选。

该字段列出构建和使用该功能所需的所有额外依赖项。

[功能][]: "description"

功能 的描述。类型为字符串或字符串数组，必填。

用于帮助用户通过 search 或 find 命令发现功能，并了解功能的作用。

[功能][]: "supports"

功能 支持的平台和构建配置。类型为 平台表达式，可选。

该字段说明功能能成功构建和运行的平台配置。

[功能][]: "license"

功能 的 SPDX 简化许可证表达式。类型为字符串或 null，可选。若未提供，默认使用顶层 license 字段的值。

信息

kmpkg 注册表中每个包提供的许可证信息是 Microsoft 对许可证要求的最佳理解，但可能并非最终结论。建议用户在使用每个包前核实确切的许可证要求，确保合规是用户的最终责任。

平台表达式

平台表达式是描述依赖项是否必需，或库/功能是否能构建的 JSON 字符串。

表达式由原始标识符、逻辑运算符和分组构成：

• !<表达式>, not <表达式> - 否定
• <表达式>|<表达式>, <表达式>,<表达式> - 逻辑或（关键字 or 已保留但不支持）
• <表达式>&<表达式>, <表达式> and <表达式> - 逻辑与
• (<表达式>) - 分组/优先级

以下标识符基于 三元组设置 和构建配置定义：

标识符	三元组条件
x64	KMPKG_TARGET_ARCHITECTURE == "x64"
x86	KMPKG_TARGET_ARCHITECTURE == "x86"
arm	KMPKG_TARGET_ARCHITECTURE == "arm" 或 KMPKG_TARGET_ARCHITECTURE == "arm64"
arm32	KMPKG_TARGET_ARCHITECTURE == "arm"
arm64	KMPKG_TARGET_ARCHITECTURE == "arm64"
arm64ec	KMPKG_TARGET_ARCHITECTURE == "arm64ec"
wasm32	KMPKG_TARGET_ARCHITECTURE == "wasm32"
mips64	KMPKG_TARGET_ARCHITECTURE == "mips64"
windows	KMPKG_CMAKE_SYSTEM_NAME == "" 或 KMPKG_CMAKE_SYSTEM_NAME == "WindowsStore" 或 KMPKG_CMAKE_SYSTEM_NAME == "MinGW"
mingw	KMPKG_CMAKE_SYSTEM_NAME == "MinGW"
uwp	KMPKG_CMAKE_SYSTEM_NAME == "WindowsStore"
xbox	KMPKG_CMAKE_SYSTEM_NAME == "" 且 XBOX_CONSOLE_TARGET 已定义
linux	KMPKG_CMAKE_SYSTEM_NAME == "Linux"
osx	KMPKG_CMAKE_SYSTEM_NAME == "Darwin"
ios	KMPKG_CMAKE_SYSTEM_NAME == "iOS"
freebsd	KMPKG_CMAKE_SYSTEM_NAME == "FreeBSD"
openbsd	KMPKG_CMAKE_SYSTEM_NAME == "OpenBSD"
android	KMPKG_CMAKE_SYSTEM_NAME == "Android"
emscripten	KMPKG_CMAKE_SYSTEM_NAME == "Emscripten"
qnx	KMPKG_CMAKE_SYSTEM_NAME == "QNX"
vxworks	KMPKG_CMAKE_SYSTEM_NAME == "VxWorks"
static	KMPKG_LIBRARY_LINKAGE == "static"
staticcrt	KMPKG_CRT_LINKAGE == "static"
native	TARGET_TRIPLET == HOST_TRIPLET

平台表达式示例

• 非 Windows 平台需要 picosha2 实现 SHA256，Windows 平台从系统（BCrypt）获取

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

• arm64 Windows 和 amd64 Linux 平台需要 zlib

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