2022 年 BazelCon 将于 11 月 16 日至 17 日在纽约和线上举办。
立即报名!

代码库规则

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本页面介绍了如何创建代码库规则,并提供了相关示例供您了解详情。

外部代码库是一种规则,只能在 WORKSPACE 文件中使用,并且在 Bazel 的加载阶段启用非封闭操作。每个外部代码库规则都会创建自己的工作区,其中包含自己的 BUILD 文件和工件。它们可用于依赖第三方库(例如 Maven 打包的库)以及生成特定于运行 Bazel 的主机的 BUILD 文件。

代码库规则创建

.bzl 文件中,使用 repository_rule 函数创建新的代码库规则并将其存储在全局变量中。

自定义代码库规则可以像原生代码库规则一样使用。它具有必需的 name 属性,并且其 build 文件中存在的每个目标可以称为 @<name>//package:target,其中 <name>name 属性的值。

当您明确构建规则时,或者规则是构建的依赖项时,系统会加载规则。在这种情况下,Bazel 将执行其 implementation 函数。此函数介绍了如何创建代码库、其内容和 BUILD 文件。

特性

特性是一个规则参数,例如 urlsha256。定义存储库规则时,您必须列出特性及其类型。

local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={"path": attr.string(mandatory=True)})

如需访问特性,请使用 repository_ctx.attr.<attribute_name>

所有 repository_rule 都有隐式定义的属性(就像构建规则一样)。两个隐式属性是 name(就像构建规则一样)和 repo_mapping。代码库规则的名称可通过 repository_ctx.name 访问。repo_mapping 的含义与原生代码库规则 local_repositorynew_local_repository 相同。

如果属性名称以 _ 开头,则该属性是私有属性,用户无法对其进行设置。

实现函数

每个代码库规则都需要一个 implementation 函数。它包含规则的实际逻辑,并会在加载阶段严格执行。

该函数只有一个输入参数:repository_ctx。该函数会返回 None 以表示规则在指定参数下可重现,或者返回包含一组参数的字典,将规则转换为可生成相同代码的可重现规则。例如,对于跟踪表示返回特定提交标识符而不是最初指定的浮动分支的 git 代码库的规则。

输入参数 repository_ctx 可用于访问属性值和非封闭函数(查找二进制文件、执行二进制文件、在代码库中创建文件或从互联网下载文件)。如需了解详情,请参阅。示例:

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

实现函数何时执行?

如果将代码库声明为 local,那么在依赖项图(包括 WORKSPACE 文件本身)中的某个依赖项中发生变化会导致执行相应函数。

如果请求的依赖项缺失,则可以重启实现函数。在解析依赖项后,系统会重新执行实现函数。为避免不必要的重启(费用高昂,因为网络访问可能需要重复),系统会预先提取标签参数,前提是所有标签参数都可以解析为现有文件。请注意,解析字符串中的路径或标签仅在函数执行期间构建时,仍可能会导致重启。

最后,对于非 local 代码库,只有以下依赖项的更改可能会导致重启:

  • 定义代码库规则所需的 .bzl 文件。
  • WORKSPACE 文件中声明代码库规则。
  • 使用 repository_rule 函数的 environ 属性声明的任何环境变量的值。可以使用 --action_env 标志在命令行中强制执行这些环境变量的值(但此标志会使 build 的每项操作失效)。
  • 标签使用和引用的任何文件的内容(例如,//mypkg:label.txt,而不是 mypkg/label.txt)。

强制重新提取外部代码库

有时,外部代码库可能会过时,而无需对其定义或依赖项进行任何更改。例如,存储库的源可以紧跟第三方代码库的特定分支,并且该分支上提供了新的提交内容。在这种情况下,您可以通过调用 bazel sync 要求 bazel 无条件地重新提取所有外部代码库。

此外,某些规则会检查本地机器,如果本地机器升级,该规则可能会过时。在这里,您可以要求 bazel 仅重新提取 repository_rule 定义设置了 configure 特性的外部代码库,请使用 bazel sync --configure

示例

  • C++ 自动配置的工具链:它会使用代码库规则,通过查找本地 C++ 编译器、环境和 C++ 编译器支持的标志,为 Bazel 自动创建 C++ 配置文件。

  • Go 代码库使用多个 repository_rule 来定义使用 Go 规则所需的依赖项列表。

  • rules_jvm_external 默认创建一个名为 @maven 的外部代码库,该代码库会为传递依赖项树中的每个 Maven 工件生成构建目标。