attr
This is a top-level module for defining the attribute schemas of a rule or aspect. Each function returns an object representing the schema of a single attribute. These objects are used as the values of theattrs
dictionary argument of rule()
and aspect()
.See the Rules page for more on defining and using attributes.
Members
bool
Attribute attr.bool(default=False, doc='', mandatory=False)Creates a schema for a boolean attribute.
Parameters
Parameter | Description |
---|---|
default
|
A default value to use if no value for this attribute is given when instantiating the rule. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
int
Attribute attr.int(default=0, doc='', mandatory=False, values=[])Creates a schema for an integer attribute.
Parameters
Parameter | Description |
---|---|
default
|
A default value to use if no value for this attribute is given when instantiating the rule. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
values
|
The list of allowed values for the attribute. An error is raised if any other value is given. |
int_list
Attribute attr.int_list(mandatory=False, allow_empty=True, *, default=[], doc='')Creates a schema for a list-of-integers attribute.
Parameters
Parameter | Description |
---|---|
mandatory
|
If true, the value must be specified explicitly (even if it has a |
allow_empty
|
True if the attribute can be empty. |
default
|
A default value to use if no value for this attribute is given when instantiating the rule. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
label
Attribute attr.label(default=None, doc='', executable=False, allow_files=None, allow_single_file=None, mandatory=False, providers=[], allow_rules=None, cfg=None, aspects=[])Creates a schema for a label attribute. This is a dependency attribute.
This attribute contains unique Label
values. If a string is supplied in place of a Label
, it will be converted using the label constructor. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.
At analysis time (within the rule's implementation function), when retrieving the attribute value from ctx.attr
, labels are replaced by the corresponding Target
s. This allows you to access the providers of the currrent target's dependencies.
In addition to ordinary source files, this kind of attribute is often used to refer to a tool -- for example, a compiler. Such tools are considered to be dependencies, just like source files. To avoid requiring users to specify the tool's label every time they use the rule in their BUILD files, you can hard-code the label of a canonical tool as the default
value of this attribute. If you also want to prevent users from overriding this default, you can make the attribute private by giving it a name that starts with an underscore. See the Rules page for more information.
Parameters
Parameter | Description |
---|---|
default
|
A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
executable
|
True if the dependency has to be executable. This means the label must refer to an executable file, or to a rule that outputs an executable file. Access the label with |
allow_files
|
Whether |
allow_single_file
|
This is similar to |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
providers
|
The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- |
allow_rules
|
Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. |
cfg
|
Configuration of the attribute. It can be either |
aspects
|
Aspects that should be applied to the dependency or dependencies specified by this attribute. |
label_keyed_string_dict
Attribute attr.label_keyed_string_dict(allow_empty=True, *, default={}, doc='', allow_files=None, allow_rules=None, providers=[], flags=[], mandatory=False, cfg=None, aspects=[])Creates a schema for an attribute holding a dictionary, where the keys are labels and the values are strings. This is a dependency attribute.
This attribute contains unique Label
values. If a string is supplied in place of a Label
, it will be converted using the label constructor. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.
At analysis time (within the rule's implementation function), when retrieving the attribute value from ctx.attr
, labels are replaced by the corresponding Target
s. This allows you to access the providers of the currrent target's dependencies.
Parameters
Parameter | Description |
---|---|
allow_empty
|
True if the attribute can be empty. |
default
|
A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
allow_files
|
Whether |
allow_rules
|
Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. |
providers
|
The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- |
flags
|
Deprecated, will be removed. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
cfg
|
Configuration of the attribute. It can be either |
aspects
|
Aspects that should be applied to the dependency or dependencies specified by this attribute. |
label_list
Attribute attr.label_list(allow_empty=True, *, default=[], doc='', allow_files=None, allow_rules=None, providers=[], flags=[], mandatory=False, cfg=None, aspects=[])Creates a schema for a list-of-labels attribute. This is a dependency attribute.
This attribute contains unique Label
values. If a string is supplied in place of a Label
, it will be converted using the label constructor. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.
At analysis time (within the rule's implementation function), when retrieving the attribute value from ctx.attr
, labels are replaced by the corresponding Target
s. This allows you to access the providers of the currrent target's dependencies.
Parameters
Parameter | Description |
---|---|
allow_empty
|
True if the attribute can be empty. |
default
|
A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
allow_files
|
Whether |
allow_rules
|
Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead. |
providers
|
The providers that must be given by any dependency appearing in this attribute. The format of this argument is a list of lists of providers -- |
flags
|
Deprecated, will be removed. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
cfg
|
Configuration of the attribute. It can be either |
aspects
|
Aspects that should be applied to the dependency or dependencies specified by this attribute. |
output
Attribute attr.output(doc='', mandatory=False)Creates a schema for an output (label) attribute.
This attribute contains unique Label
values. If a string is supplied in place of a Label
, it will be converted using the label constructor. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.
At analysis time, the corresponding File
can be retrieved using ctx.outputs
.
Parameters
Parameter | Description |
---|---|
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
output_list
Attribute attr.output_list(allow_empty=True, *, doc='', mandatory=False)Creates a schema for a list-of-outputs attribute.
This attribute contains unique Label
values. If a string is supplied in place of a Label
, it will be converted using the label constructor. The relative parts of the label path, including the (possibly renamed) repository, are resolved with respect to the instantiated target's package.
At analysis time, the corresponding File
can be retrieved using ctx.outputs
.
Parameters
Parameter | Description |
---|---|
allow_empty
|
True if the attribute can be empty. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
string
Attribute attr.string(default='', doc='', mandatory=False, values=[])Creates a schema for a string attribute.
Parameters
Parameter | Description |
---|---|
default
|
A default value to use if no value for this attribute is given when instantiating the rule. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
values
|
The list of allowed values for the attribute. An error is raised if any other value is given. |
string_dict
Attribute attr.string_dict(allow_empty=True, *, default={}, doc='', mandatory=False)Creates a schema for an attribute holding a dictionary, where the keys and values are strings.
Parameters
Parameter | Description |
---|---|
allow_empty
|
True if the attribute can be empty. |
default
|
A default value to use if no value for this attribute is given when instantiating the rule. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |
string_list
Attribute attr.string_list(mandatory=False, allow_empty=True, *, default=[], doc='')Creates a schema for a list-of-strings attribute.
Parameters
Parameter | Description |
---|---|
mandatory
|
If true, the value must be specified explicitly (even if it has a |
allow_empty
|
True if the attribute can be empty. |
default
|
A default value to use if no value for this attribute is given when instantiating the rule. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
string_list_dict
Attribute attr.string_list_dict(allow_empty=True, *, default={}, doc='', mandatory=False)Creates a schema for an attribute holding a dictionary, where the keys are strings and the values are lists of strings.
Parameters
Parameter | Description |
---|---|
allow_empty
|
True if the attribute can be empty. |
default
|
A default value to use if no value for this attribute is given when instantiating the rule. |
doc
|
A description of the attribute that can be extracted by documentation generating tools. |
mandatory
|
If true, the value must be specified explicitly (even if it has a |