The previous sections described packages, targets and labels, and the build dependency graph abstractly. This section describes the concrete syntax used to define a package.
By definition, every package contains a BUILD file, which is a short
program. BUILD files are evaluated using an imperative language,
Starlark.
They are interpreted as a sequential list of statements.
In general, order does matter: variables must be defined before they are
used, for example. However, most BUILD files consist only of declarations of
build rules, and the relative order of these statements is immaterial; all
that matters is which rules were declared, and with what values, by the
time package evaluation completes.
When a build rule function, such as cc_library, is executed, it creates a
new target in the graph. This target can later be referred using a label.
In simple BUILD files, rule declarations can be re-ordered freely without
changing the behavior.
To encourage a clean separation between code and data, BUILD files cannot
contain function definitions, for statements or if statements (but list
comprehensions and if expressions are allowed). Functions can be declared in
.bzl files instead. Additionally, *args and **kwargs arguments are not
allowed in BUILD files; instead list all the arguments explicitly.
Crucially, programs in Starlark can't perform arbitrary I/O. This invariant
makes the interpretation of BUILD files hermetic — dependent only on a known
set of inputs, which is essential for ensuring that builds are reproducible.
For more details, see Hermeticity.
BUILD files should be written using only ASCII characters, although
technically they are interpreted using the Latin-1 character set.
Because BUILD files need to be updated whenever the dependencies of the
underlying code change, they are typically maintained by multiple people on a
team. BUILD file authors should comment liberally to document the role
of each build target, whether or not it is intended for public use, and to
document the role of the package itself.
Loading an extension
Bazel extensions are files ending in .bzl. Use the load statement to import
a symbol from an extension.
load("//foo/bar:file.bzl", "some_library")
This code loads the file foo/bar/file.bzl and adds the some_library symbol
to the environment. This can be used to load new rules, functions, or constants
(for example, a string or a list). 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 — they cannot be
in a function body.
The first argument of load is a label identifying a
.bzl file. If it's 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, therefore, you can assign different names to the
imported symbols.
load("//foo/bar:file.bzl", library_alias = "some_library")
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.
You can use load visibility to restrict
who may load a .bzl file.
Types of build rules
The majority of build rules come in families, grouped together by
language. For example, cc_binary, cc_library
and cc_test are the build rules for C++ binaries,
libraries, and tests, respectively. Other languages use the same
naming scheme, with a different prefix, such as java_* for
Java. Some of these functions are documented in the
Build Encyclopedia, but it is possible
for anyone to create new rules.
*_binaryrules build executable programs in a given language. After a build, the executable will reside in the build tool's binary output tree at the corresponding name for the rule's label, so//my:programwould appear at (for example)$(BINDIR)/my/program.In some languages, such rules also create a runfiles directory containing all the files mentioned in a
dataattribute belonging to the rule, or any rule in its transitive closure of dependencies; this set of files is gathered together in one place for ease of deployment to production.*_testrules are a specialization of a*_binaryrule, used for automated testing. Tests are simply programs that return zero on success.Like binaries, tests also have runfiles trees, and the files beneath it are the only files that a test may legitimately open at runtime. For example, a program
cc_test(name='x', data=['//foo:bar'])may open and read$TEST_SRCDIR/workspace/foo/barduring execution. (Each programming language has its own utility function for accessing the value of$TEST_SRCDIR, but they are all equivalent to using the environment variable directly.) Failure to observe the rule will cause the test to fail when it is executed on a remote testing host.*_libraryrules specify separately-compiled modules in the given programming language. Libraries can depend on other libraries, and binaries and tests can depend on libraries, with the expected separate-compilation behavior.
| Labels | Dependencies |