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 the attrs dictionary argument of rule() and aspect().

See the Rules page for more on defining and using attributes.

Methods

bool

Attribute attr.bool(default=False, doc='', mandatory=False)

Creates a schema for a boolean attribute.

Parameters

Parameter Description
default

bool; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).

int

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

Creates a schema for an integer attribute.

Parameters

Parameter Description
default

int; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
values

sequence of ints

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, non_empty=False, allow_empty=True, *, default=[], doc='')

Creates a schema for a list-of-integers attribute.

Parameters

Parameter Description
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
non_empty

bool

True if the attribute must not be empty. Deprecated: Use allow_empty instead.
allow_empty

bool

True if the attribute can be empty.
default

sequence of ints; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

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, single_file=False, cfg=None, aspects=[])

Creates a schema for a label attribute. This is a dependency attribute.

This attribute contains 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 Targets. 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

Label; or string; or LateBoundDefault; or function

A default value to use if no value for this attribute is given when instantiating the rule.Use a string or the Label function to specify a default value, for example, attr.label(default = "//a:b").
doc

string

A description of the attribute that can be extracted by documentation generating tools.
executable

bool

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 ctx.executable.<attribute_name>.
allow_files

Whether File targets are allowed. Can be True, False (default), or a list of file extensions that are allowed (for example, [".cc", ".cpp"]).
allow_single_file

This is similar to allow_files, with the restriction that the label must correspond to a single File. Access it through ctx.file.<attribute_name>.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
providers

sequence

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 -- *Info objects returned by provider() (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element.
allow_rules

sequence of strings

Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.
single_file

bool

Deprecated: Use allow_single_file instead. If True, the label must correspond to a single File. Access it through ctx.file.<attribute_name>.
cfg

Configuration of the attribute. It can be either "host" or "target". This parameter is required if executable is True.
aspects

sequence of 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, non_empty=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 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 Targets. This allows you to access the providers of the currrent target's dependencies.

Parameters

Parameter Description
allow_empty

bool

True if the attribute can be empty.
default

dict; or function

A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the Label function to specify default values, for example, attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"}).
doc

string

A description of the attribute that can be extracted by documentation generating tools.
allow_files

Whether File targets are allowed. Can be True, False (default), or a list of file extensions that are allowed (for example, [".cc", ".cpp"]).
allow_rules

sequence of strings

Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.
providers

sequence

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 -- *Info objects returned by provider() (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element.
flags

sequence of strings

Deprecated, will be removed.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
non_empty

bool

True if the attribute must not be empty. Deprecated: Use allow_empty instead.
cfg

Configuration of the attribute. It can be either "host" or "target".
aspects

sequence of 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, non_empty=False, cfg=None, aspects=[])

Creates a schema for a list-of-labels attribute. This is a dependency attribute.

This attribute contains 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 Targets. This allows you to access the providers of the currrent target's dependencies.

Parameters

Parameter Description
allow_empty

bool

True if the attribute can be empty.
default

sequence of Labels; or function

A default value to use if no value for this attribute is given when instantiating the rule.Use strings or the Label function to specify default values, for example, attr.label_list(default = ["//a:b", "//a:c"]).
doc

string

A description of the attribute that can be extracted by documentation generating tools.
allow_files

Whether File targets are allowed. Can be True, False (default), or a list of file extensions that are allowed (for example, [".cc", ".cpp"]).
allow_rules

sequence of strings

Which rule targets (name of the classes) are allowed. This is deprecated (kept only for compatibility), use providers instead.
providers

sequence

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 -- *Info objects returned by provider() (or in the case of a legacy provider, its string name). The dependency must return ALL providers mentioned in at least ONE of the inner lists. As a convenience, this argument may also be a single-level list of providers, in which case it is wrapped in an outer list with one element.
flags

sequence of strings

Deprecated, will be removed.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
non_empty

bool

True if the attribute must not be empty. Deprecated: Use allow_empty instead.
cfg

Configuration of the attribute. It can be either "host" or "target".
aspects

sequence of Aspects

Aspects that should be applied to the dependency or dependencies specified by this attribute.

license

Attribute attr.license(default=None, doc='', mandatory=False)

Creates a schema for a license attribute.

Parameters

Parameter Description
default

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).

output

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

Creates a schema for an output (label) attribute.

This attribute contains 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
default

Label; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).

output_list

Attribute attr.output_list(allow_empty=True, *, default=[], doc='', mandatory=False, non_empty=False)

Creates a schema for a list-of-outputs attribute.

This attribute contains 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

bool

True if the attribute can be empty.
default

sequence of Labels; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
non_empty

bool

True if the attribute must not be empty. Deprecated: Use allow_empty instead.

string

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

Creates a schema for a string attribute.

Parameters

Parameter Description
default

string

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
values

sequence of strings

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, non_empty=False)

Creates a schema for an attribute holding a dictionary, where the keys and values are strings.

Parameters

Parameter Description
allow_empty

bool

True if the attribute can be empty.
default

dict; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
non_empty

bool

True if the attribute must not be empty. Deprecated: Use allow_empty instead.

string_list

Attribute attr.string_list(mandatory=False, non_empty=False, allow_empty=True, *, default=[], doc='')

Creates a schema for a list-of-strings attribute.

Parameters

Parameter Description
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
non_empty

bool

True if the attribute must not be empty. Deprecated: Use allow_empty instead.
allow_empty

bool

True if the attribute can be empty.
default

sequence of strings; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

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, non_empty=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

bool

True if the attribute can be empty.
default

dict; or function

A default value to use if no value for this attribute is given when instantiating the rule.
doc

string

A description of the attribute that can be extracted by documentation generating tools.
mandatory

bool

If true, the value must be specified explicitly (even if it has a default).
non_empty

bool

True if the attribute must not be empty. Deprecated: Use allow_empty instead.