Starlark 是一种类似于 Python 的配置语言,最初是在 Bazel 中使用,之后被其他工具采用。Bazel 的 BUILD
和 .bzl
文件是用 Starlark 的方言(通常称为“build 语言”)编写的,但它通常简称为“Starlark”,尤其是在强调某项功能用 Build 语言表示而不是作为 Bazel 的内置或“原生”部分时。Bazel 使用众多与构建相关的函数(例如 glob
、genrule
、java_binary
等)来增强核心语言。
如需了解详情,请参阅 Bazel 和 Starlark 文档,并以规则 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 文件评估”。在评估
BUILD
文件之前,Bazel 会评估它加载的所有文件。如果有多个BUILD
文件在加载 foo.bzl,您将只会看到一次“bzl 文件评估”,因为 Bazel 会缓存评估结果。 - 系统不会调用回调函数
_foo_binary_impl
。Bazel 查询会加载BUILD
文件,但不会分析目标。
如需分析目标,请使用 cquery
(“配置的查询”)或 build
命令:
$ bazel build :all
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 文件评估”和“BUILD 文件”都不会再次输出,因为在调用 bazel query
之后,系统会缓存 foo.bzl
的计算结果。Bazel 仅在实际执行 print
时才发出语句。
创建文件
为了使规则更实用,请更新规则以生成文件。首先,声明文件并为其命名。在此示例中,请创建一个与目标同名的文件:
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"])