规则教程

Starlark 是一种类似 Python 的配置语言，最初是为在 Bazel 中使用而开发的，后来被其他工具采用。Bazel 的 BUILD 和 .bzl 文件是使用 Starlark 的一种方言编写的，该方言应被称为“构建语言”，但通常也被称为“Starlark”，尤其是在强调某个功能是使用构建语言表达的，而不是 Bazel 的内置或“原生”部分时。Bazel 通过许多与构建相关的函数（例如 glob、genrule、java_binary 等）增强了核心语言。

如需了解详情，请参阅 Bazel 和 Starlark 文档，并将 Rules 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)

虽然该规则不执行任何操作，但它的行为已经与其他规则一样：它有一个必需的名称，它支持 visibility、testonly 和 tags 等常见属性。

评估模型

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

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

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

foo_binary = rule(
    implementation = _foo_binary_impl,
)

print("bzl file evaluation")

和构建：

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 file measurement”。在评估 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 文件评估”，尽管在调用 bazel query 后，foo.bzl 的评估结果已缓存。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]))]

稍后再查看 DefaultInfo 和 depset 函数。现在，假设最后一行是用于选择规则输出的方式。

现在，运行 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.label 和 attr.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"])

进一步了解