4.8.2 Aspect Implementation Basics

An aspect is declared with aspect() and an implementation function — the surface is parallel to 4.2.1 Rule Function, but, during analysis, its result attaches to existing dependency edges instead of defining a new target kind.¹ The aspect declaration says how the shadow graph from 4.8.1 Aspects — Cross-Cutting Graph Traversal is built and what each visited node may produce: providers, actions, and named output groups.²

The aspect() Declaration

aspect() is a global factory. Its return value must be stored in a global symbol in a .bzl file so Bazel and users can refer to it by <file label>%<global name>.³ The smallest useful declaration names the implementation function and the edges to follow:

print_aspect = aspect(
    implementation = _print_aspect_impl,
    attr_aspects = ["deps"],
    required_providers = [CcInfo],
)

The most important parameters at this level are:⁴

Other parameters are useful but secondary for a first aspect. toolchains, exec_groups, and toolchains_aspects connect the aspect to platform-aware tooling. requires, required_aspect_providers, and provides chain aspects together. propagation_predicate and the function form of attr_aspects enable runtime propagation decisions — those belong in 4.8.6 Dynamic Aspect Propagation.¹⁰ apply_to_generating_rules redirects propagation from an output file back to the rule that generates it.¹¹

The Implementation Function

An aspect implementation has exactly two parameters: the target it is being applied to and ctx, the analysis context.¹² It receives a Target and a ctx, and returns a list of provider instances.¹³ 4.1.7 Starlark Callback Contexts & Types maps these nominal types, the callback's phase, its return value, and its effects to the other Starlark extension points.

def _print_aspect_impl(target, ctx):
    if hasattr(ctx.rule.attr, "srcs"):
        for src in ctx.rule.attr.srcs:
            for f in src.files.to_list():
                print(f.path)
    return []

Two things separate this from a rule implementation:

• target is the visited rule's configured target. The aspect reads providers from it with the usual target[SomeInfo] indexing.¹⁴
• ctx.rule exposes the visited rule's own metadata, even though the aspect didn't declare those attributes. ctx.rule.attr is the attribute struct, ctx.rule.kind is the rule class name ("cc_library", "py_binary", …), and ctx.rule.executable / ctx.rule.file / ctx.rule.files / ctx.rule.toolchains mirror the rule's analysis-time accessors.¹⁵ ctx.rule.kind is the standard hook for rule-type-specific logic, such as "only emit a Makefile rule for cc_binary."¹⁶

ctx still gives access to the aspect's own attrs through ctx.attr and to action APIs through ctx.actions, exactly like a rule context.¹⁷ An aspect can therefore call ctx.actions.run(), declare files, and emit OutputGroupInfo the same way a rule does.¹⁸

Propagation Edges

attr_aspects is the list of attribute names the aspect follows. Common values are ["deps"] and ["deps", "exports"]. The wildcard ["*"] propagates along every attribute of every visited rule.¹⁹ Bazel rewrites the visited rule's view of those attributes for the duration of the aspect: if a target X has Y and Z in deps, then ctx.rule.attr.deps for A(X) is [A(Y), A(Z)] — Target objects that already carry the aspect's providers.²⁰ This is the mechanism behind transitive collection patterns.

This example counts matching source-file occurrences through a graph whose srcs and deps, when present, are label-list attributes. The aspect declares its own extension parameter, while the rules it visits declare srcs and deps. Shared dependencies can contribute more than once along different paths, so this is not a count of unique files.

FileCountInfo = provider(fields = {    "count": "Number of matching files",})def _file_count_aspect_impl(target, ctx):    count = 0    extension = ctx.attr.extension    if hasattr(ctx.rule.attr, "srcs"):        for src in ctx.rule.attr.srcs:            for f in src.files.to_list():                if extension in ["*", f.extension]:                    count = count + 1    if hasattr(ctx.rule.attr, "deps"):        for dep in ctx.rule.attr.deps:            count = count + dep[FileCountInfo].count    return [FileCountInfo(count = count)]file_count_aspect = aspect(    implementation = _file_count_aspect_impl,    attr_aspects = ["deps"],    attrs = {        "extension": attr.string(            default = "*",            values = ["*", "txt"],        ),    },)

The aspect reads the dep's FileCountInfo after applying itself to that dep — the recursion is implicit in the propagation list.²¹

required_providers narrows traversal to targets whose rules advertise certain providers. The value is a list of provider lists with OR-of-ANDs semantics: [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] matches a rule that provides FooInfo, or BarInfo, or both BazInfo and QuxInfo.²² Use it to keep the shadow graph focused — a Java-only aspect should not stop at cc_library nodes.²³ The wildcard ["*"] propagation combined with no required_providers is the most aggressive shape and can cause subtle problems: cc_shared_library's linking aspect uses "*" so it can reach object files reachable through any attribute, and a custom rule that incidentally returns CcInfo ends up considered for linking by accident.²⁴

Aspect Attrs

Aspects can declare their own attributes, but the rules differ from regular rules.²⁵

• Private attributes (names starting with _) must have defaults and must be of type label or label_list. They are how an aspect carries the tools and configuration files it needs without forcing every visited rule to expose them:²⁶

  attrs = {
      "_protoc": attr.label(
          default = Label("//tools:protoc"),
          executable = True,
          cfg = "exec",
      ),
  }
  

• Public attributes are parameters. In the current API reference, explicit public aspect attrs must be string attrs and use the values restriction so Bazel can validate parameter values against the consuming rule.²⁷ For command-line aspects, parameter values come from --aspects_parameters and the values restriction may be relaxed.²⁸

That public-parameter restriction is what makes the aspect-factory pattern common in production rulesets: a top-level Starlark function captures richer configuration, such as a label, and returns an aspect() whose private attr defaults to that value.²⁹

def stylelint_aspect(config):
    return aspect(
        implementation = _stylelint_impl,
        attr_aspects = ["deps"],
        attrs = {
            "_config": attr.label(default = config),
        },
    )

That is how rules_lint lets each consumer wire their own tool config without exposing a public label-typed aspect parameter.³⁰

Read Structured Hints From Visited Targets

aspect_hints is a common attribute on build rules, but it belongs to the visited target rather than to the aspect declaration. Each entry is a label to a target that can return providers carrying structured, ruleset-specific information. An aspect reads those targets through ctx.rule.attr.aspect_hints, but the visited rule's own implementation does not see this implicit attribute.³¹

For example, a language-interoperability ruleset can define a hint rule that returns InteropInfo, then let an ordinary C++ target opt into a module name:

cc_library(
    name = "codec",
    srcs = ["codec.cc"],
    aspect_hints = [":codec_interop"],
)

The consuming aspect looks for the provider rather than parsing a string:

for hint in ctx.rule.attr.aspect_hints:
    if InteropInfo in hint:
        interop = hint[InteropInfo]

This is richer than tags: a tag carries a boolean-like string, while a hint target can expose typed fields and files through providers.³¹ It is also not a general user-extension mechanism. A hint has no effect unless a particular aspect documents and reads its provider contract.

rules_swift demonstrates the production shape. C/C++ and Objective-C targets put swift_interop_hint or swift_overlay targets in aspect_hints, and the Swift Clang-module aspect reads the providers from ctx.rule.attr.aspect_hints to customize cross-language import behavior.³² Use this pattern when metadata is for an aspect attached by a reverse dependency and the original rule should not need a new public attribute or implementation change.

Returning Providers

An aspect implementation returns a list of providers, just like a rule.³³ The provider set for the aspect application A(X) is the union of the rule's providers on X and the aspect's own providers.³⁴ Two rules differ from regular rule authoring:

• An aspect must not return DefaultInfo. Default outputs belong to the rule. It is also an error if the rule and the aspect both return the same provider type — with two documented exceptions.³⁵
• OutputGroupInfo from rules and aspects is merged, as long as the rule and aspect declare different group names. InstrumentedFilesInfo from the aspect supersedes the rule's, used for coverage instrumentation.³⁶

OutputGroupInfo is therefore the standard way an aspect surfaces files to users and tools — IDE drivers, linters, and SBOM aspects use named groups so a single bazel build can request only the aspect's artifacts.³⁷

return [
    FileCountInfo(count = count),
    OutputGroupInfo(file_count_report = depset([report])),
]

Aspect-generated actions should also use stable mnemonic values. Mnemonics show up in profiles, bazel aquery, and CI logs alongside actions from regular rules.³⁸ For multi-action augmentation patterns — adding instrumentation or coverage to an existing rule's action without reconstructing its full input list — see 4.8.7 shadowed_action — Action Composition.

Two Ways To Invoke

An aspect runs only when something asks for it. There are two invocation modes, called command-line aspects and rule-propagated aspects in the official docs.³⁹

Command-line — pass --aspects and a label-style spec on a normal bazel build:⁴⁰

bazel build //pkg:app \
    --aspects=//tools/lint:linters.bzl%ruff_aspect \
    --output_groups=rules_lint_human,rules_lint_machine

The spec format is <.bzl file label>%<aspect global name>. Command-line aspects are how IDE plugins, lint drivers, and SBOM generators run aspects across an existing graph without changing any BUILD files.⁴¹

Rule-propagated — a custom rule attaches the aspect to one of its label attributes:⁴²

file_count_rule = rule(
    implementation = _file_count_rule_impl,
    attrs = {
        "deps": attr.label_list(aspects = [file_count_aspect]),
        "extension": attr.string(default = "*"),
    },
)

Here, building any file_count_rule target runs file_count_aspect on the targets in deps and on their transitive deps (because attr_aspects = ["deps"]).⁴³ Aspect parameters are taken from the requesting rule's attribute of the same name and type — that is why the rule has a matching extension attr with a default value, and why public string parameters need a values restriction on the aspect side.⁴⁴

The choice between the two is a deployment question, not an implementation one. Both run the same implementation function over the same shadow graph. They differ only in how the request reaches the graph. Lint workflows usually start as command-line aspects because they don't want to touch rule sets. Once that quality gate matures, the team may decide to fold it into the rule contract instead — that is the comparison developed in 4.8.3 Validation Actions vs Aspects.

The mini-ruleset assembles the core pieces in glyph_metadata_aspect.bzl: an implementation that registers an output, propagation over two attributes, required_providers, and an OutputGroupInfo result. Request it with bazel build //examples/basic:metadata --aspects=//tools/aspects:glyph_metadata_aspect.bzl%glyph_metadata_aspect --output_groups=glyph_metadata.