平台和工具链规则

报告问题 查看源代码

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

规则

• constraint_setting
• constraint_value
• 平台
• 工具链
• 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)

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

示例

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

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, licenses, parents, remote_execution_properties, tags, testonly, visibility)

此规则定义了一个新的平台，即限制条件选项（例如 CPU 架构或编译器版本）的指定集合，用于描述部分 build 可以在其中运行的环境。 如需了解详情，请参阅平台页面。

示例

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

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

平台沿用

平台可以使用 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 不会尝试解读这些数据，而是将其视为通过远程执行协议的 Platform 字段转发的不透明数据。这包括来自父级平台的 exec_properties 属性的所有数据。如果子级和父级平台定义相同的键，则保留子级的值。与空字符串值关联的所有键都会从字典中移除。 此属性完全替代已弃用的 remote_execution_properties。
parents	标签列表；不可配置；默认值为 [] 此平台应从其继承的 platform 目标的标签。尽管该属性采用列表，但其平台数不得超过一个。任何未直接在此平台上设置的 constraint_settings 均可在父平台中找到。 如需了解详情，请参阅平台继承部分。
remote_execution_properties	字符串；不可配置；默认值为 "" 已弃用。请改用 exec_properties 属性。 用于配置远程执行平台的字符串。实际 build 不会尝试解读这些数据，此类数据被视为可供特定 SpawnRunner 使用的不透明数据。 通过使用宏“{PARENT_REMOTE_EXECUTION_PROPERTIES}”，可以包括来自父平台的“remote_execution_properties”属性的数据。如需了解详情，请参阅平台继承部分。

工具链

查看规则来源

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

查看规则来源

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	名称（必需） 此目标的唯一名称。