Bazel 注册表

报告问题查看源代码 每夜 build · 8.1 · 8.0 · 7.5 · 7.4

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

索引注册表

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

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

/bazel_registry.json：一个可选的 JSON 文件，其中包含注册表的元数据。
/modules：一个目录，其中包含此注册表中每个模块的子目录
/modules/$MODULE：一个目录，其中包含名为 $MODULE 的每个模块版本的子目录，以及包含此模块元数据的 metadata.json 文件。
/modules/$MODULE/$VERSION：包含以下文件的目录：
- MODULE.bazel：此模块版本的 MODULE.bazel 文件。请注意，这是在 Bazel 的外部依赖项解析期间读取的 MODULE.bazel 文件，而不是源代码归档中的文件（除非存在非注册表替换项）。
- source.json：一个 JSON 文件，其中包含有关如何提取此模块版本源代码的信息
- patches/：包含补丁文件的可选目录，仅在 source.json 的类型为“归档”时使用
- overlay/：包含叠加层文件的可选目录，仅在 source.json 的类型为“归档”时使用

`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：字符串，源代码归档的网址
- integrity：一个字符串，归档文件的子资源完整性校验和
- strip_prefix：一个字符串，解压缩源代码归档文件时要剥离的目录前缀
- overlay：一个 JSON 对象，其中包含要叠加在提取的归档文件之上的叠加文件。补丁文件位于 /modules/$MODULE/$VERSION/overlay 目录下。键是叠加层文件名，值是叠加层文件的完整性校验和。叠加层会在补丁文件之前应用。
- patches：一个 JSON 对象，其中包含要应用于提取的归档文件的补丁文件。补丁文件位于 /modules/$MODULE/$VERSION/patches 目录下。键是补丁文件名，值是补丁文件的完整性校验和。补丁会在叠加文件之后应用。
- patch_strip：一个数字；与 Unix patch 的 --strip 参数相同。
- archive_type：一个字符串，表示下载文件的归档类型（与 http_archive 上的 type 相同）。
如果 type 为 git_repository，则此模块版本由 git_repository 代码库规则提供支持；系统会通过克隆 Git 代码库来提取该版本。
- 支持以下字段，这些字段会直接转发到底层 git_repository 代码库规则：remote、commit、shallow_since、tag、init_submodules、verbose 和 strip_prefix。
如果 type 为 local_path，则此模块版本由 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 中央注册库

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

Bazel 社区负责维护 BCR，欢迎贡献者提交拉取请求。请参阅 BCR 贡献指南。

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

选择注册表

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

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

默认情况下，使用 --registry 标志会停止使用 Bazel 中央注册库，但您可以通过添加 --registry=https://bcr.bazel.build 将其重新添加回来。