跳到主要内容

注册表参考文档

概述​

本文介绍各类注册表的实现细节，具体包括每种注册表的推荐目录结构，以及其对应的版本数据库应包含的内容。

信息

本文涵盖自定义注册表的实现相关信息。若需了解在项目中使用自定义注册表的方法，请参阅使用注册表一文。

Git 注册表​

Git 注册表中的基线文件结构​

顶层字段​

baseline.json 文件的顶层对象是一个字典，字典中的每个键为一个命名基线（named baseline）。由于 Git 注册表的实现特性，必须存在一个名为 "default" 的命名基线，且该基线需包含注册表中所有端口与其基线版本的映射关系。

名称类型说明
default基线对象（BaselineObject）Git 注册表必需的默认基线
命名基线基线对象（BaselineObject）额外的基线，字段名对应基线名称

基线对象（BaselineObject）​

基线对象是一个字典，每个键对应注册表中的一个端口名，值为该端口的最新版本。

名称类型说明
端口名基线版本对象（BaselineVersionObject）端口名与其最新版本的映射关系

基线版本对象（BaselineVersionObject）​

名称类型说明
baseline字符串对应注册表中该端口的最新可用版本
port-version整数对应注册表中该端口的最新端口版本

Git 注册表中 baseline.json 文件示例​

若注册表中包含一个名为 foo、版本为 1.0.0#1 的端口，则 baseline.json 文件内容应如下：

{
  "default": {
    "foo": { 
      "baseline": "1.0.0", 
      "port-version": 1
    }
  }
}

Git 注册表中的版本文件结构​

versions 目录包含注册表中所有软件包版本的相关信息，以及从仓库历史中获取这些版本的方法。

每个软件包的版本文件是一个 JSON 文件，文件名与软件包名相同，存放于 versions 目录下的子目录中；该子目录命名规则为软件包名的首字母加一个连字符。 例如，pcre2 软件包的版本文件路径为 versions\p-\pcre2.json。

顶层字段​

名称类型说明
versions版本对象数组（VersionObject[]）版本对象数组，包含注册表历史中该端口每个版本的条目

版本对象（VersionObject）​

名称类型说明
git-tree字符串用于获取端口内容的 Git 树哈希值（SHA）
version
version-semver
version-date
version-string		字符串上游版本信息
port-version整数端口文件修订版本

Git 注册表版本文件示例​

{
  "versions": [
    {
      "git-tree": "963060040c3ca463d17136e39c7317efb15eb6a5",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "git-tree": "548c90710d59c174aa9ab10a24deb69f1d75ff8f",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

获取 git-tree 哈希值（SHA）​

kmpkg 利用 Git 的能力从提交历史中获取端口的特定版本，具体方式是根据端口版本文件中指定的 git-tree 对象从仓库中检索内容。

Git 注册表中的每个端口目录都关联一个唯一的 SHA 值（在版本文件中称为 git-tree）。该 SHA 值由目录内容计算得出；每当仓库中提交的变更修改了该目录，其 SHA 值都会重新计算。

只要知道目录对应的特定 SHA 值，Git 就能检索该目录在历史任意节点的内容。kmpkg 正是利用这一特性，将特定端口版本与其对应的 SHA 值（git-tree）建立索引。

要获取指定版本下端口目录的 SHA 值，可使用以下 Git 命令：

git -C <path/to/ports> ls-tree --format='%(objectname)' <commit sha> -- <portname>

示例：

git -C %KMPKG_ROOT%/ports ls-tree --format='%(objectname)' HEAD -- curl
6ef1763f3cbe570d6378632c9b5793479c37fb07

该命令返回当前版本（HEAD）下 curl 端口所在目录的 SHA 值。

可通过 git show <git-tree> 命令查看 git-tree 包含的内容：

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07
tree 6ef1763f3cbe570d6378632c9b5793479c37fb07

0005_remove_imp_suffix.patch
0020-fix-pc-file.patch
0022-deduplicate-libs.patch
cmake-config.patch
cmake-project-include.cmake
dependencies.patch
export-components.patch
portfile.cmake
redact-input-vars.diff
usage
kmpkg-cmake-wrapper.cmake
kmpkg.json

也可通过 git show <git-tree>:<file> 查看特定文件的内容：

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07:usage
curl is compatible with built-in CMake targets:

    find_package(CURL REQUIRED)
    target_link_libraries(main PRIVATE CURL::libcurl)

手动通过这些 Git 命令维护数据库文件是一项繁琐的工作。因此，我们建议使用 x-add-version 命令——只要仓库遵循推荐的注册表结构，该命令可自动完成上述流程。有关如何在 Git 注册表中发布端口的示例，请参阅教程：通过 Git 将软件包发布到私有 kmpkg 注册表一文。

文件系统注册表​

文件系统注册表中的基线文件结构​

顶层字段​

baseline.json 文件的顶层对象是一个字典，字典中的每个键为一个命名基线（named baseline）。基线应包含注册表中所有端口与其基线版本的映射关系。

名称类型说明
命名基线基线对象（BaselineObject）额外的基线，字段名对应基线名称

基线对象（BaselineObject）​

基线对象是一个字典，每个键对应注册表中的一个端口名，值为该端口的最新版本。

名称类型说明
端口名基线版本对象（BaselineVersionObject）端口名与其最新版本的映射关系

基线版本对象（BaselineVersionObject）​

名称类型说明
baseline字符串对应注册表中该端口的最新可用版本
port-version整数对应注册表中该端口的最新端口版本

文件系统注册表的基线文件结构与 Git 注册表 一致，唯一区别是文件系统注册表不要求必须存在 default 基线。

文件系统注册表中 baseline.json 文件示例​

{
  "2024-12-01": {
    "foo": {
      "baseline": "1.0.0",
      "port-version": 1
    }
  }
}

文件系统注册表中的版本文件结构​

versions 目录包含注册表中所有软件包版本的相关信息，以及从文件系统路径中获取这些版本的方法。

每个软件包的版本文件是一个 JSON 文件，文件名与软件包名相同，存放于 versions 目录下的子目录中；该子目录命名规则为软件包名的首字母加一个连字符。 例如，fmt 软件包的版本文件路径为 versions\f-\fmt.json。

顶层字段

名称类型说明
versions版本对象数组（VersionObject[]）版本对象数组，包含注册表中该端口每个版本的条目

版本对象（VersionObject）

名称类型说明
path字符串对应版本端口文件所在的文件系统路径
version
version-semver
version-date
version-string		字符串上游版本信息
port-version整数端口文件修订版本

指定注册表路径时，可使用 $ 字符引用注册表的根目录；也可直接使用绝对路径。

文件系统注册表版本文件示例​

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

后续步骤​

你可尝试以下任务：