平台和工具链规则

报告问题 查看源代码 敬上 每晚 · 7.3。 · 7.2。 · 7.1。 · 7.0。 · 6.5

这组规则让您可以为自己熟悉的特定硬件平台建模。 并指定在针对这些平台编译代码时可能需要的特定工具。 用户应熟悉此处介绍的概念。

规则

• <ph type="x-smartling-placeholder"></ph> constraint_setting
• <ph type="x-smartling-placeholder"></ph> constraint_value
• <ph type="x-smartling-placeholder"></ph> 平台
• <ph type="x-smartling-placeholder"></ph> 工具链
• <ph type="x-smartling-placeholder"></ph> toolchain_type

constraint_setting

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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 可能的选择。

平台

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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

此规则定义了一个新的平台，即限制条件选项的指定集合。 （例如 CPU 架构或编译器版本）来描述 构建的哪个部分可能会运行 如需了解详情，请参阅平台页面。

示例

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

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

平台标志

平台可以使用 flags 属性来指定要添加的标志列表 只要平台用作目标平台（即，作为 --platforms 标志）。

从平台设置的标志实际上具有最高优先级，并会覆盖之前的任何标志 。

示例

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”父项的父项，而不设置自己的项。
• 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	字典：String ->String;不可配置；默认值为 {} 影响远程执行操作方式的字符串映射。Bazel 不尝试 将被视为不透明数据，通过 远程执行协议。 这包括来自父级平台的 exec_properties 属性的所有数据。 如果子级和父级平台定义相同的键，则保留子级的值。不限 与空字符串值相关联的键会从字典中移除。 此属性完全替代已弃用的 remote_execution_properties。
flags	字符串列表；不可配置；默认值为 [] 在将此平台用作目标平台时将会启用的标志列表 配置。只能使用可在过渡中设置的标记。
parents	标签列表；不可配置；默认值为 [] 此平台应从其继承的 platform 目标的标签。虽然 属性采用列表形式，则平台中不应超过 1 个。不限 未在父级平台中找到未直接在此平台上设置的 constraint_settings 设置。 如需了解详情，请参阅平台继承部分。
remote_execution_properties	String;不可配置；默认值为 "" 已弃用。请改用 exec_properties 属性。 用于配置远程执行平台的字符串。实际 build 不会尝试 解读数据时，系统会将其视为不透明数据，可供特定的 SpawnRunner 使用。 这可能包括来自父级平台的“remote_execution_properties”的数据属性， 使用宏“{PARENT_REMOTE_EXECUTION_PROPERTIES}”。请参阅 如需了解详情，请参阅平台继承。
required_settings	标签列表；默认值为 [] 目标配置必须满足的 config_setting 列表 以便此平台在工具链解析期间用作执行平台。 必需设置不会从父级平台继承。

工具链

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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 列表 以便针对在该平台上构建的目标选择此工具链。
target_compatible_with	标签列表；不可配置；默认值为 [] 一个由目标平台必须满足的 constraint_value 的列表， 选择此工具链用于该平台的目标构建。
target_settings	标签列表；默认值为 [] 目标配置必须满足的 config_setting 列表 才能在工具链解析期间选择此工具链。
toolchain	姓名；必需 一个目标，表示在此测试时提供的实际工具或工具套件。 工具链。
toolchain_type	标签；不可配置；必需 toolchain_type 目标的标签，表示 工具链服务。

toolchain_type

<ph type="x-smartling-placeholder"></ph> 查看规则来源

toolchain_type(name, compatible_with, deprecation, features, 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	姓名；必需 此目标的唯一名称。