.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.

Declared attributes will convert None to the default value.

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.

By convention, the implementation function should have a named parameter for any attribute that the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited attributes which will be passed to the "main" target unchanged are passed as **kwargs.

The implementation function must not return a value. Instead, the implementation function declares targets by calling rule or macro symbols.

The name of any target or inner symbolic macro declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) must either equal name (this is referred to as the "main" target) or start with name, followed by a separator chracter ("_", "-", or ".") and a string suffix. (Targets violating this naming scheme are allowed to be declared, but cannot be built, configured, or depended upon.)

By default, targets declared by a symbolic macro (including by any Starlark function that the macro's implementation function transitively calls) are visible only in the package containing the .bzl file defining the macro. To declare targets visible externally, including to the caller of the symbolic macro, the implementation function must set visibility appropriately – typically, by passing visibility = visibility to the rule or macro symbol being called.

The following APIs are unavailable within a macro implementation function and any Starlark function it transitively calls:

• package(), licenses()
• environment_group()
• native.glob() – instead, you may pass a glob into the macro via a label list attribute
• native.subpackages()
• (allowed in rule finalizers only, see finalizer below) native.existing_rules(), native.existing_rule()
• (for WORKSPACE threads) workspace(), register_toolchains(), register_execution_platforms(), bind(), repository rule instantiation

The special name attribute is predeclared and must not be included in the dictionary. The visibility attribute name is reserved and must not be included in the dictionary.

Attributes whose names start with _ are private -- they cannot be passed at the call site of the rule. Such attributes can be assigned a default value (as in attr.label(default="//pkg:foo")) to create an implicit dependency on a label.

To limit memory usage, there is a cap on the number of attributes that may be declared.

If inherit_attrs is set to the string "common", the macro will inherit common rule attribute definitions used by all Starlark rules.

Note that if the return value of rule() or macro() was not assigned to a global variable in a .bzl file, then such a value has not been registered as a rule or macro symbol, and therefore cannot be used for inherit_attrs.

The inheritance mechanism works as follows:

1. The special name and visibility attributes are never inherited;
2. Hidden attributes (ones whose name starts with "_") are never inherited;
3. Attributes whose names are already defined in the attrs dictionary are never inherited (the entry in attrs takes precedence; note that an entry may be set to None to ensure that no attribute by that name gets defined on the macro);
4. All other attributes are inherited from the rule or macro and effectively merged into the attrs dict.

When a non-mandatory attribute is inherited, the default value of the attribute is overridden to be None, regardless of what it was specified in the original rule or macro. This ensures that when the macro forwards the attribute's value to an instance of the wrapped rule or macro – such as by passing in the unmodified **kwargs – a value that was absent from the outer macro's call will also be absent in the inner rule or macro's call (since passing None to an attribute is treated the same as omitting the attribute). This is important because omitting an attribute has subtly different semantics from passing its apparent default value. In particular, omitted attributes are not shown in some bazel query output formats, and computed defaults only execute when the value is omitted. If the macro needs to examine or modify an inherited attribute – for example, to add a value to an inherited tags attribute – you must make sure to handle the None case in the macro's implementation function.

For example, the following macro inherits all attributes from native.cc_library, except for cxxopts (which is removed from the attribute list) and copts (which is given a new definition). It also takes care to checks for the default None value of the inherited tags attribute before appending an additional tag.

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

If inherit_attrs is set, the macro's implementation function must have a **kwargs residual keyword parameter.

By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main" rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have a parameter in the implementation function's parameter list, and will simply be passed via **kwargs. It can be convenient for the implementation function to have explicit parameters for some inherited attributes (most commonly, tags and testonly) if the macro needs to pass those attributes to both "main" and non-"main" targets – but if the macro also needs to examine or manipulate those attributes, you must take care to handle the None default value of non-mandatory inherited attributes.

Unlike ordinary symbolic macros, rule finalizers may call native.existing_rule() and native.existing_rules() to query the set of non-finalizer rule targets defined in the current package. Note that native.existing_rule() and native.existing_rules() cannot access the targets defined by any rule finalizer, including this one.

• 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 = ...)

Declared attributes will convert None to the default value.

Declared attributes will convert None to the default value.

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 by the 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

Note that unlike rule(), aspect() and repository_rule(), declared attributes will not convert None to the default value. For the default to be used, the attribute must be omitted entirely by the caller.

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".