4.1.3 Symbolic Macros (Bazel 8+)

Symbolic macros are the Bazel 8 macro form for BUILD-file APIs that Bazel can understand as structured declarations. They still run in the loading phase and still instantiate existing rules or macros, but their macro() declaration gives Bazel a typed attribute schema, a target namespace, macro-scoped visibility, and enough constraints to support future lazy expansion.¹

A Macro With A Declared Shape

A symbolic macro is defined by assigning the result of macro() to a global value in a .bzl file. The declaration names an implementation function and an attrs dictionary. The implementation function must accept at least name and visibility, then declares targets by calling rules or other macros.²

# //tools/images:defs.bzl
def _miniature_impl(name, visibility, src, size, **kwargs):
    native.genrule(
        name = name,
        visibility = visibility,
        srcs = [src],
        outs = [name + "_small_" + src.name],
        cmd = "convert $< -resize " + size + " $@",
        **kwargs
    )

miniature = macro(
    doc = "Create a resized image.",
    implementation = _miniature_impl,
    inherit_attrs = native.genrule,
    attrs = {
        "src": attr.label(
            allow_single_file = True,
            configurable = False,
            doc = "Image file.",
        ),
        "size": attr.string(
            default = "100x100",
            configurable = False,
        ),
        "srcs": None,
        "cmd": None,
        "outs": None,
    },
)

The call site still looks like a rule-shaped BUILD declaration:

load("//tools/images:defs.bzl", "miniature")

miniature(
    name = "logo",
    src = "logo.png",
    tags = ["manual"],
)

This example wraps native.genrule(), so it remains macro territory: the macro creates an existing rule target with a clearer project-level API. If the abstraction needs custom providers, action registration, toolchain resolution, or analyzed dependency data, it belongs in 4.2 Custom Rules, Providers & Actions, not in a macro.³

Attributes Are An API, Not Just Parameters

Legacy macros receive ordinary Starlark parameters. Symbolic macros receive declared attributes. name and visibility are implicit, while user-facing parameters are listed in attrs with types such as attr.label, attr.label_list, attr.string, or attr.bool.⁴ That makes the macro API visible to documentation and tooling, and it lets Bazel validate values before the macro body silently builds the wrong target family.

Label attributes are especially important. If the caller passes a string where a label is expected, Bazel converts it using the caller's package context.⁵ That preserves the normal BUILD-file behavior for caller-supplied inputs while removing a class of legacy macro bugs around Label() versus native.package_relative_label().⁶

inherit_attrs is the ergonomic bridge for wrapper macros. A macro can inherit public attributes from a rule, another macro, or "common", override selected attributes, and remove inherited ones by setting them to None.⁷ When a non-mandatory inherited attribute is absent, its value is None in the outer macro, even if the wrapped rule has a different apparent default. That is deliberate: forwarding None behaves like omitting the attribute, which preserves computed defaults and query output semantics.⁸

The Name Is A Namespace

Targets created by a symbolic macro must either use the macro's name exactly, or start with that name followed by _, -, or .. A call such as miniature(name = "logo") can create logo, logo_small, logo-test, or logo.preview, but not thumbnail.⁹

This is more than style. The naming rule tells Bazel which macro instance is responsible for a target label. Targets or files that violate the naming convention may be declared, but cannot be built or used as dependencies.¹⁰ The same convention is the foundation for lazy macro expansion: Bazel can eventually skip unrelated symbolic macros when the requested target's name clearly belongs to another namespace.¹¹

Legacy macro authors often used the same naming convention voluntarily. Symbolic macros turn it into an enforceable contract. That protects neighboring target names in a package and makes generated helper names less likely to become accidental public APIs.

Visibility Is Scoped To The Macro

Symbolic macro visibility is the biggest behavioral difference from 4.1.2 Legacy Macros. Legacy macros are transparent to the visibility system, so //visibility:private on a helper target still leaves it visible to other targets in the same package. Symbolic macros change the "location" used by visibility checks: a target declared inside the macro is checked as belonging to the macro definition context, not merely the caller's package.¹²

By default, a target declared inside a symbolic macro is internal to the macro. The caller's package-level default_visibility does not apply inside the macro.¹³ To export a target as part of the macro's API, pass the macro implementation's visibility parameter through to the target:

def _bundle_impl(name, visibility, srcs):
    native.filegroup(
        name = name + "_internal_files",
        srcs = srcs,
    )

    native.genrule(
        name = name,
        srcs = [name + "_internal_files"],
        outs = [name + ".txt"],
        cmd = "cat $(SRCS) > $@",
        visibility = visibility,
    )

Here :bundle_internal_files is an implementation detail, while :bundle is exported according to the macro call's visibility. This connects back to the target-visibility basics from 0.2.4 Visibility, but the unit of encapsulation is now the macro API rather than only the package.

The same rule helps tools. A tool used by the macro body only needs to be visible to the package that defines the macro, not to every package that might call it.¹⁴ When macros call submacros, Bazel also has a delegation mechanism for labels passed through label-typed attributes, so composed macros can preserve visibility privileges without exposing helper targets to callers.¹⁵

select() Must Be A Design Choice

Symbolic macro attributes are configurable by default when their type supports it. If a caller passes a plain value to a configurable attribute, the macro implementation sees it as a trivial select({"//conditions:default": ...}).¹⁶ This is intentionally annoying in the right place: if the macro tries to index, branch on, or mutate a configurable value as if it were an ordinary list or bool, it fails while the macro author can still fix the API.

Use configurable = False when the macro must inspect the value during loading. The image example marks src non-configurable because the macro uses src.name to construct an output filename, and marks size non-configurable because the macro concatenates it into the generated command string. A select() cannot produce either one loading-phase value.¹⁷ A boolean such as create_test often deserves the same treatment, because a macro cannot know which branch of a select() will be chosen later during analysis.¹⁸

Forwarding configurable values is different. If the macro only passes deps, srcs, or copts through to a generated rule, keeping the attribute configurable is usually correct: the rule target will receive the configurable expression and Bazel will resolve it in analysis.¹⁹ The boundary is the same phase boundary from 4.1.1 Macro vs Rule Decision Framework. A macro may shape declarations around the syntax it receives. It may not inspect configured target values, providers, or toolchain results.

Restrictions Are Part Of The Feature

Symbolic macros are deliberately less free-form than legacy macros. They may not return values, mutate their arguments, call native.package(), call native.glob(), call native.environment_group(), or call native.existing_rules() unless they are declared as rule finalizers.²⁰ They also cannot refer to undeclared input files that were not passed through an argument.²¹

Those restrictions are not arbitrary loss of power. They prevent side effects between macros, keep BUILD files readable for tools, and make lazy evaluation possible.²² If a legacy macro depends on glob() or native.existing_rules(), migrate the shape carefully: pass the glob() result from the BUILD file, keep a small legacy wrapper where compatibility requires it, or use 4.1.4 Rule Finalizers for the package-wide epilogue pattern.²³

Inspect the typed attribute contract and private helper naming in the runnable glyph_app symbolic macro.