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

规则教程

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

Starlark 是一种类似于 Python 的配置语言,最初是在 Bazel 中开发的,后来被其他工具采用。Bazel 的 BUILD.bzl 文件是用 Starlark 的方言(通常称为“Build Language”)编写的,尽管它通常简称为“Starlark”,特别是在强调功能以 build 语言表示,而不是作为 Bazel 的内置或“原生”部分。Bazel 使用许多与构建相关的函数(例如 globgenrulejava_binary 等)增强了核心语言。

如需了解详情,请参阅 BazelStarlark 文档,以及规则 SIG 模板新规则集的起点。

空规则

如需创建您的第一条规则,请创建文件 foo.bzl

def _foo_binary_impl(ctx):
    pass

foo_binary = rule(
    implementation = _foo_binary_impl,
)

调用 rule 函数时,您必须定义回调函数。逻辑将转到相应位置,但现在您可以将该函数留空。ctx 参数提供有关目标的信息。

您可以加载规则,并通过 BUILD 文件使用它。

在同一目录中创建一个 BUILD 文件:

load(":foo.bzl", "foo_binary")

foo_binary(name = "bin")

现在,可以构建目标:

$ bazel build bin
INFO: Analyzed target //:bin (2 packages loaded, 17 targets configured).
INFO: Found 1 target...
Target //:bin up-to-date (nothing to build)

虽然该规则不执行任何操作,但其行为方式与其他规则相同:它具有强制性名称,并且支持 visibilitytestonlytags 等常见特性。

评估模型

在继续之前,请务必了解代码的评估方式。

使用一些输出语句更新 foo.bzl

def _foo_binary_impl(ctx):
    print("analyzing", ctx.label)

foo_binary = rule(
    implementation = _foo_binary_impl,
)

print("bzl file evaluation")

和 build:

load(":foo.bzl", "foo_binary")

print("BUILD file")
foo_binary(name = "bin1")
foo_binary(name = "bin2")

ctx.label 对应于要分析的目标的标签。ctx 对象有许多有用的字段和方法;您可以在 API 参考文档中找到详尽的列表。

查询代码:

$ bazel query :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
//:bin2
//:bin1

请观察以下几点:

  • 首先输出“bzl 文件评估”。在评估 BUILD 文件之前,Bazel 会评估它加载的所有文件。如果有多个 BUILD 文件加载 foo.bzl,您将只会看到一次“bzl 文件评估”,因为 Bazel 会缓存评估结果。
  • 回调函数 _foo_binary_impl 不会被调用。Bazel 查询会加载 BUILD 文件,但不会分析目标。

如需分析目标,请使用 cquery(“配置的查询”)或 build 命令:

$ bazel build :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin1
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin2
INFO: Analyzed 2 targets (0 packages loaded, 0 targets configured).
INFO: Found 2 targets...

如您所见,_foo_binary_impl 现在被调用了两次 - 每个目标调用一次。

一些读者会注意到“bzl 文件评估”会再次输出,尽管 foo.bzl 的评估在调用 bazel query 之后被缓存。Bazel 不会重新评估代码,而只会重放打印事件。无论缓存状态如何,您都会获得相同的输出。

创建文件

为了使规则更实用,请更新规则以生成文件。首先,声明该文件,并为其命名。在此示例中,请创建一个与目标同名的文件:

ctx.actions.declare_file(ctx.label.name)

如果您现在运行 bazel build :all,将收到错误消息:

The following files have no generating action:
bin2

每次声明文件时,您都必须通过创建操作来告知 Bazel 如何生成此文件。使用 ctx.actions.write 创建一个包含指定内容的文件。

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello\n",
    )

代码有效,但不会执行任何操作:

$ bazel build bin1
Target //:bin1 up-to-date (nothing to build)

ctx.actions.write 函数注册了一个操作,它会指示 Bazel 如何生成文件。但在实际请求该文件之前,Bazel 不会创建该文件。因此,最后要做的是告知 Bazel 文件是规则的输出,而不是规则实现中使用的临时文件。

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello!\n",
    )
    return [DefaultInfo(files = depset([out]))]

稍后请查看 DefaultInfodepset 函数。现在,假设最后一行是选择规则输出的方式。

现在,运行 Bazel:

$ bazel build bin1
INFO: Found 1 target...
Target //:bin1 up-to-date:
  bazel-bin/bin1

$ cat bazel-bin/bin1
Hello!

您已成功生成文件!

特性

为了使规则更实用,请使用 attr 模块添加新特性并更新规则定义。

添加一个名为 username 的字符串属性:

foo_binary = rule(
    implementation = _foo_binary_impl,
    attrs = {
        "username": attr.string(),
    },
)

接下来,在 BUILD 文件中进行设置:

foo_binary(
    name = "bin",
    username = "Alice",
)

要访问回调函数中的值,请使用 ctx.attr.username。例如:

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello {}!\n".format(ctx.attr.username),
    )
    return [DefaultInfo(files = depset([out]))]

请注意,您可以将属性设为强制性属性或设置默认值。查看 attr.string 的文档。您还可以使用其他类型的属性,例如布尔值整数列表

依赖项

依赖项属性,例如attr.labelattr.label_list,从拥有该特性的目标声明到其属性值出现在该目标的目标中的依赖项。此类特性构成了目标图的基础。

BUILD 文件中,目标标签显示为字符串对象,例如 //pkg:name。在实现函数中,可通过 Target 对象访问目标。例如,使用 Target.files 查看目标返回的文件。

多个文件

默认情况下,只有规则创建的目标(例如 foo_library() 目标)可以显示为依赖项。如果您希望该属性接受输入文件(例如代码库中的源文件)的目标,可以执行以下操作:allow_files并指定接受的文件扩展名列表(或True以允许任何文件扩展名):

"srcs": attr.label_list(allow_files = [".java"]),

您可以使用 ctx.files.<attribute name> 访问文件列表。例如,可以通过以下函数访问 srcs 属性中的文件列表:

ctx.files.srcs

单个文件

如果您只需要一个文件,请使用 allow_single_file

"src": attr.label(allow_single_file = [".java"])

然后,您可以通过 ctx.file.<attribute name> 访问此文件:

ctx.file.src

使用模板创建文件

您可以创建基于模板生成 .cc 文件的规则。此外,您还可以使用 ctx.actions.write 输出在规则实现函数中构造的字符串,但这样有两个问题。首先,随着模板变得越来越大,将其放入单独的文件中会变得更加高效,并避免在分析阶段构建大型字符串。第二,使用单独的文件更方便用户。请改为使用 ctx.actions.expand_template,它用于替换模板文件。

创建 template 属性以声明对模板文件的依赖项:

def _hello_world_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name + ".cc")
    ctx.actions.expand_template(
        output = out,
        template = ctx.file.template,
        substitutions = {"{NAME}": ctx.attr.username},
    )
    return [DefaultInfo(files = depset([out]))]

hello_world = rule(
    implementation = _hello_world_impl,
    attrs = {
        "username": attr.string(default = "unknown person"),
        "template": attr.label(
            allow_single_file = [".cc.tpl"],
            mandatory = True,
        ),
    },
)

用户可以使用如下规则:

hello_world(
    name = "hello",
    username = "Alice",
    template = "file.cc.tpl",
)

cc_binary(
    name = "hello_bin",
    srcs = [":hello"],
)

如果您不想向最终用户公开模板,但始终使用相同的模板,则可以设置默认值并将特性设为不公开:

    "_template": attr.label(
        allow_single_file = True,
        default = "file.cc.tpl",
    ),

以下划线开头的特性为不公开特性,不能在 BUILD 文件中设置。该模板现在是一个隐式依赖项:每个 hello_world 目标都依赖于此文件。不要忘记通过更新 BUILD 文件并使用 exports_files 让其他软件包可以看到此文件:

exports_files(["file.cc.tpl"])

更完善