Bazel 注册表

报告问题 查看源代码 每夜 build · 7.4 .

Bzlmod 通过从 Bazel 注册表(Bazel 模块的数据库)请求依赖项信息来发现依赖项。目前,Bzlmod 仅支持索引注册表,即采用特定格式的本地目录或静态 HTTP 服务器。

索引注册表

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

索引注册表必须遵循以下格式:

  • /bazel_registry.json:包含注册表元数据的 JSON 文件,例如:
    • mirrors:指定用于源归档的镜像列表。镜像网址是镜像本身与其 source.json 文件指定的模块的源网址(不含协议)的串联。例如,如果模块的源代码网址为 https://foo.com/bar/baz,并且 mirrors 包含 ["https://mirror1.com/", "https://example.com/mirror2/"],那么 Bazel 将按顺序尝试的网址为 https://mirror1.com/foo.com/bar/bazhttps://example.com/mirror2/foo.com/bar/baz,最后是原始源代码网址 https://foo.com/bar/baz
    • module_base_path:在 source.json 文件中为类型为 local_repository 的模块指定基路径
  • /modules:一个目录,其中包含此注册表中每个模块的子目录
  • /modules/$MODULE:一个目录,其中包含此模块每个版本的子目录以及:
    • metadata.json:包含模块相关信息的 JSON 文件,其中包含以下字段:
      • homepage:项目首页的网址
      • maintainers:JSON 对象列表,其中每个对象都对应注册表中的模块维护人员的信息。请注意,这不一定与项目的作者相同
      • versions:此注册表中可找到的此模块的所有版本的列表
      • yanked_versions:此模块的已移除版本的映射。键应为要撤消的版本,值应说明撤消版本的原因,最好包含指向更多信息的链接
  • /modules/$MODULE/$VERSION:包含以下文件的目录:
    • MODULE.bazel:此模块版本的 MODULE.bazel 文件
    • source.json:一个 JSON 文件,其中包含有关如何提取此模块版本源代码的信息
      • 默认类型为“archive”,表示一个 http_archive 代码库,其中包含以下字段:
        • url:源代码归档的网址
        • integrity:归档文件的子资源完整性校验和
        • strip_prefix:提取源归档文件时要剥离的目录前缀
        • patches:包含要应用于提取后归档文件的补丁文件的映射。补丁文件位于 /modules/$MODULE/$VERSION/patches 目录下。键是补丁文件名,值是补丁文件的完整性校验和
        • patch_strip:与 Unix patch--strip 参数相同。
        • archive_type:下载文件的归档类型(与 http_archive 上的 type 相同)。默认情况下,归档类型由网址的文件扩展名决定。如果文件没有扩展名,您可以明确指定以下任一扩展名:"zip""jar""war""aar""tar""tar.gz""tgz""tar.xz""txz""tar.zst""tzst"tar.bz2"ar""deb"
      • 您可以更改类型以使用 Git 代码库,并使用以下字段:
        • typegit_repository
        • https://bazel.build/rules/lib/repo/git 中所述的以下字段:
          • remote
          • commit
          • shallow_since
          • tag
          • init_submodules
          • verbose
          • strip_prefix
      • 可以将类型更改为使用表示 local_repository 代码库的本地路径,其中包含以下字段:
        • typelocal_path
        • path:代码库的本地路径,计算公式如下:
          • 如果 path 是绝对路径,则保持不变
          • 如果 path 是相对路径,而 module_base_path 是绝对路径,则解析为 <module_base_path>/<path>
          • 如果 pathmodule_base_path 都是相对路径,则解析为 <registry_path>/<module_base_path>/<path>。注册表必须在本地托管,并由 --registry=file://<registry_path> 使用。否则,Bazel 将抛出错误
    • patches/:包含补丁文件的可选目录,仅当 source.json 为“归档”类型时才使用

Bazel 中央注册表

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

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 将其重新添加回来。