Bazel 注册表

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

Bazel 通过从 Bazel 注册表（Bazel 模块数据库）请求依赖项的信息来发现依赖项。Bazel 仅支持一种类型的 注册表，即 _索引注册表_ ，它是遵循特定格式的本地目录或静态 HTTP 服务器。

索引注册表

索引注册表是本地目录或静态 HTTP 服务器，其中包含 有关模块列表的信息，包括模块的主页、维护人员、每个版本的 MODULE.bazel 文件，以及如何提取每个 版本的源代码。值得注意的是，它 不需要 提供源代码归档本身。

索引注册表必须采用以下格式：

  • /bazel_registry.json：一个可选的 JSON 文件 ，其中包含注册表的元数据。
  • /modules：一个目录，其中包含此 注册表中每个模块的子目录
  • /modules/$MODULE：一个目录，其中包含名为 $MODULE 的模块的每个版本 的子目录，以及包含此模块元数据的 metadata.json 文件。
  • /modules/$MODULE/$VERSION：一个目录，其中包含以下文件：
    • MODULE.bazel：此模块版本的 MODULE.bazel 文件。请注意，这是 Bazel 的外部依赖项解析期间读取的 MODULE.bazel 文件，而不是源代码归档中的文件（除非有 非注册表 替换）。另请注意，最好使用此文件来设置版本的发布，并避免在源代码归档 MODULE.bazel 文件中执行此操作。如需详细了解模块 版本控制，请参阅常见问题解答。
    • source.json：一个 JSON 文件，其中包含有关如何 提取此模块版本的源代码的信息
    • patches/：一个可选目录，其中包含补丁文件，仅在 source.json具有“archive”类型时使用
    • overlay/：一个可选目录，其中包含叠加层文件，仅在 source.json 具有“archive”类型时使用

bazel_registry.json

bazel_registry.json 是一个可选文件，用于指定适用于 整个注册表的元数据。它可以包含以下字段：

  • mirrors：一个字符串数组，用于指定要用于 源代码归档的镜像列表。
    • 镜像网址是镜像本身与 source.json文件（不含 协议）指定的模块的源代码网址的串联。例如，如果模块的源代码网址为 https://foo.com/bar/baz，并且 mirrors 包含 ["https://mirror1.com/", "https://example.com/mirror2/"]，则 Bazel 将按顺序尝试的 网址为 https://mirror1.com/foo.com/bar/baz、 https://example.com/mirror2/foo.com/bar/baz，最后是原始 源代码网址本身 https://foo.com/bar/baz。
  • module_base_path：一个字符串，用于指定 source.json 文件中具有 local_path 类型的模块的基本路径

metadata.json

metadata.json 是一个可选的 JSON 文件，其中包含有关 模块的信息，具有以下字段：

  • versions：一个字符串数组，每个字符串表示此注册表中可用的模块 版本。此数组应与 模块目录的子项匹配。
  • yanked_versions：一个 JSON 对象，用于指定此模块的 撤消 版本。键 应是要撤消的版本，值应是撤消该版本的原因说明 ，最好包含指向更多信息的链接 。

请注意，BCR 需要 metadata.json 文件中的更多信息。

source.json

source.json 是一个必需的 JSON 文件，其中包含有关如何提取 特定模块版本的信息。此文件的架构取决于其 type 字段，该字段默认为 archive。

  • 如果 type 为 archive（默认值），则此模块版本由 http_archive 代码库规则提供支持；它通过从给定网址下载归档并提取其内容来提取。它 支持以下字段：
    • url：一个字符串，即源代码归档的网址
    • mirror_urls：一个字符串列表，即源代码归档的镜像网址。 这些网址在 url 之后按顺序尝试，作为备份。
    • integrity：一个字符串，即归档的子资源 完整性校验和
    • strip_prefix：一个字符串，即提取源代码归档时要剥离的目录前缀
    • overlay：一个 JSON 对象，其中包含要叠加在 提取的归档之上的叠加层文件。补丁文件位于 /modules/$MODULE/$VERSION/overlay 目录下。键是 叠加层文件名，值是 叠加层文件的完整性校验和。叠加层在补丁文件之前应用。
    • patches：一个 JSON 对象，其中包含要应用于 提取的归档的补丁文件。补丁文件位于 /modules/$MODULE/$VERSION/patches 目录下。键是 补丁文件名，值是 补丁文件的完整性校验和。补丁在叠加层文件之后应用，并按照它们在 patches 中出现的顺序应用。
    • patch_strip：一个数字；与 Unix patch 的 --strip 实参相同。
    • archive_type：一个字符串，即下载文件的归档类型（与 type 上的 http_archive 相同）。
  • 如果 type 为 git_repository，则此模块版本由 git_repository 代码库规则提供支持；它 通过克隆 Git 代码库来提取。
    • 支持以下字段，这些字段会直接转发到底层 git_repository代码库规则：remote、commit、 shallow_since、tag、init_submodules、verbose 和 strip_prefix。
  • 如果 type 为 local_path，则此模块版本由 a local_repository 代码库规则提供支持； 它会符号链接到本地磁盘上的目录。它支持以下 字段：
    • path：代码库的本地路径，计算方式如下：
      • 如果 path 是绝对路径，则保持不变
      • 如果 path 是相对路径，而 module_base_path 是 绝对路径，则解析为 <module_base_path>/<path>
      • 如果 path 和 module_base_path 都是相对路径，则 解析为 <registry_path>/<module_base_path>/<path>。 注册表必须托管在本地，并由 --registry=file://<registry_path> 使用。否则，Bazel 将 抛出错误

Bazel Central Registry

https://bcr.bazel.build/ 处的 Bazel Central Registry (BCR) 是一个索引 注册表，其内容由 GitHub 代码库 bazelbuild/bazel-central-registry 提供支持。您可以使用 https://registry.bazel.build/ 处的 Web 前端浏览其内容 。

Bazel 社区维护 BCR，欢迎贡献者提交 pull 请求。请参阅 BCR 贡献 准则。

除了遵循普通索引注册表的格式之外，BCR 还要求 为每个模块版本提供 presubmit.yml 文件 (/modules/$MODULE/$VERSION/presubmit.yml)。此文件指定了一些基本的 构建和测试目标，您可以使用这些目标来检查此模块 版本的有效性。BCR 的 CI 流水线也使用此文件来确保模块之间的互操作性 。

选择注册表

可重复的 Bazel 标志 --registry 可用于指定要从中请求模块的 注册表列表，因此您可以将项目设置为从第三方或内部注册表提取 依赖项。较早的注册表优先。为方便起见，您可以将 --registry 标志列表放在项目的 .bazelrc 文件中。

如果您的注册表托管在 GitHub 上（例如，作为 bazelbuild/bazel-central-registry的分支），则您的 --registry 值需要 下的原始 GitHub 地址。raw.githubusercontent.com例如，在 main 分支的 my-org 分支上，您需要设置 --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/。

使用 --registry 标志会阻止默认使用 Bazel Central Registry，但您可以通过添加 --registry=https://bcr.bazel.build 将其添加回来。