kmpkg-configuration.json 参考文档

kmpkg-configuration.json 文件是项目 清单 的一部分，与 kmpkg.json 配合使用。kmpkg-configuration.json 中的所有字段仅由顶层项目使用——依赖项中的 kmpkg-configuration.json 文件会被忽略。

在 清单模式 中，kmpkg-configuration.json 可作为独立文件与 kmpkg.json 同级存放，也可嵌入到 kmpkg.json 的 "configuration" 字段 中。

在 经典模式 中，kmpkg 会使用 kmpkg 实例 根目录 下的 kmpkg-configuration.json 文件。

关于 kmpkg 注册表的使用概述，请参考 使用注册表。

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

示例

{
  "$schema": "https://raw.githubusercontent.com/kumose/kmpkg-tool/main/docs/kmpkg-configuration.schema.json",
  "default-registry": {
    "kind": "git",
    "repository": "https://internal/mirror/of/github.com/kumose/kmpkg",
    "baseline": "eefee7408133f3a0fef711ef9c6a3677b7e06fd7"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/MicrosoftDocs/kmpkg-docs",
      "reference": "kmpkg-registry",
      "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
      "packages": [ "beicode", "beison" ]
    }
  ],
  "overlay-ports": [
    "./team-ports",
    "./custom-ports"
   ],
  "overlay-triplets": [ "./my-triplets" ]
}

该示例配置了一个私有注册表 https://github.com/MicrosoftDocs/kmpkg-docs/tree/kmpkg-registry，作为 beicode 和 beison 库的来源；其他所有端口均从 https://internal/mirror/of/github.com/kumose/kmpkg（官方精选目录的内部镜像）获取。

示例还配置了自定义的端口覆盖路径和三元组覆盖路径，这些路径位于源码仓库中。

顶级字段

名称	类型	描述
default-registry	Registry 或 null	所有未指定专属注册表的端口使用的默认注册表
overlay-ports	string[]	用作覆盖端口位置的路径列表
overlay-triplets	string[]	用作覆盖三元组位置的路径列表
registries	Registry 数组	为特定端口子集提供的额外注册表

"default-registry"

所有未指定专属注册表的端口使用的默认注册表。类型为 Registry 或 null，可选。

未匹配任何 "packages" 模式的端口会从默认注册表解析。若默认注册表设为 null，未匹配的端口会解析失败；若省略该字段，默认注册表会隐式设为 内置注册表，并使用 "builtin-baseline" 的值作为 "baseline"。

"registries"

为特定端口提供的额外注册表。类型为 Registry 数组，可选。

"overlay-ports"

端口覆盖路径列表。类型为字符串数组，可选。

数组中的每个路径必须满足以下条件之一：

• 包含单个端口的目录（目录下需有 kmpkg.json 和 portfile.cmake 文件）；
• 包含多个端口目录的父目录（如 zlib 的 kmpkg.json 需位于 zlib/kmpkg.json）。

相对路径会相对于 kmpkg-configuration.json 文件解析；绝对路径可使用，但不推荐。

"overlay-triplets"

三元组覆盖路径列表。类型为字符串数组，可选。

数组中的每个路径必须指向包含三元组文件的目录（参考 三元组文档）。相对路径会相对于 kmpkg-configuration.json 文件解析；绝对路径可使用，但不推荐。

注册表字段

名称	是否必填	类型	描述
baseline	Git 注册表和内置注册表	string	该注册表所有端口的最低版本约束
kind	是	string	注册表类型
packages	非默认注册表时必填	string 数组	从该注册表获取的端口列表
path	文件系统注册表	string	文件系统注册表的路径
reference	否	string	用于获取可用版本的 Git 引用
repository	Git 注册表	string	Git 注册表的 URI

Registry: "kind"

注册表类型。类型为字符串，必填。

"kind" 取值	注册表类型
"filesystem"	文件系统注册表
"git"	Git 注册表
"builtin"	内置注册表

Registry: "baseline"

注册表特定的标识符，指定从该注册表获取的端口的最低版本。类型为字符串，必填。

• 对于 Git 注册表 和 内置注册表：该值是注册表仓库中包含 versions/baseline.json 文件的 40 字符 Git 提交哈希；
• 对于 文件系统注册表：该值可以是注册表在其 baseline.json 中定义的任意有效 JSON 属性名；若文件系统注册表未声明基线，默认使用 "default"。

Registry: "reference"

用于列出 Git 注册表 可用版本的 Git 引用。类型为字符串，可选。

若未指定，默认值为 HEAD。该字段可设置为主题分支，以访问尚未完全发布的版本。

Registry: "repository"

Git 注册表 的 URI。类型为字符串，Git 注册表必填。

该字符串支持 Git 可识别的所有 URI 格式：

• "https://github.com/kumose/kmpkg"
• "git@github.com:kumose/kmpkg"
• "/dev/kmpkg-registry"

相对路径的行为未定义，未来版本的 kmpkg 可能会变更。

Registry: "path"

文件系统注册表 的路径。类型为字符串，文件系统注册表必填。

相对路径会相对于 kmpkg-configuration.json 文件解析。

Registry: "packages"

分配给该注册表的端口模式列表。类型为字符串数组，所有非默认注册表必填。

每个条目必须是以下类型之一：

• 包名（如 boost）；
• 包名前缀 + *（工具版本 2022-12-14 新增）。

包模式仅允许包含小写字母、数字和 -，且 * 只能作为后缀。

有效模式示例：

• *: 匹配所有端口名；
• boost: 仅匹配端口 boost；
• b*: 匹配所有以 b 开头的端口；
• boost-*: 匹配所有以 boost- 为前缀的端口。

无效模式示例：

• *a（* 必须是前缀的最后一个字符）；
• a**（仅允许一个 *）；
• a+（+ 不是有效的模式字符）；
• a?（? 不是有效的模式字符）。

关于端口名解析的更多信息，请参考 使用注册表文档。