这组规则可让您为要构建的特定硬件平台建模,并指定在针对这些平台编译代码时可能需要使用的特定工具。用户应熟悉此处介绍的概念。
规则
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
|
此设置的默认值的标签,在未指定值时使用。如果此属性存在,则其指向的 constraint_value 必须在与此 constraint_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, 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
的逻辑如下所示:
-
如果未在子平台上设置
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 |
名称(必需) 此目标的唯一名称。 |
constraint_values
|
此平台包含的限制条件选项组合。环境必须至少包含此列表中的值,才能将平台应用于指定环境。
此列表中的每个 |
exec_properties
|
字典:String -> String;不可配置;默认值为 exec_properties 属性的所有数据。如果子级和父级平台定义相同的键,则保留子级的值。与空字符串值关联的所有键都会从字典中移除。
此属性完全替代已弃用的 remote_execution_properties 。
|
flags
|
在配置中将此平台用作目标平台时启用的标志列表。只能使用可在过渡中设置的标记。 |
parents
|
此平台应从其继承的 platform 目标的标签。尽管该属性采用列表,但其平台数不得超过一个。任何未直接在此平台上设置的 constraint_settings 均可在父平台中找到。
如需了解详情,请参阅平台继承部分。
|
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 ,才能针对在该平台上进行的目标构建选择此工具链。
|
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 |
名称(必需) 此目标的唯一名称。 |