执行组

报告问题 查看源代码 每夜 build · 8.0 . 7.47.3 · 7.2 · 7.1 · 7.0 · 6.5

借助执行组,您可以在单个目标中使用多个执行平台。 每个执行组都有自己的 toolchain 依赖项,并执行自己的 toolchain 解析

背景

借助执行组,规则作者可以定义一组操作,每项操作可能具有不同的执行平台。多个执行平台可以允许以不同的方式执行操作,例如在远程 (Linux) 工作器上编译 iOS 应用,然后在本地 Mac 工作器上进行关联/代码签名。

能够定义一组操作还有助于减少使用操作助记符作为指定操作的替代项。我们无法保证快捷字母键是唯一的,并且只能引用单个操作。这对于向特定内存和处理密集型操作(例如在 C++ build 中进行链接)分配额外资源非常有用,而不会向需求较低的任务过度分配资源。

定义执行组

在定义规则时,规则作者可以声明一组执行组。对于每个执行组,规则作者可以指定为该执行组选择执行平台所需的所有信息,即通过 exec_compatible_with 指定的任何约束条件,以及通过 toolchain 指定的工具链类型。

# foo.bzl
my_rule = rule(
    _impl,
    exec_groups = {
        link: exec_group(
            exec_compatible_with = [ "@platforms//os:linux" ]
            toolchains = ["//foo:toolchain_type"],
        ),
        test: exec_group(
            toolchains = ["//foo_tools:toolchain_type"],
        ),
    },
    attrs = {
        "_compiler": attr.label(cfg = config.exec("link"))
    },
)

在上面的代码段中,您可以看到,工具依赖项还可以使用 cfg 属性参数和 config 模块为执行组指定转换。该模块公开了一个 exec 函数,该函数接受一个字符串参数,该参数是应为其构建依赖项的执行组的名称。

与原生规则一样,Starlark 测试规则默认包含 test 执行组。

执行组继承

除了定义自己的约束条件和工具链之外,新执行组还可以通过传递 copy_from_rule = True 参数声明其希望从规则的默认执行组继承。如果将 copy_from_rule 设置为 true,同时也传递 exec_compatible_withtoolchains,则会出错。

从默认执行组继承的执行组会复制默认组中的约束条件、工具链和执行属性。这包括在目标级别设置的约束条件和执行属性,而不仅仅是规则本身指定的约束条件和执行属性。换句话说,假设:

# foo.bzl
my_rule = rule(
    _impl,
    exec_groups = {
        copied: exec_group(
            copy_from_rule = True,
            # This will inherit exec_compatible_with and toolchains.
            # Setting them here directly would be an error, however.
        ),
    },
    toolchains = ["//foo_tools:toolchain_type"],
    exec_compatible_with = ["@platforms//os:linux"],
)

# BUILD

my_rule(
    name = "demo",
    exec_compatible_with = [":local_constraint"],
)

配置的目标 democopied 执行组将包含以下所有内容: - //fool_tools:toolchain_type - @platforms//os:linux - :local_constraint

访问执行组

在规则实现中,您可以声明操作应在执行组的执行平台上运行。为此,您可以使用操作生成方法(特别是 ctx.actions.runctx.actions.run_shell)的 exec_group 参数。

# foo.bzl
def _impl(ctx):
  ctx.actions.run(
     inputs = [ctx.attr._some_tool, ctx.srcs[0]]
     exec_group = "compile",
     # ...
  )

规则作者还可以访问执行组的已解析的工具链,就像访问目标的已解析工具链一样:

# foo.bzl
def _impl(ctx):
  foo_info = ctx.exec_groups["link"].toolchains["//foo:toolchain_type"].fooinfo
  ctx.actions.run(
     inputs = [foo_info, ctx.srcs[0]]
     exec_group = "link",
     # ...
  )

使用执行组设置执行属性

执行组与每个规则中存在的 exec_properties 属性集成,并允许目标写入器指定一个属性字符串字典,然后将其传递给执行机制。例如,如果您想为目标设置某些属性(例如内存),并为某些操作分配更多内存,则可以使用带有执行组增强键的 exec_properties 条目进行编写,例如:

# BUILD
my_rule(
    name = 'my_target',
    exec_properties = {
        'mem': '12g',
        'link.mem': '16g'
    }
    
)

使用 exec_group = "link" 的所有操作都会将 exec 属性字典视为 {"mem": "16g"}。如您所见,执行组级设置会替换目标级设置。

原生规则的执行组

以下执行组适用于由原生规则定义的操作:

  • test:测试运行程序操作。
  • cpp_link:C++ 链接操作。

创建执行组以设置执行属性

有时,您希望使用 exec 组为特定操作提供不同的 exec 属性,但实际上不希望与规则使用不同的工具链或约束条件。对于这些情况,您可以使用 copy_from_rule 参数创建执行组:

# foo.bzl

# Creating an exec group with `copy_from_rule=True` is the same as explicitly
# setting the exec group's toolchains and constraints to the same values as the
# rule's respective parameters.
my_rule = rule(
    _impl,
    exec_compatible_with = ["@platforms//os:linux"],
    toolchains = ["//foo:toolchain_type"],
    exec_groups = {
        # The following two groups have the same toolchains and constraints:
        foo: exec_group(copy_from_rule = True),
        "bar": exec_group(
            exec_compatible_with = ["@platforms//os:linux"],
            toolchains = ["//foo:toolchain_type"],
        ),
    },
)

#

执行组和平台执行属性

您可以在平台目标上为任意执行组定义 exec_properties(与直接在目标上设置 exec_properties 不同,后者会拒绝未知执行组的属性)。然后,目标会继承影响默认执行组和任何其他相关执行组的执行平台的 exec_properties

例如,假设运行 C++ 测试需要某些资源可用,但编译和链接不需要这些资源;这可以按如下方式建模:

constraint_setting(name = "resource")
constraint_value(name = "has_resource", constraint_setting = ":resource")

platform(
    name = "platform_with_resource",
    constraint_values = [":has_resource"],
    exec_properties = {
        "test.resource": "...",
    },
)

cc_test(
    name = "my_test",
    srcs = ["my_test.cc"],
    exec_compatible_with = [":has_resource"],
)

直接在目标上定义的 exec_properties 优先于从执行平台继承的 exec_properties