平台和工具链规则

报告问题 查看源代码

每夜版 · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

这组规则旨在让您能够为正在构建的特定硬件平台建模，并指定可能需要用于为这些平台编译代码的特定工具。用户应熟悉此处说明的概念。

规则

• constraint_setting
• constraint_value
• 平台
• toolchain
• toolchain_type

constraint_setting

查看规则来源

constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

此规则用于引入平台可以指定值的新约束类型。例如，您可以定义一个名为“glibc_version”的 constraint_setting，以表示平台安装了不同版本的 glibc 库。如需了解详情，请参阅平台页面。

每个 constraint_setting 都有一组可扩展的关联 constraint_value。通常，这些值是在同一软件包中定义的，但有时不同的软件包会为现有设置引入新值。例如，预定义设置 @platforms//cpu:cpu 可以通过自定义值进行扩展，以定义以不常见的 CPU 架构为目标的平台。

参数

属性
name	名称；必需 相应目标的唯一名称。
default_constraint_value	名称；不可配置；默认值为 None 相应设置的默认值的标签，在未提供值时使用。如果存在此属性，则其指向的 constraint_value 必须与此 constraint_setting 定义在同一软件包中。 如果某个限制设置具有默认值，那么每当平台未包含该设置的任何限制值时，就相当于平台指定了默认值。否则，如果没有默认值，则该平台会认为相应限制设置未指定。在这种情况下，平台将不会与任何需要该设置具有特定值的限制列表（例如 config_setting 的限制列表）进行匹配。

constraint_value

查看规则来源

constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)

此规则为给定的限制条件类型引入了一个新值。 如需了解详情，请参阅平台页面。

示例

以下代码为预定义的 constraint_value（表示 CPU 架构）创建了一个新的可能值。

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)

然后，平台可以声明它们具有 mips 架构，而不是 x86_64、arm 等。

参数

属性
name	名称；必需 相应目标的唯一名称。
constraint_setting	标签；不可配置；必需 相应 constraint_value 可能适用的 constraint_setting。

平台

查看规则来源

platform(name, constraint_values, deprecation, distribs, exec_properties, features, flags, licenses, parents, remote_execution_properties, required_settings, tags, testonly, visibility)

此规则定义了一个新平台，即一组命名的限制选择项（例如 CPU 架构或编译器版本），用于描述部分 build 可能运行的环境。 如需了解详情，请参阅平台页面。

示例

这定义了一个平台，用于描述在 ARM 上运行 Linux 的任何环境。

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

平台标志

平台可以使用 flags 属性来指定一个标志列表，每当平台用作目标平台（即作为 --platforms 标志的值）时，这些标志都会添加到配置中。

从平台设置的标志实际上具有最高优先级，并会覆盖该标志的任何先前值（来自命令行、rc 文件或过渡）。

示例

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

这定义了一个名为 foo 的平台。如果这是目标平台（无论是由于用户指定了 --platforms//:foo，还是由于某个过渡将 //command_line_option:platforms 标志设置为 ["//:foo"]，还是由于 //:foo 被用作执行平台），那么给定的标志将设置在配置中。

平台和可重复标志

有些标志在重复使用时会累积值，例如 --features、--copt 以及任何创建为 config.string(repeatable = True) 的 Starlark 标志。 这些标志与从平台设置标志不兼容：相反，所有之前的值都将被移除，并被平台中的值覆盖。

举例来说，假设有以下平台，调用 build --platforms=//:repeat_demo --features feature_a --features feature_b 将导致 --feature 标志的值为 ["feature_c", "feature_d"]，从而移除在命令行中设置的功能。

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

因此，不建议在 flags 属性中使用可重复的标志。

平台继承

平台可以使用 parents 属性来指定将从中继承限制值的其他平台。虽然 parents 属性接受列表，但目前仅支持单个值，指定多个父级会出错。

在平台中检查限制设置的值时，系统会先检查直接设置的值（通过 constraint_values 属性），然后再检查父级上的限制值。此过程会以递归方式继续向上遍历父平台链。这样一来，直接在平台中设置的任何值都会覆盖在父级中设置的值。

平台会从父平台继承 exec_properties 属性。 父平台和子平台的 exec_properties 中的字典条目将被合并。 如果父级和子级的 exec_properties 中都出现了相同的键，系统将使用子级的值。如果子平台将空字符串指定为值，则相应属性将处于未设置状态。

平台还可以从父平台继承（已弃用的）remote_execution_properties 属性。注意：新代码应改用 exec_properties。以下所述的逻辑是为了与旧版行为保持兼容性，但未来会移除。 当存在父平台时，设置 remote_execution_platform 的逻辑如下：

1. 如果未在子平台中设置 remote_execution_property，则使用父平台的 remote_execution_properties。
2. 如果子平台设置了 remote_execution_property，并且其中包含字面值字符串 {PARENT_REMOTE_EXECUTION_PROPERTIES}，则该宏将被替换为父平台的 remote_execution_property 属性的内容。
3. 如果子平台设置了 remote_execution_property，且不包含该宏，则子平台的 remote_execution_property 将保持不变。

由于 remote_execution_properties 已被废弃并将逐步淘汰，因此不允许在同一继承链中混合使用 remote_execution_properties 和 exec_properties。 建议使用 exec_properties，而不是已弃用的 remote_execution_properties。

示例：限制值

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

在此示例中，子平台的属性如下：

• child_a 具有约束值 @platforms//os:linux（从父级继承）和 @platforms//cpu:x86_64（直接在平台上设置）。
• child_b 从父级继承所有限制值，并且不设置任何自己的限制值。

示例：执行属性

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

在此示例中，子平台的属性如下：

• child_a 继承父级的“exec_properties”，而不设置自己的“exec_properties”。
• child_b 继承父级的 exec_properties 并替换 k1 的值。其 exec_properties 将为： { "k1": "child", "k2": "v2" }。
• child_c 继承父级的 exec_properties 并取消设置 k1。其 exec_properties 将为： { "k2": "v2" }。
• child_d 继承了父级的 exec_properties 并添加了一个新属性。其 exec_properties 将为： { "k1": "v1", "k2": "v2", "k3": "v3" }。

参数

属性
name	名称；必需 相应目标的唯一名称。
constraint_values	标签列表；不可配置；默认值为 [] 相应平台包含的限制条件选择组合。为了使平台能够应用于给定的环境，该环境必须至少具有此列表中的值。 此列表中的每个 constraint_value 都必须对应不同的 constraint_setting。例如，您不能定义一个平台，该平台要求 CPU 架构同时为 @platforms//cpu:x86_64 和 @platforms//cpu:arm。
exec_properties	字典：字符串 -> 字符串；不可配置；默认值为 {} 一个字符串映射，用于影响远程执行操作的方式。Bazel 不会尝试解释此内容，而是将其视为通过远程执行协议的 Platform 字段转发的不透明数据。 这包括父平台的 exec_properties 属性中的所有数据。 如果子平台和父平台定义了相同的键，则保留子平台的值。与空字符串值关联的所有键都会从字典中移除。 此属性完全取代了已弃用的 remote_execution_properties。
flags	字符串列表；不可配置；默认值为 [] 当此平台在配置中用作目标平台时将启用的一系列标志。只允许使用可在过渡中设置的标志。
parents	标签列表；不可配置；默认值为 [] 相应平台应继承的 platform 目标的标签。虽然该属性采用列表，但不应包含多个平台。未直接在此平台上设置的任何 constraint_settings 都将在父平台中找到。 如需了解详情，请参阅有关平台继承的部分。
remote_execution_properties	字符串；不可配置；默认值为 "" 已弃用。请改用 exec_properties 属性。 用于配置远程执行平台的字符串。实际 build 不会尝试解释此数据，而是将其视为可供特定 SpawnRunner 使用的不透明数据。这可以包括来自父平台的“remote_execution_properties”属性的数据，方法是使用宏“{PARENT_REMOTE_EXECUTION_PROPERTIES}”。如需了解详情，请参阅有关平台继承的部分。
required_settings	标签列表；默认值为 [] 目标配置必须满足的 config_setting 列表，以便在工具链解析期间将相应平台用作执行平台。 必需设置不会从父平台继承。

工具链

查看规则来源

toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

此规则声明了特定工具链的类型和限制条件，以便在工具链解析期间可以选择该工具链。如需了解详情，请参阅工具链页面。

参数

属性
name	名称；必需 相应目标的唯一名称。
exec_compatible_with	标签列表；不可配置；默认值为 [] constraint_value 的列表，执行平台必须满足这些 constraint_value，才能选择此工具链来构建该平台上的目标。
target_compatible_with	标签列表；不可配置；默认值为 [] 目标平台必须满足的 constraint_value 列表，以便为针对该平台构建的目标选择此工具链。
target_settings	标签列表；默认值为 [] 目标配置必须满足的 config_setting 列表，以便在工具链解析期间选择此工具链。
toolchain	名称；必需 表示选择此工具链时可用的实际工具或工具套件的目标。
toolchain_type	标签；不可配置；必需 表示此工具链所服务角色的 toolchain_type 目标的标签。

toolchain_type

查看规则来源

toolchain_type(name, compatible_with, deprecation, features, no_match_error, restricted_to, tags, target_compatible_with, testonly, visibility)

此规则定义了一种新的工具链 - 一个简单的目标，表示一类在不同平台上发挥相同作用的工具。

如需了解详情，请参阅工具链页面。

示例

此属性用于为自定义规则定义工具链类型。

toolchain_type(
    name = "bar_toolchain_type",
)

这可以在 bzl 文件中使用。

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

参数

属性
name	名称；必需 相应目标的唯一名称。
no_match_error	字符串；不可配置；默认值为 "" 当找不到与此类型匹配的工具链时要显示的自定义错误消息。