4.1.1 Macro vs Rule Decision Framework

The macro-vs-rule decision is not about which abstraction feels more "Bazel-native." It is about which build phase should carry the behavior. A macro is a loading-phase convenience for declaring existing targets. A rule is an analysis-phase contract that creates providers, actions, outputs, runfiles, and toolchain-aware behavior.¹

Start With The Phase Boundary

Macros run while Bazel reads BUILD files. They call rules or other macros, and by the end of loading Bazel has concrete targets to analyze.² That makes macros a good fit when the shape of the build graph is already expressible with existing rules, but the BUILD files have become repetitive or hard to read.³

Rules run later. A rule implementation receives ctx during analysis, inspects configured attributes and providers from direct dependencies, declares outputs, registers actions, and returns providers.⁴ That is a different kind of power: a rule can create a new target kind with a real contract for downstream rules.

The shortest useful distinction is the one from the symbolic macros design: symbolic macros cannot have their own dependencies or propagate providers, while rules cannot instantiate other rules.⁵ If you need to stamp out several existing targets, you are in macro territory. If you need a target to communicate new semantic information to its consumers, you are in rule territory.

Use A Macro For BUILD-File Shape

Use a macro when you want a better BUILD API over existing targets. Typical macro work includes wrapping a genrule, creating a small family of related targets, forwarding common attributes, or encoding a project convention once instead of repeating it in every package.⁶

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

image_asset(
    name = "logo",
    src = "logo.png",
    size = "100x100",
)

That macro can expand to an existing rule such as native.genrule() or a better tool-running rule, then let ordinary targets depend on :logo.⁷ The macro has made the call site smaller and more intentional, but it has not changed what Bazel can fundamentally model. Bazel still sees generated rule targets after loading.

Choose the macro style by constraints, not by novelty. Legacy macros are still appropriate for simple wrappers and compatibility. Symbolic macros are worth the extra structure when typed attributes, inherited attributes, automatic label and select() handling, naming constraints, or macro-private visibility solve a real problem.^8,9

Use A Rule For A New Target Contract

Write a rule when the abstraction needs to participate in analysis, not just shorten declarations. The common signals are concrete:

This is why language support is usually a ruleset, not a pile of macros. A language rule has to gather transitive compile data, choose tools, register compiler actions, expose providers such as compilation info, and make downstream targets understand what was produced.

The Escalation Ladder

Start as low as the problem allows:

1. Use an existing rule directly when one BUILD call is clear enough.
2. Wrap it in a legacy macro when repetition or convention deserves one project-level API.
3. Use a symbolic macro when typed attributes, inherited attributes, naming constraints, or private helper targets matter.
4. Move to a custom rule when the abstraction needs actions, providers, toolchains, custom outputs, runfiles, or analysis-time validation.

This ladder keeps the first version cheap while leaving an honest migration path. It also prevents the two common failures: writing a custom rule for simple boilerplate, or stretching a macro until it becomes a hidden rule without the APIs rules provide.

Watch For Macro Smells

A macro is still loading-phase code. If it starts branching on things Bazel only knows after configuration, it is probably in the wrong layer. select() values are especially revealing: in macros they are still opaque configurable expressions, while rules see resolved configured attributes during analysis.¹⁶ If the macro needs to inspect the selected value to decide what actions or providers exist, move that logic into a rule or push the condition down into attributes of existing rules.

String-building is another smell. A little naming convention is fine. Complex label rewriting, hidden internal target names, or long chains of generated targets are signs that users may start depending on implementation details. Symbolic macros reduce that risk with naming constraints and macro-private visibility, but they do not turn macro internals into providers or actions.¹⁷

Genrule wrappers deserve the same caution. A tool invocation with known inputs, outputs, and command-line flags is often enough, and the common guidance is to reach for genrule-like helpers plus a macro before writing a custom rule.¹⁸ But once the wrapper needs provider interop, persistent workers, toolchain resolution, or output-dependent action choices, the custom rule is no longer accidental complexity. It is the correct abstraction.

Compare both choices in one runnable file: glyph_legacy_app and glyph_app expand to the same target shape while exposing different loading-phase contracts.