Legacy macros are unstructured functions called from BUILD
files that can
create targets. By the end of the
loading phase, legacy macros don't exist
anymore, and Bazel sees only the concrete set of instantiated rules.
Why you shouldn't use legacy macros (and should use Symbolic macros instead)
Where possible you should use symbolic macros.
Symbolic macros
- Prevent action at a distance
- Make it possible to hide implementation details through granular visibility
- Take typed attributes, which in turn means automatic label and select conversion.
- Are more readable
- Will soon have lazy evaluation
Usage
The typical use case for a macro is when you want to reuse a rule.
For example, genrule in a BUILD
file generates a file using //:generator
with a some_arg
argument hardcoded in the command:
genrule(
name = "file",
outs = ["file.txt"],
cmd = "$(location //:generator) some_arg > $@",
tools = ["//:generator"],
)
If you want to generate more files with different arguments, you may want to
extract this code to a macro function. To create a macro called
file_generator
, which has name
and arg
parameters, we can replace the
genrule with the following:
load("//path:generator.bzl", "file_generator")
file_generator(
name = "file",
arg = "some_arg",
)
file_generator(
name = "file-two",
arg = "some_arg_two",
)
file_generator(
name = "file-three",
arg = "some_arg_three",
)
Here, you load the file_generator
symbol from a .bzl
file located in the
//path
package. By putting macro function definitions in a separate .bzl
file, you keep your BUILD
files clean and declarative, The .bzl
file can be
loaded from any package in the workspace.
Finally, in path/generator.bzl
, write the definition of the macro to
encapsulate and parameterize the original genrule definition:
def file_generator(name, arg, visibility=None):
native.genrule(
name = name,
outs = [name + ".txt"],
cmd = "$(location //:generator) %s > $@" % arg,
tools = ["//:generator"],
visibility = visibility,
)
You can also use macros to chain rules together. This example shows chained genrules, where a genrule uses the outputs of a previous genrule as inputs:
def chained_genrules(name, visibility=None):
native.genrule(
name = name + "-one",
outs = [name + ".one"],
cmd = "$(location :tool-one) $@",
tools = [":tool-one"],
visibility = ["//visibility:private"],
)
native.genrule(
name = name + "-two",
srcs = [name + ".one"],
outs = [name + ".two"],
cmd = "$(location :tool-two) $< $@",
tools = [":tool-two"],
visibility = visibility,
)
The example only assigns a visibility value to the second genrule. This allows macro authors to hide the outputs of intermediate rules from being depended upon by other targets in the workspace.
Expanding macros
When you want to investigate what a macro does, use the query
command with
--output=build
to see the expanded form:
$ bazel query --output=build :file
# /absolute/path/test/ext.bzl:42:3
genrule(
name = "file",
tools = ["//:generator"],
outs = ["//test:file.txt"],
cmd = "$(location //:generator) some_arg > $@",
)
Instantiating native rules
Native rules (rules that don't need a load()
statement) can be instantiated
from the native module:
def my_macro(name, visibility=None):
native.cc_library(
name = name,
srcs = ["main.cc"],
visibility = visibility,
)
If you need to know the package name (for example, which BUILD
file is calling
the macro), use the function
native.package_name(). Note that
native
can only be used in .bzl
files, and not in BUILD
files.
Label resolution in macros
Since legacy macros are evaluated in the
loading phase, label strings such as
"//foo:bar"
that occur in a legacy macro are interpreted relative to the
BUILD
file in which the macro is used rather than relative to the .bzl
file
in which it is defined. This behavior is generally undesirable for macros that
are meant to be used in other repositories, such as because they are part of a
published Starlark ruleset.
To get the same behavior as for Starlark rules, wrap the label strings with the
Label
constructor:
# @my_ruleset//rules:defs.bzl
def my_cc_wrapper(name, deps = [], **kwargs):
native.cc_library(
name = name,
deps = deps + select({
# Due to the use of Label, this label is resolved within @my_ruleset,
# regardless of its site of use.
Label("//config:needs_foo"): [
# Due to the use of Label, this label will resolve to the correct target
# even if the canonical name of @dep_of_my_ruleset should be different
# in the main repo, such as due to repo mappings.
Label("@dep_of_my_ruleset//tools:foo"),
],
"//conditions:default": [],
}),
**kwargs,
)
Debugging
bazel query --output=build //my/path:all
will show you how theBUILD
file looks after evaluation. All legacy macros, globs, loops are expanded. Known limitation:select
expressions are not shown in the output.You may filter the output based on
generator_function
(which function generated the rules) orgenerator_name
(the name attribute of the macro):bash $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'
To find out where exactly the rule
foo
is generated in aBUILD
file, you can try the following trick. Insert this line near the top of theBUILD
file:cc_library(name = "foo")
. Run Bazel. You will get an exception when the rulefoo
is created (due to a name conflict), which will show you the full stack trace.You can also use print for debugging. It displays the message as a
DEBUG
log line during the loading phase. Except in rare cases, either removeprint
calls, or make them conditional under adebugging
parameter that defaults toFalse
before submitting the code to the depot.
Errors
If you want to throw an error, use the fail
function. Explain clearly to the user what went wrong and how to fix their
BUILD
file. It is not possible to catch an error.
def my_macro(name, deps, visibility=None):
if len(deps) < 2:
fail("Expected at least two values in deps")
# ...
Conventions
All public functions (functions that don't start with underscore) that instantiate rules must have a
name
argument. This argument should not be optional (don't give a default value).Public functions should use a docstring following Python conventions.
In
BUILD
files, thename
argument of the macros must be a keyword argument (not a positional argument).The
name
attribute of rules generated by a macro should include the name argument as a prefix. For example,macro(name = "foo")
can generate acc_library
foo
and a genrulefoo_gen
.In most cases, optional parameters should have a default value of
None
.None
can be passed directly to native rules, which treat it the same as if you had not passed in any argument. Thus, there is no need to replace it with0
,False
, or[]
for this purpose. Instead, the macro should defer to the rules it creates, as their defaults may be complex or may change over time. Additionally, a parameter that is explicitly set to its default value looks different than one that is never set (or set toNone
) when accessed through the query language or build-system internals.Macros should have an optional
visibility
argument.