A *_binary
rule compiles an application. This might be
an executable, a .jar
file, and/or a collection of scripts.
A *_library()
rule compiles some sources into a library.
In general, a language_library
rule works like
the corresponding language_binary
rule, but
doesn't generate something executable.
A *_test
rule compiles a
test. See Common attributes for
tests for an explanation of the common attributes.
${SECTION_TEST}
This section describes how to use or define a special class of string variables that are called the "Make" environment. Bazel defines a set of standard "Make" variables, and you can also define your own.
(The reason for the term "Make" is historical: the syntax and semantics of these variables are somewhat similar to those of GNU Make, and in the original implementation, were implemented by GNU Make. The scare-quotes are present because newer build tools support "Make" variables without being implemented using GNU Make; therefore it is important to read the specification below carefully to understand the differences.)
To see the list of all common "Make" variables and their values,
run bazel info --show_make_env
.
Build rules can introduce additional rule specific variables. One example is
the cmd
attribute of a genrule.
Variables can be referenced in attributes and other variables using either
$(FOO)
or varref('FOO')
, where FOO
is
the variable name. In the attribute documentation of rules, it is mentioned
when an attribute is subject to "Make" variable substitution. For those
attributes this means that any substrings of the form $(X)
within those attributes will be interpreted as references to the "Make"
variable X, and will be replaced by the appropriate value of that
variable for the applicable build configuration. The parens may be omitted
for variables whose name is a single character.
It is an error if such attributes contain embedded strings of the
form $(X)
where X is not the name of a
"Make" variable, or unclosed references such as $(
not
matched by a corresponding )
.
Within such attributes, literal dollar signs must be escaped
as $$
to prevent this expansion.
Those attributes that are subject to this substitution are explicitly indicated as such in their definitions in this document.
Bazel defines a set of "Make" variables for you.
The build system also provides a consistent PATH for genrules and tests which need to execute shell commands. For genrules, you can indirect your commands using the Make variables below. For basic Unix utilities, prefer relying on the PATH variable to guarantee correct results. For genrules involving compiler and platform invocation, you must use the Make variable syntax. The same basic command set is also available during tests. Simply rely on the PATH.
Bazel uses a tiny Unix distribution to guarantee consistent behavior of
build and test steps which execute shell code across all build execution
hosting environments but it does not enforce a pure chroot. As such, do
not use hard coded paths, such as
/usr/bin/foo
. Binaries referenced in hardcoded paths are not
hermetic and can lead to unexpected and non-reproducible build behavior.
Command Variables for genrules
Note that in general, you should simply refer to many common utilities as bare commands that the $PATH variable will correctly resolve to hermetic versions for you.
Path Variables
BINDIR
: The base of the generated binary tree for the target
architecture. (Note that a different tree may be used for
programs that run during the build on the host architecture,
to support cross-compiling. If you want to run a tool from
within a genrule, the recommended way of specifying the path to
the tool is to use $(location toolname)
,
where toolname must be listed in the tools
attribute for the genrule.GENDIR
: The base of the generated code
tree for the target architecture.JAVABASE
:
The base directory containing the Java utilities.
It will have a "bin" subdirectory.Architecture Variables
ABI
: The C++ ABI version. ANDROID_CPU
: The Android target architecture's cpu. JAVA_CPU
: The Java target architecture's cpu. TARGET_CPU
: The target architecture's cpu. Other Variables available to the cmd attribute of a genrule
OUTS
: The outs
list. If you have only one output
file, you can also use $@
.SRCS
: The srcs
list (or more
precisely, the pathnames of the files corresponding to
labels in the srcs
list). If you have only one
source file, you can also use $<
.<
: srcs
, if it is a single file.@
: outs
, if it is a single file.@D
: The output directory. If there is only
one filename in outs
, this expands to the
directory containing that file. If there are multiple
filenames, this variable instead expands to the package's root
directory in the genfiles
tree, even if all
the generated files belong to the same subdirectory!
If the genrule needs to generate temporary intermediate files
(perhaps as a result of using some other tool like a compiler)
then it should attempt to write the temporary files to
@D
(although /tmp
will also be
writable), and to remove any such generated temporary files.
Especially, avoid writing to directories containing inputs -
they may be on read-only filesystems. You may want to use Python-style variable assignments rather than "Make" variables, because they work in more use cases and are less surprising. "Make" variables will work in the cmd attribute of genrules and in the key of the abi_deps attribute of a limited number of rules, but only in very few other places.
To define your "Make" own variables, first call vardef() to define your variable, then call varref(name) to retrieve it. varref can be embedded as part of a larger string. Custom "Make" variables differ from ordinary "Python" variables in the BUILD language in two important ways:
$(FOO)
.
varref defers evaluation until after BUILD file evaluation.vardef(name, value, platform)
Define a variable for use within this BUILD
file only.
This variable can then be used by varref().
The value of the variable can be overridden on the command line by using the
--define
flag.
Arguments
name
: The name of the variable.
(String; required)value
: The value to assign to this variable.
(String; required)platform
: Conditionally define this variable for a given
platform.
(String; optional)vardef
binds the name
to value
if we're
compiling for platform
.
Notes
Because references to "Make" variables are expanded after
BUILD file evaluation, the relative order of vardef
statements and rule declarations is unimportant; it is order of
vardef
statements relative to each other, and hence the
state of the "Make" environment at the end of evaluation that
matters.
If there are multiple matching vardef
definitions for
the same variable, the definition that wins is
the last matching definition
that specifies a platform, unless there are no matching
definitions that specify a platform, in which case the definition
that wins is the last definition without
a platform.
varref(name)
varref("FOO")
is equivalent of writing "$(FOO)". It is used to
dereference variables defined with vardef
as well as predefined variables.
In rule attributes that are subject to "Make" variable
substitution, the string produced by varref(name)
will expand to the value of variable name.
varref(name)
may not be used in rule attributes that are
not subject to "Make" variable substitution.
Arguments
name
: The name of the variable to dereference.
Notes
varref
can access either local or global variables.
It prefers the local variable, if both a local and a global exist with
the same name.
Examples
See vardef() examples.