平台和工具链规则

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

规则

• constraint_setting
• constraint_value
• platform
• 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 架构为目标的平台。

实参

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",
)

实参

platform

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 标志的值）时，这些标志都会添加到配置中。

从平台设置的标志实际上具有最高优先级，并会覆盖命令行、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" }.

实参

toolchain

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

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

实参

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"]
)

实参