属性

每夜版 · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7
这是一个用于定义规则或方面的属性架构的顶级模块。每个函数都会返回一个表示单个属性的架构的对象。这些对象用作 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 目标平台。可以是 True、False（默认值），也可以是允许的文件扩展名列表（例如 [".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 对象（如果是旧版提供程序，则为提供程序的字符串名称）。依赖项必须返回至少一个内部列表中提及的所有提供程序。为方便起见，此实参也可以是提供商的单级列表，在这种情况下，它会封装在包含一个元素的外层列表中。依赖项规则的 provides 参数中不一定需要宣传这些提供程序，但这是最佳实践。

for_dependency_resolution 默认值为 unbound
如果设置了此值，则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
allow_rules 字符串的序列；或 None； 默认值为 None
允许哪些规则目标（类的名称）。此属性已弃用（仅为兼容性而保留），请改用提供程序。
cfg 默认值为 None
属性的配置。它可以是 "exec"（表示依赖项是为 execution platform 构建的），也可以是 "target"（表示依赖项是为 target platform 构建的）。一个典型的区别示例是构建移动应用时，target platform 为 Android 或 iOS，而 execution platform 为 Linux、macOS 或 Windows。如果 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, 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；或函数； 默认值为 {}
在实例化规则时，如果未提供相应属性的值，则使用的默认值。使用字符串或 Label 函数指定默认值，例如 attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})。
doc 字符串；或 None； 默认值为 None
可由文档生成工具提取的属性的说明。
allow_files 布尔值；或字符串序列；或 None； 默认值为 None
是否允许 File 目标平台。可以是 True、False（默认值），也可以是允许的文件扩展名列表（例如 [".cc", ".cpp"]）。
allow_rules 字符串的序列；或 None； 默认值为 None
允许哪些规则目标（类的名称）。此属性已弃用（仅为兼容性而保留），请改用提供程序。
providers sequence；默认值为 []
必须由出现在此属性中的任何依赖项提供的提供程序。

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

for_dependency_resolution 默认值为 unbound
如果设置了此值，则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
flags 字符串的序列； 默认值为 []
已弃用，将被移除。
mandatory bool； 默认值为 False
如果为 true，则必须明确指定值（即使它具有 default）。
cfg 默认值为 None
属性的配置。它可以是 "exec"（表示依赖项是为 execution platform 构建的），也可以是 "target"（表示依赖项是为 target platform 构建的）。一个典型的区别示例是构建移动应用时，target platform 为 Android 或 iOS，而 execution platform 为 Linux、macOS 或 Windows。
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 目标平台。可以是 True、False（默认值），也可以是允许的文件扩展名列表（例如 [".cc", ".cpp"]）。
allow_rules 字符串的序列；或 None； 默认值为 None
允许哪些规则目标（类的名称）。此属性已弃用（仅为兼容性而保留），请改用提供程序。
providers sequence；默认值为 []
必须由出现在此属性中的任何依赖项提供的提供程序。

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

for_dependency_resolution 默认值为 unbound
如果设置了此值，则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
flags 字符串的序列； 默认值为 []
已弃用，将被移除。
mandatory bool； 默认值为 False
如果为 true，则必须明确指定值（即使它具有 default）。
skip_validations 布尔值；默认值为 False
如果为 true，则不会运行来自此属性的传递依赖项的验证操作。这只是一项临时缓解措施，未来将会移除。
cfg 默认值为 None
属性的配置。它可以是 "exec"（表示依赖项是为 execution platform 构建的），也可以是 "target"（表示依赖项是为 target platform 构建的）。一个典型的区别示例是构建移动应用时，target platform 为 Android 或 iOS，而 execution platform 为 Linux、macOS 或 Windows。
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 字符串；或 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；或函数； 默认值为 {}
在实例化规则时，如果未提供相应属性的值，则使用的默认值。使用字符串或 Label 函数指定默认值，例如 attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})。
doc 字符串；或 None； 默认值为 None
可由文档生成工具提取的属性的说明。
allow_files 布尔值；或字符串序列；或 None； 默认值为 None
是否允许 File 目标平台。可以是 True、False（默认值），也可以是允许的文件扩展名列表（例如 [".cc", ".cpp"]）。
allow_rules 字符串的序列；或 None； 默认值为 None
允许哪些规则目标（类的名称）。此属性已弃用（仅为兼容性而保留），请改用提供程序。
providers sequence；默认值为 []
必须由出现在此属性中的任何依赖项提供的提供程序。

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

for_dependency_resolution 默认值为 unbound
如果设置了此值，则该属性可供实体化程序使用。只有标记了相同名称的标志的规则才能通过此类属性进行引用。
flags 字符串的序列； 默认值为 []
已弃用，将被移除。
mandatory bool； 默认值为 False
如果为 true，则必须明确指定值（即使它具有 default）。
cfg 默认值为 None
属性的配置。它可以是 "exec"（表示依赖项是为 execution platform 构建的），也可以是 "target"（表示依赖项是为 target platform 构建的）。一个典型的区别示例是构建移动应用时，target platform 为 Android 或 iOS，而 execution platform 为 Linux、macOS 或 Windows。
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）。