规则
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 |
此目标的唯一名称。 |
default_constraint_value
|
constraint_setting 相同的软件包中定义它指向的 constraint_value 。
如果限制条件设置具有默认值,那么每当平台未为该设置添加任何限制条件值时,其效果与平台已指定默认值的情况相同。否则,如果没有默认值,则约束设置会被视为平台未指定。在这种情况下,平台不会与任何需要此设置特定值的约束列表(例如 |
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 |
此目标的唯一名称。 |
constraint_setting
|
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 |
此目标的唯一名称。 |
constraint_values
|
此列表中的每个 |
exec_properties
|
exec_properties 属性中的任何数据。如果子级平台和父级平台定义了相同的键,则会保留子级的值。任何与空字符串值相关联的键都将从字典中移除。
此属性可完全替换已废弃的 remote_execution_properties 。
|
parents
|
platform 目标的标签。虽然该属性采用列表形式,但最多只能存在一个平台。未在此平台上直接设置的任何 constraint_settings 都将在父平台中找到。
如需了解详情,请参阅平台继承部分。
|
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 |
此目标的唯一名称。 |
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 |
此目标的唯一名称。 |