2025 年 BazelCon 报名和 CFP 现已开放！

此页面由 Cloud Translation API 翻译。

配置

报告问题查看来源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

本页介绍了 Starlark 配置的优势和基本用法，Starlark 配置是 Bazel 的 API，用于自定义项目构建方式。它包括如何定义 build 设置，并提供了一些示例。

这样一来，您就可以：

为项目定义自定义标志，从而无需使用 --define
编写转换，以配置与父级不同的配置中的依赖项（例如 --compilation_mode=opt 或 --cpu=arm）
将更好的默认设置纳入规则中（例如，使用指定的 SDK 自动构建 //my:android_app）

等等，所有这些都完全来自 .bzl 文件（无需 Bazel 版本）。如需查看示例，请参阅 bazelbuild/examples 代码库。

用户定义的 build 设置

build 设置是一条配置信息。将配置视为键值映射。设置 --cpu=ppc 和 --copt="-DFoo" 会生成类似于 {cpu: ppc, copt: "-DFoo"} 的配置。每个条目都是一个 build 设置。

cpu 和 copt 等传统标志是原生设置，其键已定义，其值在原生 Bazel Java 代码中设置。Bazel 用户只能通过命令行和其他原生维护的 API 读取和写入这些文件。更改原生标志以及公开这些标志的 API 需要进行 bazel 发布。用户定义的 build 设置在 .bzl 文件中定义（因此，不需要通过 Bazel 版本来注册更改）。这些变量也可以通过命令行设置（如果它们被指定为 flags，请参阅下文了解详情），但也可以通过用户定义的过渡进行设置。

定义 build 设置

端到端示例

`build_setting` `rule()` 参数

build 设置与其他规则一样都是规则，但通过 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

与所有规则一样，build 设置规则也具有实现函数。可以通过 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 参数，该参数允许在命令行或 bazelrc 中多次设置标志。但仍需使用字符串类型的属性来设置其默认值：

# example/buildsettings/build_settings.bzl
allow_multiple_flag = rule(
    implementation = _impl,
    build_setting = config.string(flag = True, allow_multiple = True)
)

# example/buildsettings/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/buildsettings/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 设置。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 设置别名

您可以为 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。这些规则会将实际目标的提供程序（构建设置已设置为该目标）转发给该目标。label_flag 和 label_setting 可由过渡读取/写入，并且 label_flag 可由用户设置，就像其他 build_setting 规则一样。它们唯一的区别是无法自定义。

标签类型设置最终将取代后期绑定默认值的功能。后期绑定默认属性是指最终值可能会受到配置影响的 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"
)

构建设置和 select()

端到端示例

用户可以使用 select() 在 build 设置中配置属性。构建设置目标可以传递给 config_setting 的 flag_values 属性。要与配置匹配的值作为 String 传递，然后解析为 build 设置的类型以进行匹配。

config_setting(
    name = "my_config",
    flag_values = {
        "//example:favorite_flavor": "MANGO"
    }
)

用户定义的过渡

配置转换用于将构建图中的一个配置目标转换为另一个配置目标。

设置这些规则时必须包含一个特殊属性：

  "_allowlist_function_transition": attr.label(
      default = "@bazel_tools//tools/allowlists/function_transition_allowlist"
  )

通过添加过渡，您可以轻松地大幅增加 build 图的大小。此设置用于为可创建相应规则的目标的软件包设置许可名单。上述代码块中的默认值允许所有内容。不过，如果您想限制规则的使用者，可以将该属性设置为指向您自己的自定义许可名单。如果您想获得有关转换如何影响构建性能的建议或帮助，请发送电子邮件至 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 是一个字典 {String:Object}，包含 inputs 参数中声明的所有设置，用于 transition()。

attr 是附加了相应过渡的规则的属性和值的字典。当作为出边转换附加时，这些属性的值都是在 select() 解析后配置的。当作为入边转换附加时，attr 不包含任何使用选择器来解析其值的属性。如果 --foo 上的入边转换读取属性 bar，然后还选择 --foo 来设置属性 bar，则入边转换可能会在转换中读取错误的 bar 值。

实现函数必须返回要应用的新 build 设置值的字典（或字典列表，如果转换具有多个输出配置）。返回的字典键集必须包含传递给过渡函数的 outputs 形参的构建设置集。即使在过渡期间 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 不支持在 --define 上使用 "//command_line_option: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_0b_1...b_n\)”。 \(b_i\)

这使得 build 图比目标图大得多，从而导致内存和性能方面的问题。

待办事项：添加用于衡量和缓解这些问题的策略。

深入阅读

如需详细了解如何修改 build 配置，请参阅：

配置

用户定义的 build 设置

定义 build 设置

build_setting rule() 参数

使用 ctx.build_setting_value

定义多组字符串标志

实例化 build 设置

预定义设置

使用 build 设置

取决于 build 设置

在命令行中使用 build 设置

使用 build 设置别名

标签类型的 build 设置

构建设置和 select()

用户定义的过渡

定义

定义 1:2+ 过渡

附加转换

传入边缘转换

出站边缘转换

原生选项的过渡

不支持的原生选项

过渡允许多个 build 设置

空操作过渡

通过过渡访问属性

与平台和工具链集成

内存和性能注意事项

行为不端的 build：一个案例研究

深入阅读

`build_setting` `rule()` 参数