属性

报告问题 查看来源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

这是一个顶级模块,用于定义规则或方面的属性架构。每个函数都会返回一个表示单个属性的架构的对象。这些对象用作 rule()aspect()repository_rule()tag_class()attrs 字典实参的值。

如需详细了解如何定义使用属性,请参阅“规则”页面。

成员

bool

Attribute attr.bool(configurable=unbound, default=False, doc=None, mandatory=False)

为布尔值属性创建架构。相应的 ctx.attr 属性将为 bool 类型。

参数

参数 说明
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default bool; 默认值为 False
在实例化规则时,如果未为此属性提供值,则要使用的默认值。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。

int

Attribute attr.int(configurable=unbound, default=0, doc=None, mandatory=False, values=[])

为整数属性创建架构。该值必须在带符号的 32 位范围内。相应的 ctx.attr 属性将为 int 类型。

参数

参数 说明
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default int; 默认值为 0
在实例化规则时,如果未提供相应属性的值,则使用的默认值。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
values 整数序列; 默认值为 []
属性的允许值列表。如果提供任何其他值,则会引发错误。

int_list

Attribute attr.int_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None)

为整数列表属性创建架构。每个元素都必须在带符号的 32 位范围内。

参数

参数 说明
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default 的序列;默认值为 []
如果在实例化规则时未为此属性提供值,则要使用的默认值。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。

标签

Attribute attr.label(configurable=unbound, default=None, materializer=None, doc=None, executable=False, allow_files=None, allow_single_file=None, mandatory=False, skip_validations=False, providers=[], for_dependency_resolution=unbound, allow_rules=None, cfg=None, aspects=[], flags=[])

为标签属性创建架构。这是一个依赖项属性。

此属性包含唯一的 Label 值。如果提供的是字符串而不是 Label,系统会使用 label 构造函数进行转换。标签路径的相对部分(包括可能已重命名的代码库)是相对于实例化目标的软件包来解析的。

在分析时(在规则的实现函数内),从 ctx.attr 检索属性值时,标签会被替换为相应的 Target。这样,您就可以访问当前目标依赖项的提供程序。

除了普通的源文件之外,此类属性通常还用于指代工具(例如编译器)。此类工具被视为依赖项,就像源文件一样。为避免要求用户每次在 BUILD 文件中使用该规则时都指定工具的标签,您可以将规范工具的标签硬编码为此属性的 default 值。如果您还想阻止用户替换此默认值,可以为该属性指定一个以下划线开头的名称,使其成为私有属性。如需了解详情,请参阅规则页面。

参数

参数 说明
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default 标签;或字符串;或 LateBoundDefault;或 NativeComputedDefault;或函数;或 None; 默认值为 None
如果实例化规则时未提供相应属性的值,则使用的默认值。使用字符串或 Label 函数指定默认值,例如 attr.label(default = "//a:b")
materializer 函数; 默认值为 None
实验性。此参数目前处于实验阶段,随时可能发生变化。请勿依赖此功能。可以通过设置 --experimental_dormant_deps
以实验性方式启用。如果设置了该属性,则会从传递闭包中具体化休眠的依赖项。此形参的值必须是一个函数,该函数可访问规则的属性值,这些属性要么不是依赖项,要么标记为可用于依赖项解析。它必须返回休眠依赖项或休眠依赖项列表,具体取决于属性的类型
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
executable bool; 默认值为 False
如果依赖项必须是可执行文件,则为 True。这意味着标签必须引用可执行文件,或引用输出可执行文件的规则。使用 ctx.executable.<attribute_name> 访问标签。
allow_files 布尔值;或字符串序列;或 None; 默认值为 None
是否允许 File 目标平台。可以是 TrueFalse(默认值),也可以是允许的文件扩展名列表(例如 [".cc", ".cpp"])。
allow_single_file 默认值为 None
此标志与 allow_files 类似,但限制是标签必须对应于单个 File。您可以通过 ctx.file.<attribute_name> 访问该文件。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
skip_validations 布尔值; 默认值为 False
如果为 true,则不会运行来自此属性的传递依赖项的验证操作。这只是一项临时缓解措施,未来将会移除。
providers sequence;默认值为 []
必须由出现在此属性中的任何依赖项提供的提供程序。

此实参的格式为提供程序列表的列表,即 provider() 返回的 *Info 对象(如果是旧版提供程序,则为它的字符串名称)。依赖项必须返回至少一个内部列表中提及的所有提供程序。为方便起见,此实参也可以是提供程序的一级列表,在这种情况下,它会封装在一个包含一个元素的外部列表中(即 [A, B] 表示 [[A, B]])。依赖项的规则不一定需要在其 provides 参数中宣传这些提供程序,但建议这样做。

for_dependency_resolution 默认值为 unbound
如果设置了此值,则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
allow_rules 字符串的序列;或 None; 默认值为 None
允许哪些规则目标(类的名称)。此属性已弃用(仅为兼容性而保留),请改用提供程序。
cfg 默认值为 None
属性的配置。它可以是 "exec"(表示依赖项是为 execution platform 构建的),也可以是 "target"(表示依赖项是为 target platform 构建的)。一个典型的区别示例是构建移动应用时,target platformAndroidiOS,而 execution platformLinuxmacOSWindows。如果 executable 为 True,则需要此参数,以防止在目标配置中意外构建宿主工具。"target" 没有语义效果,因此,除非它确实有助于明确您的意图,否则请勿在 executable 为 False 时设置它。
aspects 方面序列;默认值为 []
应应用于此属性指定的依赖项的方面。
flags 字符串序列; 默认值为 []
已弃用,将被移除。

label_keyed_string_dict

Attribute attr.label_keyed_string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[])

为包含字典的属性创建一个架构,其中键是标签,值是字符串。这是一个依赖项属性。

此属性包含唯一的 Label 值。如果提供的是字符串而不是 Label,系统会使用 label 构造函数进行转换。标签路径的相对部分(包括可能已重命名的代码库)是相对于实例化目标的软件包来解析的。

在分析时(在规则的实现函数内),从 ctx.attr 检索属性值时,标签会被替换为相应的 Target。这样,您就可以访问当前目标依赖项的提供程序。

参数

参数 说明
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default dict;或 function; 默认值为 {}
在实例化规则时,如果未提供相应属性的值,则使用的默认值。使用字符串或 Label 函数指定默认值,例如 attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
allow_files 布尔值;或字符串序列;或 None; 默认值为 None
是否允许 File 目标平台。可以是 TrueFalse(默认值),也可以是允许的文件扩展名列表(例如 [".cc", ".cpp"])。
allow_rules 字符串的序列;或 None; 默认值为 None
允许哪些规则目标(类的名称)。此属性已弃用(仅为兼容性而保留),请改用提供程序。
providers sequence;默认值为 []
必须由出现在此属性中的任何依赖项提供的提供程序。

此实参的格式为提供程序列表的列表,即 provider() 返回的 *Info 对象(如果是旧版提供程序,则为它的字符串名称)。依赖项必须返回至少一个内部列表中提及的所有提供程序。为方便起见,此实参也可以是提供程序的一级列表,在这种情况下,它会封装在一个包含一个元素的外部列表中(即 [A, B] 表示 [[A, B]])。依赖项的规则不一定需要在其 provides 参数中宣传这些提供程序,但建议这样做。

for_dependency_resolution 默认值为 unbound
如果设置了此值,则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
flags 字符串序列; 默认值为 []
已弃用,将被移除。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
skip_validations 布尔值; 默认值为 False
如果为 true,则不会运行来自此属性的传递依赖项的验证操作。这只是一项临时缓解措施,未来将会移除。
cfg 默认值为 None
属性的配置。它可以是 "exec"(表示依赖项是为 execution platform 构建的),也可以是 "target"(表示依赖项是为 target platform 构建的)。一个典型的差异示例是构建移动应用时,target platformAndroidiOS,而 execution platformLinuxmacOSWindows
aspects 方面序列;默认值为 []
应应用于此属性指定的依赖项的方面。

label_list

Attribute attr.label_list(allow_empty=True, *, configurable=unbound, default=[], materializer=None, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, skip_validations=False, cfg=None, aspects=[])

为标签列表属性创建架构。这是一个依赖项属性。相应的 ctx.attr 属性将是 Target列表类型。

此属性包含唯一的 Label 值。如果提供的是字符串而不是 Label,系统会使用 label 构造函数进行转换。标签路径的相对部分(包括可能已重命名的代码库)是相对于实例化目标的软件包来解析的。

在分析时(在规则的实现函数内),从 ctx.attr 检索属性值时,标签会被替换为相应的 Target。这样,您就可以访问当前目标依赖项的提供程序。

参数

参数 说明
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default 标签序列;或函数; 默认值为 []
在实例化规则时,如果未提供相应属性的值,则使用的默认值。使用字符串或 Label 函数指定默认值,例如 attr.label_list(default = ["//a:b", "//a:c"])
materializer 函数; 默认值为 None
实验性。此参数目前处于实验阶段,随时可能发生变化。请勿依赖此功能。可以通过设置 --experimental_dormant_deps
以实验性方式启用。如果设置了该属性,则会从传递闭包中具体化休眠的依赖项。此形参的值必须是一个函数,该函数可访问规则的属性值,这些属性要么不是依赖项,要么标记为可用于依赖项解析。它必须返回休眠依赖项或休眠依赖项列表,具体取决于属性的类型
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
allow_files 布尔值;或字符串序列;或 None; 默认值为 None
是否允许 File 目标平台。可以是 TrueFalse(默认值),也可以是允许的文件扩展名列表(例如 [".cc", ".cpp"])。
allow_rules 字符串的序列;或 None; 默认值为 None
允许哪些规则目标(类的名称)。此属性已弃用(仅为兼容性而保留),请改用提供程序。
providers sequence;默认值为 []
必须由出现在此属性中的任何依赖项提供的提供程序。

此实参的格式为提供程序列表的列表,即 provider() 返回的 *Info 对象(如果是旧版提供程序,则为它的字符串名称)。依赖项必须返回至少一个内部列表中提及的所有提供程序。为方便起见,此实参也可以是提供程序的一级列表,在这种情况下,它会封装在一个包含一个元素的外部列表中(即 [A, B] 表示 [[A, B]])。依赖项的规则不一定需要在其 provides 参数中宣传这些提供程序,但建议这样做。

for_dependency_resolution 默认值为 unbound
如果设置了此值,则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
flags 字符串序列; 默认值为 []
已弃用,将被移除。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
skip_validations 布尔值; 默认值为 False
如果为 true,则不会运行来自此属性的传递依赖项的验证操作。这只是一项临时缓解措施,未来将会移除。
cfg 默认值为 None
属性的配置。它可以是 "exec"(表示依赖项是为 execution platform 构建的),也可以是 "target"(表示依赖项是为 target platform 构建的)。一个典型的差异示例是构建移动应用时,target platformAndroidiOS,而 execution platformLinuxmacOSWindows
aspects 方面序列;默认值为 []
应应用于此属性指定的依赖项的方面。

输出

Attribute attr.output(doc=None, mandatory=False)

为输出(标签)属性创建架构。

此属性包含唯一的 Label 值。如果提供的是字符串而不是 Label,系统会使用 label 构造函数进行转换。标签路径的相对部分(包括可能已重命名的代码库)是相对于实例化目标的软件包来解析的。

在分析时,可以使用 ctx.outputs 检索相应的 File

参数

参数 说明
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。

output_list

Attribute attr.output_list(allow_empty=True, *, doc=None, mandatory=False)

为输出列表属性创建架构。

此属性包含唯一的 Label 值。如果提供的是字符串而不是 Label,系统会使用 label 构造函数进行转换。标签路径的相对部分(包括可能已重命名的代码库)是相对于实例化目标的软件包来解析的。

在分析时,可以使用 ctx.outputs 检索相应的 File

参数

参数 说明
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。

字符串

Attribute attr.string(configurable=unbound, default='', doc=None, mandatory=False, values=[])

string 属性创建架构。

参数

参数 说明
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default string;或 NativeComputedDefault; 默认值为 ''
在实例化规则时,如果未提供相应属性的值,则使用的默认值。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
values 字符串的序列;默认值为 []
属性的允许值列表。如果提供任何其他值,则会引发错误。

string_dict

Attribute attr.string_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False)

为包含字典的属性创建架构,其中键和值均为字符串。

参数

参数 说明
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default dict;默认值为 {}
在实例化规则时,如果未为此属性提供值,则要使用的默认值。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。

string_keyed_label_dict

Attribute attr.string_keyed_label_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], for_dependency_resolution=unbound, flags=[], mandatory=False, cfg=None, aspects=[])

为属性创建一个架构,该属性的值是一个字典,其中键是字符串,值是标签。这是一个依赖项属性。

此属性包含唯一的 Label 值。如果提供的是字符串而不是 Label,系统会使用 label 构造函数进行转换。标签路径的相对部分(包括可能已重命名的代码库)是相对于实例化目标的软件包来解析的。

在分析时(在规则的实现函数内),从 ctx.attr 检索属性值时,标签会被替换为相应的 Target。这样,您就可以访问当前目标依赖项的提供程序。

参数

参数 说明
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default dict;或 function; 默认值为 {}
在实例化规则时,如果未提供相应属性的值,则使用的默认值。使用字符串或 Label 函数指定默认值,例如 attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
allow_files 布尔值;或字符串序列;或 None; 默认值为 None
是否允许 File 目标平台。可以是 TrueFalse(默认值),也可以是允许的文件扩展名列表(例如 [".cc", ".cpp"])。
allow_rules 字符串的序列;或 None; 默认值为 None
允许哪些规则目标(类的名称)。此属性已弃用(仅为兼容性而保留),请改用提供程序。
providers sequence;默认值为 []
必须由出现在此属性中的任何依赖项提供的提供程序。

此实参的格式为提供程序列表的列表,即 provider() 返回的 *Info 对象(如果是旧版提供程序,则为它的字符串名称)。依赖项必须返回至少一个内部列表中提及的所有提供程序。为方便起见,此实参也可以是提供程序的一级列表,在这种情况下,它会封装在一个包含一个元素的外部列表中(即 [A, B] 表示 [[A, B]])。依赖项的规则不一定需要在其 provides 参数中宣传这些提供程序,但建议这样做。

for_dependency_resolution 默认值为 unbound
如果设置了此值,则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
flags 字符串序列; 默认值为 []
已弃用,将被移除。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
cfg 默认值为 None
属性的配置。它可以是 "exec"(表示依赖项是为 execution platform 构建的),也可以是 "target"(表示依赖项是为 target platform 构建的)。一个典型的差异示例是构建移动应用时,target platformAndroidiOS,而 execution platformLinuxmacOSWindows
aspects 方面序列;默认值为 []
应应用于此属性指定的依赖项的方面。

string_list

Attribute attr.string_list(mandatory=False, allow_empty=True, *, configurable=unbound, default=[], doc=None)

为字符串列表属性创建架构。

参数

参数 说明
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default 字符串的序列;或 NativeComputedDefault; 默认值为 []
如果实例化规则时未为此属性提供值,则要使用的默认值。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。

string_list_dict

Attribute attr.string_list_dict(allow_empty=True, *, configurable=unbound, default={}, doc=None, mandatory=False)

为包含字典的属性创建架构,其中键是字符串,值是字符串列表。

参数

参数 说明
allow_empty bool; 默认值为 True
如果属性可以为空,则为 True。
configurable bool;或无绑定; 默认值为 unbound
此实参只能针对符号宏的属性指定。

如果 configurable 明确设置为 False,则符号宏属性不可配置,也就是说,它不能采用 select() 值。如果 configurable 未绑定或明确设置为 True,则该属性可配置,并且可以采用 select() 值。

对于规则或方面的属性,configurable 必须保持未绑定状态。大多数 Starlark 规则属性始终可配置,但 attr.output()attr.output_list()attr.license() 规则属性始终不可配置。

default dict;默认值为 {}
在实例化规则时,如果未为此属性提供值,则要使用的默认值。
doc 字符串;或 None; 默认值为 None
可由文档生成工具提取的属性的说明。
mandatory bool; 默认值为 False
如果为 true,则必须明确指定值(即使它具有 default)。