Extension Overview

Loading an extension

Bazel extensions are files ending in .bzl. Use the load statement to import a symbol from an extension.

load("//build_tools/rules:maprule.bzl", "maprule")

This code will load the file build_tools/rules/maprule.bzl and add the maprule symbol to the environment. This can be used to load new rules, functions or constants (e.g. a string, a list, etc.). Multiple symbols can be imported by using additional arguments to the call to load. Arguments must be string literals (no variable) and load statements must appear at top-level, i.e. they cannot be in a function body.

The first argument of load is a label identifying a .bzl file. If it is a relative label, it is resolved with respect to the package (not directory) containing the current .bzl file. Relative labels in load statements should use a leading :.

load also supports aliases, i.e. you can assign different names to the imported symbols.

load("//build_tools/rules:maprule.bzl", maprule_alias = "maprule")

You can define multiple aliases within one load statement. Moreover, the argument list can contain both aliases and regular symbol names. The following example is perfectly legal (please note when to use quotation marks).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

In a .bzl file, symbols starting with _ are not exported and cannot be loaded from another file. Visibility doesn’t affect loading (yet): you don’t need to use exports_files to make a .bzl file visible.

Macros and rules

A macro is a function that instantiates rules. It is useful when a BUILD file is getting too repetitive or too complex, as it allows you to reuse some code. The function is evaluated as soon as the BUILD file is read. After the evaluation of the BUILD file, Bazel has little information about macros: if your macro generates a genrule, Bazel will behave as if you wrote the genrule. As a result, bazel query will only list the generated genrule.

A rule is more powerful than a macro. It can access Bazel internals and have full control over what is going on. It may for example pass information to other rules.

If you want to reuse simple logic, start with a macro. If a macro becomes complex, it is often a good idea to make it a rule. Support for a new language is typically done with a rule. Rules are for advanced users: we expect that most people will never have to write one, they will only load and call existing rules.

Evaluation model

A build consists of three phases.

  • Loading phase. First, we load and evaluate all extensions and all BUILD files that are needed for the build. The execution of the BUILD files simply instantiates rules (each time a rule is called, it gets added to a graph). This is where macros are evaluated.

  • Analysis phase. The code of the rules is executed (their implementation function), and actions are instantiated. An action describes how to generate a set of outputs from a set of inputs, e.g. “run gcc on hello.c and get hello.o”. It is important to note that we have to list explicitly which files will be generated before executing the actual commands. In other words, the analysis phase takes the graph generated by the loading phase and generates an action graph.

  • Execution phase. Actions are executed, when at least one of their outputs is required. If a file is missing or if a command fails to generate one output, the build fails. Tests are also run during this phase.

Bazel uses parallelism to read, parse and evaluate the .bzl files and BUILD files. A file is read at most once per build and the result of the evaluation is cached and reused. A file is evaluated only once all its dependencies (load() statements) have been resolved. By design, loading a .bzl file has no visible side-effect, it only defines values and functions.

Bazel tries to be clever: it uses dependency analysis to know which files must be loaded, which rules must be analyzed, and which actions must be executed. For example, if a rule generates actions that we don’t need for the current build, they will not be executed.