.bzl files

Implicit attributes starting with _ must have default values, and have type label or label_list.

Explicit attributes must have type string, and must use the values restriction. Explicit attributes restrict the aspect to only be used with rules that have attributes of the same name, type, and valid values according to the restriction.

An unnested list of providers will automatically be converted to a list containing one list of providers. That is, [FooInfo, BarInfo] will automatically be converted to [[FooInfo, BarInfo]].

To make some rule (e.g. some_rule) targets visible to an aspect, some_rule must advertise all providers from at least one of the required providers lists. For example, if the required_providers of an aspect are [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], this aspect can see some_rule targets if and only if some_rule provides FooInfo, or BarInfo, or both BazInfo and QuxInfo.

An unnested list of providers will automatically be converted to a list containing one list of providers. That is, [FooInfo, BarInfo] will automatically be converted to [[FooInfo, BarInfo]].

To make another aspect (e.g. other_aspect) visible to this aspect, other_aspect must provide all providers from at least one of the lists. In the example of [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], this aspect can see other_aspect if and only if other_aspect provides FooInfo, or BarInfo, or both BazInfo and QuxInfo.

It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.

Each element of the list is an *Info object returned by provider(), except that a legacy provider is represented by its string name instead.When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The required_providers field of an aspect does, however, require that providers are specified here.

For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta_output']`, where `beta_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply_to_generating_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`.

False by default.

• list of fields:
  

  provider(fields = ['a', 'b'])

• dictionary field name -> documentation:
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

A precise description follows; see Rules (Custom initialization of providers) for an intuitive discussion and use cases.

Let P be the provider symbol created by calling provider(). Conceptually, an instance of P is generated by calling a default constructor function c(*args, **kwargs), which does the following:

• If args is non-empty, an error occurs.
• If the fields parameter was specified when provider() was called, and if kwargs contains any key that was not listed in fields, an error occurs.
• Otherwise, c returns a new instance that has, for each k: v entry in kwargs, a field named k with value v.

MyInfo = provider()
m = MyInfo(foo = 1)

But in the case where init is specified, the call P(*args, **kwargs) will perform the following steps instead:

1. The callback is invoked as init(*args, **kwargs), that is, with the exact same positional and keyword arguments as were passed to P.
2. The return value of init is expected to be a dictionary, d, whose keys are field name strings. If it is not, an error occurs.
3. A new instance of P is generated as if by calling the default constructor with d's entries as keyword arguments, as in c(**d).

NB: the above steps imply that an error occurs if *args or **kwargs does not match init's signature, or the evaluation of init's body fails (perhaps intentionally via a call to fail()), or if the return value of init is not a dictionary with the expected schema.

In this way, the init callback generalizes normal provider construction by allowing positional arguments and arbitrary logic for preprocessing and validation. It does not enable circumventing the list of allowed fields.

When init is specified, the return value of provider() becomes a tuple (P, r), where r is the raw constructor. In fact, the behavior of r is exactly that of the default constructor function c discussed above. Typically, r is bound to a variable whose name is prefixed with an underscore, so that only the current .bzl file has direct access to it:

MyInfo, _new_myinfo = provider(init = ...)

A schema for defining predeclared outputs. Unlike output and output_list attributes, the user does not specify the labels for these files. See the Rules page for more on predeclared outputs.

The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass outputs = _my_func with the definition def _my_func(srcs, deps): ..., the function has access to the attributes srcs and deps. Whether the dictionary is specified directly or via a function, it is interpreted as follows.

Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's File in ctx.outputs. The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form "%{ATTR}" with a string formed from the value of the attribute ATTR:

• String-typed attributes are substituted verbatim.
• Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label "//pkg:a/b.c" becomes "a/b".
• Output-typed attributes become the part of the label after the package, including the file extension (for the above example, "a/b.c").
• All list-typed attributes (for example, attr.label_list) used in placeholders are required to have exactly one element. Their conversion is the same as their non-list version (attr.label).
• Other attribute types may not appear in placeholders.
• The special non-attribute placeholders %{dirname} and %{basename} expand to those parts of the rule's label, excluding its package. For example, in "//pkg:a/b.c", the dirname is a and the basename is b.c.

In practice, the most common substitution placeholder is "%{name}". For example, for a target named "foo", the outputs dict {"bin": "%{name}.exe"} predeclares an output named foo.exe that is accessible in the implementation function as ctx.outputs.bin.

It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here.

Each element of the list is an *Info object returned by provider(), except that a legacy provider is represented by its string name instead.When a target of the rule is used as a dependency for a target that declares a required provider, it is not necessary to specify that provider here. It is enough that the implementation function returns it. However, it is considered best practice to specify it, even though this is not required. The required_providers field of an aspect does, however, require that providers are specified here.

Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See Testing for guidance.

If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using analysis_test_transition on its attributes, but opts into some restrictions:

• Targets of this rule are limited in the number of transitive dependencies they may have.
• The rule is considered a test rule (as if test=True were set). This supersedes the value of test
• The rule implementation function may not register actions. Instead, it must register a pass/fail result via providing AnalysisTestResultInfo.

The function is called at load time for each instance of the rule. It's called with name and the values of public attributes defined bythe rule (not with generic attributes, for example tags).

It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning None as value results in using the default value specified in the attribute definition.

Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning None).

Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases.

It's a good practice to use **kwargs for attributes that are not handled.

In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about.

Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be:

• FilesToRunProvider for label attributes with executable=True
• File for label attributes with allow_single_file=True
• Target for all other label attributes
• [Target] for all label-list attributes

Package specifications follow the same format as for package_group, except that negative package specifications are not permitted. That is, a specification may have the forms:

• "//foo": the package //foo
• "//foo/...": the package //foo and all of its subpackages.
• "public" or "private": all packages or no packages, respectively

The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository.

If value is a list of strings, the set of packages granted visibility to this module is the union of the packages represented by each specification. (An empty list has the same effect as private.) If value is a single string, it is treated as if it were the singleton list [value].

Note that the flags --incompatible_package_group_has_public_syntax and --incompatible_fix_package_group_reporoot_syntax have no effect on this argument. The "public" and "private" values are always available, and "//..." is always interpreted as "all packages in the current repository".