此页面由 Cloud Translation API 翻译。

平台规则

规则

constraint_setting
constraint_value
平台
工具链
toolchain_type

constraint_setting

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

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

每个 constraint_setting 都有一组可扩展的关联 constraint_value。通常它们是在同一软件包中定义的，但有时不同的软件包会为现有设置引入新值。例如，您可以使用自定义值扩展预定义的设置 @platforms//cpu:cpu，以定义针对隐蔽的 CPU 架构的平台。

参数

属性

name

Name; required

此目标的唯一名称。

default_constraint_value

Name; optional; nonconfigurable

此设置的默认值的标签，在未指定任何值时使用。如果存在此属性，则必须在与此 constraint_setting 相同的软件包中定义它指向的 constraint_value。

如果限制条件设置具有默认值，那么每当平台未为该设置添加任何限制条件值时，其效果与平台已指定默认值的情况相同。否则，如果没有默认值，则约束设置会被视为平台未指定。在这种情况下，平台不会与任何需要此设置特定值的约束列表（例如 config_setting）进行匹配。

constraint_value

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

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

示例

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

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

然后，平台可以声明它们采用 mips 架构来代替 x86_64、arm 等。

参数

属性

name

Name; required

此目标的唯一名称。

constraint_setting

Label; required; nonconfigurable

此 constraint_value 可能选择的 constraint_setting。

平台

platform(name, constraint_values, deprecation, distribs, exec_compatible_with, 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 的逻辑如下所示：

如果未在子级平台上设置 remote_execution_property，将使用父级平台的 remote_execution_properties。
如果在子平台上设置了 remote_execution_property，且包含字面量字符串 {PARENT_REMOTE_EXECUTION_PROPERTIES}，则该宏将替换为父平台 remote_execution_property 属性的内容。
如果在子平台上设置了 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`	`Name; required` 此目标的唯一名称。
`constraint_values`	`List of labels; optional` 此平台包含的限制条件选项组合。为使平台能够应用于给定环境，该环境必须至少包含此列表中的值。此列表中的每个 `constraint_value` 都必须用于不同的 `constraint_setting`。例如，您不能定义要求 CPU 架构同时是 `@platforms//cpu:x86_64` 和 `@platforms//cpu:arm` 的平台。
`exec_properties`	`Dictionary: String -> String; optional` 影响远程执行操作方式的字符串映射。Bazel 不会尝试解读这种情况，而是将其视为通过远程执行协议的 Platform 字段转发的不透明数据。这包括父平台的 `exec_properties` 属性中的任何数据。如果子级平台和父级平台定义了相同的键，则会保留子级的值。任何与空字符串值相关联的键都将从字典中移除。此属性可完全替换已废弃的 `remote_execution_properties`。
`parents`	`List of labels; optional` 此平台应沿用的 `platform` 目标的标签。虽然该属性采用列表形式，但最多只能存在一个平台。未在此平台上直接设置的任何 constraint_settings 都将在父平台中找到。如需了解详情，请参阅平台继承部分。
`remote_execution_properties`	`String; optional` 已弃用。请改用 exec_properties 属性。用于配置远程执行平台的字符串。实际 build 不会尝试解释这一点，它被视为可供特定 SpawnRunner 使用的不透明数据。这可以使用宏“{PARENT_REMOTE_EXECUTION_PROPERTIES}”添加来自父平台的“remote_execution_properties”属性的数据。如需了解详情，请参阅平台继承部分。

工具链

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

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

参数

属性
`name`	`Name; required` 此目标的唯一名称。
`exec_compatible_with`	`List of labels; optional; nonconfigurable` 执行平台必须满足的 `constraint_value` 列表，才能为在该平台上构建的目标选择此工具链。
`target_compatible_with`	`List of labels; optional; nonconfigurable` 一个 `constraint_value` 列表，目标平台必须满足这些要求，才能为该平台的目标构建选择此工具链。
`target_settings`	`List of labels; optional` 为了在工具链解析期间选择此工具链，目标配置必须满足的 `config_setting` 列表。
`toolchain`	`Name; required` 表示选择此工具链时提供的实际工具或工具套件的目标。
`toolchain_type`	`Label; required; nonconfigurable` `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

Name; required

此目标的唯一名称。