Migrating to Bazel Symbolic Macros

Bazel offers two macro types: legacy macros and the newer symbolic macros, introduced in Bazel 8. While legacy macros are function-based, symbolic macros are recommended for better clarity, offering features like typed arguments and controlled visibility of generated targets. This article provides guidance for experienced Bazel users on transitioning legacy macros to symbolic macros, highlighting best practices and common pitfalls.

Symbolic macros serve as templates that generate build targets during Bazel’s loading phase, differing from build rules that execute later. Unlike legacy macros, which are simple functions, symbolic macros are first-class entities with attribute similarity to build rules. They are invoked in BUILD files with attribute arguments, allowing Bazel to recognize their role in the build process and supporting potential future features like lazy evaluation—deferring target evaluation until explicitly requested.

Practical considerations include strict naming conventions: targets created by a symbolic macro must match the macro’s name or start with that name followed by an underscore, period, or hyphen. For example, a macro called `tool` can produce targets named `tool`, `tool_`, `tool.`, or `tool-`, but not `genrule`. This contrasts with legacy macros, which do not impose such constraints.

Rendering resources also differs: symbolic macros adhere to Bazel’s visibility rules and cannot access source files unless they’re explicitly passed as arguments or made public. Legacy macros, by comparison, could inline such resources directly.

In terms of attribute handling, legacy macros often used positional arguments, simplifying invocation but sacrificing explicitness. Symbolic macros rely on named attributes, enforcing clearer declarations and better compatibility with Bazel’s configuration and analysis phases.

In conclusion, migrating to symbolic macros enhances build clarity, enforceability, and future scalability within Bazel. While the transition may require adjustments—particularly in naming and resource management—it ultimately results in a more robust and maintainable build system aligned with Bazel’s evolving architecture.

Frequently Asked Questions:

Q: Why should I switch from legacy to symbolic macros in Bazel?
A: Symbolic macros improve code readability, offer better attribute handling, enforce naming conventions, and support future features like lazy evaluation, making them a more scalable solution.

Q: Are there restrictions on naming targets created by symbolic macros?
A: Yes, targets must match the macro’s name or start with it followed by an underscore, period, or hyphen, ensuring consistent and predictable naming.

Q: Can symbolic macros access source files directly?
A: No, they must access sources through arguments or public visibility, adhering to Bazel’s resource access rules.

Q: What are the main differences between legacy and symbolic macros?
A: Legacy macros are function-based, allow positional parameters, and inline resources, while symbolic macros are first-class, use named attributes, follow naming conventions, and comply with visibility rules.

Q: Is lazy evaluation supported in symbolic macros?
A: It is a planned feature, which, when implemented, will allow Bazel to evaluate macros only when their targets are required.