创建注册表

项目
01/10/2024

有关使用注册表的信息，请参阅使用注册表。

概述

注册表是端口及其版本的集合。如果要创建自己的注册表：git 注册表和文件系统注册表，有两个主要实现方式。

Git 注册表是简单的 git 存储库，可通过 Git 存储库的正常机制公开或私密共享。例如，vcpkg 存储库是 git 注册表。

文件系统注册表设计为不只是测试地面。因为它们实际上位于文件系统上，共享它们的唯一方法就是通过共享目录。但是，文件系统注册表可以作为表示非 git 版本控制系统中保留的注册表的一种方式，假设有某种方法可以将注册表置于磁盘上。

预计随着时间的发展，会出现越来越多的注册表类型；如果想要支持喜爱的公共版本控制系统的内置注册，请随时创建 PR。

注册表的基本结构如下所示：

在历史记录中某个时间点被认为是“最新”的版本集，称之为“基线”。
所有端口的所有版本集，以及可在何处查找注册表中的每个端口。

Git 注册表

按照本文档的说明进行操作时，利用一个可用示例作为参考会有所帮助。我们已经编写好一个示例并将其放在这里：

Microsoft/vcpkg-docs：vcpkg 注册表。

所有 git 注册表都必须有一个 versions/baseline.json 文件。此文件包含特定提交时的“最新版本”集。它的布局为仅包含 "default" 文件的顶级对象。此字段应包含对象映射端口名称到当前为最新版本的版本。

下面是有效 baseline.json 的示例：

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

versions 目录包含注册表中包含哪些包的哪些版本，以及这些版本的存储位置的相关信息。注册表的其余部分只是用作 vcpkg 的后备存储：只有 versions 目录里的内容才会用于指引 vcpkg 如何查看注册表。

注册表中的每个端口在版本目录中都应作为 <first letter of port>-/<name of port>.json 存在；换句话说，与 kitten 端口相关的信息应位于 versions/k-/kitten.json 之中。应该是一个仅包含一个字段的顶级对象："versions"。此字段应包含一组版本对象：

有问题的端口版本；应与 vcpkg.json 文件一模一样，包括版本字段和 "port-version"。
"git-tree" 字段是 git 树；换句话说，就是当写入 git rev-parse COMMIT-ID:path/to/port 时所获得的内容。

具有已弃用 CONTROL 文件的端口的版本字段为 "version-string"。

警告

使用注册表时的一大禁忌就是绝不能更改版本。更新到版本更高的注册表之后，绝不能删除或更改现有版本。必须始终安全地更新注册表。

下面是一个有效版本数据库的示例，其中 kitten 端口具有一个版本：

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

通常来说，将端口目录放在哪里都可以。但在 vcpkg 中，习惯遵循内置 vcpkg 注册表的做法：即应将 kitten 端口放置在 ports/kitten 中。

警告

另外还要记住一点，在更新注册表时，所有以前的版本也应该做到可以访问。由于用户会将自己的基线设置为提交 ID，该提交 ID 必须始终存在，并且可从你的 HEAD 提交访问到（实际是提取到）。这意味着 HEAD 提交应是以前所有 HEAD 提交的子级。

内置注册表

内置注册表是特殊的 Git 注册表。内置注册表无需从远程 URL 提取，而是咨询 $VCPKG_ROOT/.git vcpkg 克隆的目录。它们使用当前已签出的 $VCPKG_ROOT/versions 目录作为版本控制信息的源。

添加新版本

创建新版本的端口涉及一些 git 技巧。首先要进行一些更改，根据需要更新 "port-version" 和常规版本字段，然后再使用 overlay-ports 进行测试：

vcpkg install kitten --overlay-ports=ports/kitten。

完成测试后，需要确保目录位于 git 的 purview 下。你将通过创建临时提交来执行此操作：

> git add ports/kitten
> git commit -m 'temporary commit'

然后，获取目录的 git 树 ID：

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

然后，可以将此版本添加到版本数据库。在 versions/k-/kitten.json 顶部可以添加（假设要添加版本 2.6.3#0）：

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

然后，还要将 versions/baseline.json 修改为新版本：

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

并修改当前提交：

> git commit --amend

然后共享出去！

Filesystem 注册表

按照本文档的说明进行操作时，利用一个可用示例作为参考会有所帮助。我们已经编写好一个示例并将其放在这里：

Filesystem 注册表示例。

所有 Filesystem 注册表都必须有一个 versions/baseline.json 文件。此文件包含特定版本的注册表的“最新版本”集。它布局为顶级对象，其中包含从版本名称到“基线对象”的映射，该映射将端口名称映射到该版本的注册表版本被视为“最新”。

Filesystem 注册表需要确定版本控制方案。与具有隐性注册表版本控制方案的 git 注册表不同，filesystem 注册表不能依赖于这里的版本控制系统。执行每日发布是一个选项，可以让“版本”有日期。

警告

基线一经发布便不得修改。如果要更改或更新版本，需要在 baseline.json 文件中创建新的基线。

下面是一个有效的 baseline.json 示例，适用于已确定其版本的日期的注册表：

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

有问题的端口版本；应与 vcpkg.json 文件一模一样，包括版本字段和 "port-version"。
"path" 字段：根位于注册表 base，端口目录的相对目录（换句话说，就是 versions 所在的目录）。应类似于 "$/path/to/port/dir

具有已弃用 CONTROL 文件的端口的版本字段为 "version-string"。

通常来说，将端口目录放在哪里都可以。但在 vcpkg 中，习惯的做法与内置 vcpkg 注册表的做法有些类似：即应将版本 x.y.z 的 kitten 端口放置在 ports/kitten/x.y.z 中，端口版本后跟如你所见（虽然由于 # 并不是好的字符供文件名使用，可能使用 _）。

警告

使用注册表时的一大禁忌就是绝不能更改版本。不应删除或更改现有版本。对注册表所做的更改不应更改下游用户的行为。

下面是一个有效版本数据库的示例，其中 kitten 端口具有一个版本：

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

添加新版本

与 git 注册表不同，将新版本添加到 filesystem 注册表主要涉及大量复制。首先要做的是将最新版本的端口复制到新版本目录中，根据需要更新版本和 "port-version" 字段，然后使用 overlay-ports：

vcpkg install kitten --overlay-ports=ports/kitten/new-version。

完成测试后，可以将此新版本添加到 versions/k-/kitten.json 的顶部：

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

然后，还需要修改 versions/baseline.json 新版本（请记住不要修改现有基线）：

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

成功了！

通过

创建注册表

概述

Git 注册表

内置注册表

添加新版本

Filesystem 注册表

添加新版本

其他资源