attrs
type
This type is available as a global attrs
symbol, to allow the definition of attributes to the rule
function.
As an example:
rule(impl = _impl, attrs = {"foo": attrs.string(), "bar": attrs.int(default = 42)})
Most attributes take at least two optional parameters:
A
doc
parameter, which specifies documentation for the attribute.A
default
parameter, which if present specifies the default value for the attribute if omitted. If there is no default, the user of the rule must supply that parameter.
Each attribute defines what values it accepts from the user, and which values it gives to the rule.
For simple types like attrs.string
these are the same, for more complex types like attrs.dep
these
are different (string from the user, dependency to the rule).
attrs.any
def attrs.any(*, doc: str = "", default = _) -> attribute
Takes most builtin literals and passes them to the rule as a string. Discouraged, as it provides little type safety and destroys the structure.
attrs.arg
def attrs.arg(
*,
json: bool = False,
default = _,
doc: str = "",
anon_target_compatible: bool = False
) -> attribute
Takes a command line argument from the user and supplies a cmd_args
compatible value to the rule. The argument may contain special macros such as $(location :my_target)
or $(exe :my_target)
which will be replaced with references to those values in the rule. Takes in an optional anon_target_compatible
flag, which indicates whether the args can be passed into anon targets. Note that there is a slight memory hit when using this flag.
attrs.bool
def attrs.bool(*, default = _, doc: str = "") -> attribute
Takes a boolean and passes it to the rule as a boolean.
attrs.configuration_label
def attrs.configuration_label(*, doc: str = "") -> attribute
attrs.configured_dep
def attrs.configured_dep(
*,
providers: list[typing.Any] | tuple = [],
default = _,
doc: str = ""
) -> attribute
attrs.default_only
def attrs.default_only(
inner: attribute,
/,
*,
doc: str = ""
) -> attribute
Rejects all values and uses the default for the inner argument. Often used to resolve dependencies, which otherwise can't be resolved inside a rule.
attrs.default_only(attrs.dep(default = "foo//my_package:my_target"))
attrs.dep
def attrs.dep(
*,
providers: list[typing.Any] | tuple = [],
pulls_plugins: list[typing.Any] | tuple = [],
pulls_and_pushes_plugins: all_plugins | list[typing.Any] | tuple = _,
default = _,
doc: str = ""
) -> attribute
Takes a target from the user, as a string, and supplies a dependency to the rule. A target can be specified as an absolute dependency foo//bar:baz
, omitting the cell (//bar:baz
) or omitting the package name (:baz
).
If supplied the providers
argument ensures that specific providers will be present
on the dependency.
attrs.dict
def attrs.dict(
key: attribute,
value: attribute,
*,
sorted: bool = False,
default = _,
doc: str = ""
) -> attribute
Takes a dict from the user, supplies a dict to the rule.
attrs.enum
def attrs.enum(
variants: list[str] | tuple[str, ...],
/,
*,
default = _,
doc: str = ""
) -> attribute
Takes a string from one of the variants given, and gives that string to the rule. Strings are matched case-insensitively, and always passed to the rule lowercase.
attrs.exec_dep
def attrs.exec_dep(
*,
providers: list[typing.Any] | tuple = [],
default = _,
doc: str = ""
) -> attribute
Takes a target from the user, as a string, and supplies a dependency to the rule. The dependency will transition to the execution platform. Use exec_dep
if you plan to execute things from this dependency as part of the compilation.
attrs.int
def attrs.int(*, default = _, doc: str = "") -> attribute
Takes an int from the user, supplies an int to the rule.
attrs.label
def attrs.label(*, default = _, doc: str = "") -> attribute
Takes a target (as per deps
) and passes a label
to the rule. Validates that the target exists, but does not introduce a dependency on it.
attrs.list
def attrs.list(
inner: attribute,
/,
*,
default = _,
doc: str = ""
) -> attribute
Takes a list from the user, supplies a list to the rule.
attrs.named_set
def attrs.named_set(
value_type: attribute,
/,
*,
sorted: bool = False,
default = _,
doc: str = ""
) -> attribute
attrs.one_of
def attrs.one_of(*args, default = _, doc: str = "") -> attribute
Given a list of alternative attributes, selects the first that matches and gives that to the rule.
attrs.option
def attrs.option(
inner: attribute,
/,
*,
default = _,
doc: str = ""
) -> attribute
Takes a value that may be None
or some inner type, and passes either None
or the value corresponding to the inner to the rule. Often used to make a rule optional:
attrs.option(attr.string(), default = None)
attrs.plugin_dep
def attrs.plugin_dep(
*,
kind,
default = _,
doc: str = ""
) -> attribute
attrs.query
def attrs.query(*, doc: str = "") -> attribute
attrs.regex
def attrs.regex(*, default = _, doc: str = "") -> attribute
Currently an alias for attrs.string
.
attrs.set
def attrs.set(
value_type: attribute,
/,
*,
sorted: bool = False,
default = _,
doc: str = ""
) -> attribute
attrs.source
def attrs.source(
*,
allow_directory: bool = False,
default = _,
doc: str = ""
) -> attribute
Takes a source file from the user, supplies an artifact to the rule. The source file may be specified as a literal string (representing the path within this package), or a target (which must have a DefaultInfo
with a default_outputs
value).
attrs.split_transition_dep
def attrs.split_transition_dep(
*,
providers: list[typing.Any] | tuple = [],
cfg,
default = _,
doc: str = ""
) -> attribute
attrs.string
def attrs.string(
*,
default = _,
validate = _,
doc: str = ""
) -> attribute
Takes a string from the user, supplies a string to the rule.
attrs.toolchain_dep
def attrs.toolchain_dep(
*,
providers: list[typing.Any] | tuple = [],
default = _,
doc: str = ""
) -> attribute
Takes a target from the user, as a string, and supplies a dependency to the rule. The dependency will be a toolchain dependency, meaning that its execution platform dependencies will be used to select the execution platform for this rule.
attrs.transition_dep
def attrs.transition_dep(
*,
providers: list[typing.Any] | tuple = [],
cfg,
default = _,
doc: str = ""
) -> attribute
attrs.tuple
def attrs.tuple(*args, default = _, doc: str = "") -> attribute
Takes a tuple of values and gives a tuple to the rule.
attrs.versioned
def attrs.versioned(value_type: attribute, *, doc: str = "") -> attribute