本页介绍了 Starlark 配置(Bazel 的 API,用于自定义项目构建方式)的优势和基本用法。其中包括如何定义 build 设置,并提供了示例。
这样一来,您就可以:
- 为您的项目定义自定义标志,从而不再需要
--define
- 编写转换,以便在与其父级(例如
--compilation_mode=opt
或--cpu=arm
)不同的配置中配置依赖项 - 将更好的默认值融入规则(例如,使用指定的 SDK 自动构建
//my:android_app
)
等等,所有这些都可以完全通过 .bzl 文件实现(无需 Bazel 版本)。如需查看示例,请参阅 bazelbuild/examples
代码库。
用户定义的 build 设置
构建设置是单个配置信息。将配置视为键值对映射。设置 --cpu=ppc
和 --copt="-DFoo"
会生成类似于 {cpu: ppc, copt: "-DFoo"}
的配置。每个条目都是一个 build 设置。
cpu
和 copt
等传统标志是原生设置,其键在原生 Bazel Java 代码中定义,其值也在原生 Bazel Java 代码中设置。Bazel 用户只能通过命令行和其他原生维护的 API 进行读取和写入。更改原生标志以及公开这些标志的 API 需要一个 Bazel 版本。用户定义的构建设置在 .bzl
文件中定义(因此不需要 bazel 版本来注册更改)。您还可以通过命令行设置这些值(如果它们被指定为 flags
,请参阅下文),但也可以通过用户定义的转换进行设置。
定义 build 设置
build_setting
rule()
参数
构建设置与任何其他规则一样,是使用 Starlark rule()
函数的 build_setting
属性进行区分的。
# example/buildsettings/build_settings.bzl
string_flag = rule(
implementation = _impl,
build_setting = config.string(flag = True)
)
build_setting
属性接受一个用于指定 build 设置类型的函数。该类型仅限于一组基本 Starlark 类型,例如 bool
和 string
。如需了解详情,请参阅 config
模块文档。您可以在规则的实现函数中执行更复杂的类型检查。详情请见下文。
config
模块的函数接受一个可选的布尔参数 flag
,该参数默认设置为 false。如果 flag
设置为 true,用户可以在命令行上设置 build 设置,规则编写者也可以通过默认值和转换在内部设置 build 设置。并非所有设置都应由用户设置。例如,如果您(作为规则编写者)有某些调试模式想要在测试规则中启用,但不希望用户能够在其他非测试规则中不加区分地启用该功能。
使用 ctx.build_setting_value
与所有规则一样,构建设置规则也有实现函数。您可以通过 ctx.build_setting_value
方法访问 build 设置的基本 Starlark 类型值。此方法仅适用于 build 设置规则的 ctx
对象。这些实现方法可以直接转发 build 设置值,也可以对其执行其他工作,例如类型检查或更复杂的结构体创建。您可以通过以下方式实现 enum
类型的 build 设置:
# example/buildsettings/build_settings.bzl
TemperatureProvider = provider(fields = ['type'])
temperatures = ["HOT", "LUKEWARM", "ICED"]
def _impl(ctx):
raw_temperature = ctx.build_setting_value
if raw_temperature not in temperatures:
fail(str(ctx.label) + " build setting allowed to take values {"
+ ", ".join(temperatures) + "} but was set to unallowed value "
+ raw_temperature)
return TemperatureProvider(type = raw_temperature)
temperature = rule(
implementation = _impl,
build_setting = config.string(flag = True)
)
定义多集字符串标志
字符串设置有一个额外的 allow_multiple
参数,可用于在命令行或 bazelrcs 中多次设置该标志。它们的默认值仍使用字符串类型的属性进行设置:
# example/buildsettings/build_settings.bzl
allow_multiple_flag = rule(
implementation = _impl,
build_setting = config.string(flag = True, allow_multiple = True)
)
# example/BUILD
load("//example/buildsettings:build_settings.bzl", "allow_multiple_flag")
allow_multiple_flag(
name = "roasts",
build_setting_default = "medium"
)
该标志的每个设置都被视为一个值:
$ bazel build //my/target --//example:roasts=blonde \
--//example:roasts=medium,dark
上述代码会解析为 {"//example:roasts": ["blonde", "medium,dark"]}
,ctx.build_setting_value
会返回列表 ["blonde", "medium,dark"]
。
实例化 build 设置
使用 build_setting
参数定义的规则具有隐式必需的 build_setting_default
属性。此属性采用的类型与 build_setting
参数声明的类型相同。
# example/buildsettings/build_settings.bzl
FlavorProvider = provider(fields = ['type'])
def _impl(ctx):
return FlavorProvider(type = ctx.build_setting_value)
flavor = rule(
implementation = _impl,
build_setting = config.string(flag = True)
)
# example/BUILD
load("//example/buildsettings:build_settings.bzl", "flavor")
flavor(
name = "favorite_flavor",
build_setting_default = "APPLE"
)
预定义的设置
Skylib 库包含一组预定义设置,您可以将其实例化,而无需编写自定义 Starlark。
例如,如需定义接受一组有限字符串值的设置,请执行以下操作:
# example/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
string_flag(
name = "myflag",
values = ["a", "b", "c"],
build_setting_default = "a",
)
如需查看完整列表,请参阅常见 build 设置规则。
使用 build 设置
取决于 build 设置
如果目标需要读取一段配置信息,可以通过常规属性依赖项直接依赖于 build 设置。
# example/rules.bzl
load("//example/buildsettings:build_settings.bzl", "FlavorProvider")
def _rule_impl(ctx):
if ctx.attr.flavor[FlavorProvider].type == "ORANGE":
...
drink_rule = rule(
implementation = _rule_impl,
attrs = {
"flavor": attr.label()
}
)
# example/BUILD
load("//example:rules.bzl", "drink_rule")
load("//example/buildsettings:build_settings.bzl", "flavor")
flavor(
name = "favorite_flavor",
build_setting_default = "APPLE"
)
drink_rule(
name = "my_drink",
flavor = ":favorite_flavor",
)
语言可能需要创建一组规范的 build 设置,该语言的所有规则都依赖于这些设置。虽然 fragments
的原生概念不再以硬编码对象的形式存在于 Starlark 配置世界中,但转换此概念的一种方法是使用一组常见的隐式属性。例如:
# kotlin/rules.bzl
_KOTLIN_CONFIG = {
"_compiler": attr.label(default = "//kotlin/config:compiler-flag"),
"_mode": attr.label(default = "//kotlin/config:mode-flag"),
...
}
...
kotlin_library = rule(
implementation = _rule_impl,
attrs = dicts.add({
"library-attr": attr.string()
}, _KOTLIN_CONFIG)
)
kotlin_binary = rule(
implementation = _binary_impl,
attrs = dicts.add({
"binary-attr": attr.label()
}, _KOTLIN_CONFIG)
在命令行中使用构建设置
与大多数原生标志类似,您可以使用命令行设置标记为标志的 build 设置。build 设置的名称是使用 name=value
语法的完整目标路径:
$ bazel build //my/target --//example:string_flag=some-value # allowed
$ bazel build //my/target --//example:string_flag some-value # not allowed
支持特殊的布尔语法:
$ bazel build //my/target --//example:boolean_flag
$ bazel build //my/target --no//example:boolean_flag
使用 build 设置别名
您可以为构建设置目标路径设置别名,以便更轻松地在命令行中阅读。别名与原生标志的运作方式类似,也使用双短划线选项语法。
通过向 .bazelrc
添加 --flag_alias=ALIAS_NAME=TARGET_PATH
来设置别名。例如,如需将别名设置为 coffee
,请使用以下代码:
# .bazelrc
build --flag_alias=coffee=//experimental/user/starlark_configurations/basic_build_setting:coffee-temp
最佳实践:多次设置别名会导致最近一个别名优先。请使用唯一的别名名称,以避免意外的解析结果。
如需使用别名,请输入别名,而不是输入 build 设置目标路径。
在用户的 .bazelrc
中设置上述 coffee
示例:
$ bazel build //my/target --coffee=ICED
来替代
$ bazel build //my/target --//experimental/user/starlark_configurations/basic_build_setting:coffee-temp=ICED
最佳实践:虽然可以在命令行中设置别名,但将其保留在 .bazelrc
中可以减少命令行混乱。
标签类型的 build 设置
与其他 build 设置不同,标签类型的设置无法使用 build_setting
规则参数进行定义。bazel 具有两条内置规则:label_flag
和 label_setting
。这些规则会将设置了 build 设置的实际目标的提供程序转发给 build 系统。label_flag
和 label_setting
可以通过转场读取/写入,并且用户可以像其他 build_setting
规则一样设置 label_flag
。它们之间的唯一区别是无法自定义。
标签类型的设置最终将取代延迟绑定的默认值的功能。延迟绑定的默认属性是 Label 类型的属性,其最终值可能会受到配置的影响。在 Starlark 中,这将取代 configuration_field
API。
# example/rules.bzl
MyProvider = provider(fields = ["my_field"])
def _dep_impl(ctx):
return MyProvider(my_field = "yeehaw")
dep_rule = rule(
implementation = _dep_impl
)
def _parent_impl(ctx):
if ctx.attr.my_field_provider[MyProvider].my_field == "cowabunga":
...
parent_rule = rule(
implementation = _parent_impl,
attrs = { "my_field_provider": attr.label() }
)
# example/BUILD
load("//example:rules.bzl", "dep_rule", "parent_rule")
dep_rule(name = "dep")
parent_rule(name = "parent", my_field_provider = ":my_field_provider")
label_flag(
name = "my_field_provider",
build_setting_default = ":dep"
)
build 设置和 select()
用户可以使用 select()
配置 build 设置的属性。构建设置目标可以传递给 config_setting
的 flag_values
属性。要与配置匹配的值会作为 String
传递,然后解析为 build 设置的类型以进行匹配。
config_setting(
name = "my_config",
flag_values = {
"//example:favorite_flavor": "MANGO"
}
)
用户定义的过渡
配置转换用于在 build 图中将从一个已配置目标到另一个目标的转换进行映射。
用于设置这些属性的规则必须包含特殊属性:
"_allowlist_function_transition": attr.label(
default = "@bazel_tools//tools/allowlists/function_transition_allowlist"
)
通过添加转换,您可以非常轻松地使构建图的大小爆炸式增长。这会针对您可以在其中创建此规则目标的软件包设置许可名单。上述代码块中的默认值会将所有内容列入许可名单。但是,如果您想限制谁在使用规则,可以将该属性设置为指向您自己的自定义许可名单。如果您想获得有关如何了解转换对构建性能有何影响的建议或帮助,请与 bazel-discuss@googlegroups.com 联系。
定义
转场定义了规则之间的配置更改。例如,“为与其父级不同的 CPU 编译我的依赖项”之类的请求由转换处理。
从形式上讲,转换是指从输入配置到一个或多个输出配置的函数。大多数转换都是 1:1,例如“使用 --cpu=ppc
替换输入配置”。也可能存在 1:2 以上的转换,但存在特殊限制。
在 Starlark 中,过渡的定义与规则非常相似,具有一个定义的 transition()
函数和一个实现函数。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {"//example:favorite_flavor" : "MINT"}
hot_chocolate_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//example:favorite_flavor"]
)
transition()
函数会接受一个实现函数、一组要读取的 build 设置 (inputs
) 和一组要写入的 build 设置 (outputs
)。实现函数有两个参数,即 settings
和 attr
。settings
是 inputs
参数中向 transition()
声明的所有设置的字典 {String
:Object
}。
attr
是与转场相关联的规则的属性和值的字典。作为传出边缘过渡附加时,这些属性的值都是配置的 select() 之后分辨率。作为传入边缘转场效果附加时,attr
不包含使用选择器解析其值的任何属性。如果 --foo
上的传入边缘过渡读取属性 bar
,然后还选择 --foo
以设置属性 bar
,则传入边缘过渡可能会在过渡中读取错误的 bar
值。
实现函数必须返回要应用的新 build 设置值的字典(如果转场具有多个输出配置,则为字典列表)。返回的字典键集必须完全包含传递给转换函数的 outputs
参数的一组 build 设置。即使 build 设置在转换过程中实际上没有更改,也必须在返回的字典中明确传递其原始值。
定义 1:2 以上的转换
出站边缘转换可将单个输入配置映射到两个或更多输出配置。这对于定义用于捆绑多架构代码的规则非常有用。
1:2 以上的转场效果是通过在转场实现函数中返回字典列表来定义的。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return [
{"//example:favorite_flavor" : "LATTE"},
{"//example:favorite_flavor" : "MOCHA"},
]
coffee_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//example:favorite_flavor"]
)
它们还可以设置规则实现函数可用于读取各个依赖项的自定义键:
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {
"Apple deps": {"//command_line_option:cpu": "ppc"},
"Linux deps": {"//command_line_option:cpu": "x86"},
}
multi_arch_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//command_line_option:cpu"]
)
附加转场
转场效果可附加在两个位置:入边和出边。 这实际上意味着规则可以转换自己的配置(入边过渡)和转换其依赖项的配置(出边过渡)。
注意:目前无法将 Starlark 转换附加到原生规则。 如果您需要这样做,请与 bazel-discuss@googlegroups.com 联系,寻求帮助来找出权宜解决方法。
传入边缘转换
通过将 transition
对象(由 transition()
创建)附加到 rule()
的 cfg
参数来激活传入边缘转场效果:
# example/rules.bzl
load("example/transitions:transitions.bzl", "hot_chocolate_transition")
drink_rule = rule(
implementation = _impl,
cfg = hot_chocolate_transition,
...
传入边缘转场效果必须为 1:1 转场效果。
出站边缘转换
通过将 transition
对象(由 transition()
创建)附加到属性的 cfg
参数,可激活传出边缘过渡:
# example/rules.bzl
load("example/transitions:transitions.bzl", "coffee_transition")
drink_rule = rule(
implementation = _impl,
attrs = { "dep": attr.label(cfg = coffee_transition)}
...
传出的边缘转换可以为 1:1 或 1:2+。
如需了解如何读取这些键,请参阅通过转换访问属性。
原生选项的转换
Starlark 转换还可以通过为选项名称添加特殊前缀来声明对原生 build 配置选项的读写操作。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {"//command_line_option:cpu": "k8"}
cpu_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//command_line_option:cpu"]
不受支持的原生选项
Bazel 不支持使用 "//command_line_option:define"
在 --define
上进行转换。请改用自定义 build 设置。一般来说,不建议使用新的 --define
用法,而应改用 build 设置。
Bazel 不支持在 --config
上进行转换。这是因为 --config
是一个会展开到其他标志的“展开”标志。
至关重要的是,--config
可能包含不会影响 build 配置的标志,例如 --spawn_strategy
。Bazel 的设计不允许将此类标志绑定到各个目标。这意味着,无法以一致的方式在转场中应用它们。
作为一种权宜解决方法,您可以在转换中明确列出配置中的标志。这需要在两个位置维护 --config
的展开,这是一个已知的界面瑕疵。
允许在转场效果中使用多个 build 设置
设置允许多个值的 build 设置时,必须使用列表设置该设置的值。
# example/buildsettings/build_settings.bzl
string_flag = rule(
implementation = _impl,
build_setting = config.string(flag = True, allow_multiple = True)
)
# example/BUILD
load("//example/buildsettings:build_settings.bzl", "string_flag")
string_flag(name = "roasts", build_setting_default = "medium")
# example/transitions/rules.bzl
def _transition_impl(settings, attr):
# Using a value of just "dark" here will throw an error
return {"//example:roasts" : ["dark"]},
coffee_transition = transition(
implementation = _transition_impl,
inputs = [],
outputs = ["//example:roasts"]
)
无操作过渡
如果转换返回 {}
、[]
或 None
,这是一种简写形式,可将所有设置保持为原始值。这比将每个输出明确设置为其自身更为方便。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (attr)
if settings["//example:already_chosen"] is True:
return {}
return {
"//example:favorite_flavor": "dark chocolate",
"//example:include_marshmallows": "yes",
"//example:desired_temperature": "38C",
}
hot_chocolate_transition = transition(
implementation = _impl,
inputs = ["//example:already_chosen"],
outputs = [
"//example:favorite_flavor",
"//example:include_marshmallows",
"//example:desired_temperature",
]
)
通过过渡访问属性
将过渡附加到传出边缘时(无论过渡是 1:1 还是 1:2+ 过渡),ctx.attr
将被强制设为一个列表(如果尚未这样做)。此列表中元素的顺序未指定。
# example/transitions/rules.bzl
def _transition_impl(settings, attr):
return {"//example:favorite_flavor" : "LATTE"},
coffee_transition = transition(
implementation = _transition_impl,
inputs = [],
outputs = ["//example:favorite_flavor"]
)
def _rule_impl(ctx):
# Note: List access even though "dep" is not declared as list
transitioned_dep = ctx.attr.dep[0]
# Note: Access doesn't change, other_deps was already a list
for other_dep in ctx.attr.other_deps:
# ...
coffee_rule = rule(
implementation = _rule_impl,
attrs = {
"dep": attr.label(cfg = coffee_transition)
"other_deps": attr.label_list(cfg = coffee_transition)
})
如果转场效果为 1:2+
并设置自定义按键,则可以使用 ctx.split_attr
读取每个按键的各个依赖项:
# example/transitions/rules.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {
"Apple deps": {"//command_line_option:cpu": "ppc"},
"Linux deps": {"//command_line_option:cpu": "x86"},
}
multi_arch_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//command_line_option:cpu"]
)
def _rule_impl(ctx):
apple_dep = ctx.split_attr.dep["Apple deps"]
linux_dep = ctx.split_attr.dep["Linux deps"]
# ctx.attr has a list of all deps for all keys. Order is not guaranteed.
all_deps = ctx.attr.dep
multi_arch_rule = rule(
implementation = _rule_impl,
attrs = {
"dep": attr.label(cfg = multi_arch_transition)
})
如需查看完整示例,请点击此处。
与平台和工具链集成
目前,许多原生标志(例如 --cpu
和 --crosstool_top
)都与工具链解析相关。未来,对这类标志的显式转换可能会被替换为在目标平台上进行转换。
内存和性能注意事项
向 build 中添加转换(即新配置)需要付出代价:build 图更大、更难理解,并且 build 速度更慢。在考虑在 build 规则中使用转换时,不妨考虑这些成本。以下示例展示了转换如何导致 build 图指数级增长。
行为异常的 build:一个案例
图 1. 显示顶级目标及其依赖项的可伸缩性图表。
此图显示了一个顶级目标 //pkg:app
,它依赖于两个目标 //pkg:1_0
和 //pkg:1_1
。这两个目标都依赖于两个目标://pkg:2_0
和 //pkg:2_1
。这两个目标都依赖于两个目标://pkg:3_0
和 //pkg:3_1
。此过程会一直持续到 //pkg:n_0
和 //pkg:n_1
,这两个依赖项都依赖于单个目标 //pkg:dep
。
构建 //pkg:app
需要 \(2n+2\) 目标:
//pkg:app
//pkg:dep
- \([1..n]\)中的 \(i\) 的
//pkg:i_0
和//pkg:i_1
假设您实现了一个标记 --//foo:owner=<STRING>
并应用了 //pkg:i_b
depConfig = myConfig + depConfig.owner="$(myConfig.owner)$(b)"
换句话说,//pkg:i_b
会将 b
附加到其所有依赖项的 --owner
旧值。
这会生成以下已配置的目标:
//pkg:app //foo:owner=""
//pkg:1_0 //foo:owner=""
//pkg:1_1 //foo:owner=""
//pkg:2_0 (via //pkg:1_0) //foo:owner="0"
//pkg:2_0 (via //pkg:1_1) //foo:owner="1"
//pkg:2_1 (via //pkg:1_0) //foo:owner="0"
//pkg:2_1 (via //pkg:1_1) //foo:owner="1"
//pkg:3_0 (via //pkg:1_0 → //pkg:2_0) //foo:owner="00"
//pkg:3_0 (via //pkg:1_0 → //pkg:2_1) //foo:owner="01"
//pkg:3_0 (via //pkg:1_1 → //pkg:2_0) //foo:owner="10"
//pkg:3_0 (via //pkg:1_1 → //pkg:2_1) //foo:owner="11"
...
//pkg:dep
会生成 \(2^n\) 配置的目标:config.owner=
\(\{0,1\}\)中的所有 \(b_i\) 均为“\(b_0b_1...b_n\)”。
这会使 build 图比目标图呈指数级增长,从而产生相应的内存和性能影响。
TODO:添加用于衡量和缓解这些问题的策略。
深入阅读
如需详细了解如何修改 build 配置,请参阅:
- Starlark build 配置
- Bazel 可配置性路线图
- 一整套端到端示例