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/baz
、https://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 对象列表,每个 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
:与 Unixpatch
的--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 代码库,其中包含以下字段:
type
:git_repository
- 以下字段(如 https://bazel.build/rules/lib/repo/git 中所述):
remote
commit
shallow_since
tag
init_submodules
verbose
strip_prefix
- 可将类型更改为使用表示
local_repository
代码库的本地路径,其中包含以下字段:type
:local_path
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 会在
- 如果
- 默认类型为“archive”,表示一个
patches/
:包含补丁文件的可选目录,仅在source.json
为“archive”类型时使用
Bazel 中央注册表
https://bcr.bazel.build/ 上的 Bazel Central Registry (BCR) 是一个索引注册表,其内容由 GitHub 代码库 bazelbuild/bazel-central-registry
提供支持。您可以使用 Web 前端 (https://registry.bazel.build/) 浏览其内容。
BCR 由 Bazel 社区维护,欢迎贡献者提交拉取请求。请参阅 BCR 贡献准则。
除了遵循普通索引注册表的格式之外,BCR 还需要为每个模块版本 (/modules/$MODULE/$VERSION/presubmit.yml
) 提供一个 presubmit.yml
文件。此文件指定了一些基本的 build 和测试目标,可用于检查此模块版本的有效性。BCR 的 CI 流水线也使用此机制来确保模块之间的互操作性。
选择注册表
可重复的 Bazel 标志 --registry
可用于指定要从中请求模块的注册表列表,以便您将项目设置为从第三方或内部注册表提取依赖项。较早的域名注册管理机构会优先。为方便起见,您可以将一系列 --registry
标志放入项目的 .bazelrc
文件中。
如果您的注册表托管在 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 Central Registry,但您可以通过添加 --registry=https://bcr.bazel.build
将其重新添加。