Google Git
Sign in
bazel / bazel / 5fe3129b20c5a020bee512f74b3f4054a5a4cda9 / . / docs / historical / bazel-user-manual.html
blob: ef183a4529617d6a30d49979ab3920389148751c [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>A User's Guide to Bazel</title>
<style type="text/css" id="internalStyle">
body {
background-color: #ffffff;
color: black;
margin-right: 10%;
margin-left: 10%;
}
h1, h2, h3, h4, h5, h6 {
color: #dd7755;
font-family: sans-serif;
}
@media print {
/* Darker version for printing */
h1, h2, h3, h4, h5, h6 {
color: #008000;
font-family: helvetica, sans-serif;
}
}
h1 {
text-align: center;
}
h2 {
margin-left: -0.5in;
}
h3 {
margin-left: -0.25in;
}
h4 {
margin-left: -0.125in;
}
hr {
margin-left: -1in;
}
address {
text-align: right;
}
/* A compact unordered list */
ul.tight > li {
margin-bottom: 0;
}
/* Use the <code> tag for bits of code and <var> for variable and object names. */
code,pre,samp,var {
color: #006000;
}
/* Use the <file> tag for file and directory paths and names. */
file {
color: #905050;
font-family: monospace;
}
/* Use the <kbd> tag for stuff the user should type. */
kbd {
color: #600000;
}
div.note p {
float: right;
width: 3in;
margin-right: 0%;
padding: 1px;
border: 2px solid #60a060;
background-color: #fffff0;
}
table.grid {
background-color: #ffffee;
border: 1px solid black;
border-collapse: collapse;
margin-left: 2mm;
margin-right: 2mm;
}
table.grid th,
table.grid td {
border: 1px solid black;
padding: 0 2mm 0 2mm;
}
/* Use pre.code for code listings.
Use pre.interaction for "Here's what you see when you run a.out.".
(Within pre.interaction, use <kbd> things the user types)
*/
pre.code {
background-color: #FFFFEE;
border: 1px solid black;
color: #004000;
font-size: 10pt;
margin-left: 2mm;
margin-right: 2mm;
padding: 2mm;
-moz-border-radius: 12px 0px 0px 0px;
}
pre.interaction {
background-color: #EEFFEE;
color: #004000;
padding: 2mm;
}
pre.interaction kbd {
font-weight: bold;
color: #000000;
}
/* legacy style */
pre.interaction b.astyped {
color: #000000;
}
h1 { margin-bottom: 5px; }
ul li { margin-bottom: 1em; }
ul.toc li { margin-bottom: 0em; }
em.harmful { color: red; }
div#release { text-align: center; font-size: 14pt; font-weight: bold; font-family: courier; }
.deprecated { text-decoration: line-through; }
.discouraged { text-decoration: line-through; }
table.truthtable {
border-collapse: collapse;
font-family: monospace;
}
table.truthtable th, table.truthtable td {
border: 1px solid black;
padding: 0.5em;
text-align: center;
}
table.truthtable th {
font-weight: bold;
}
table.truthtable td.rowhead {
text-align: right;
font-weight: bold;
}
table.layout { width: 980px; }
table.layout td { vertical-align: top; }
#maintainer { text-align: right; }
</style>
</head>
<body>
<h1>A User's Guide to Bazel</h1>
<h2>Related Documentation</h2>
<ul class="toc">
<li><a href="write_build_file.html">Getting Started with BUILD files</a></li>
<li><a href="build-ref.html">BUILD Concept Reference</a></li>
<li><a href="build-encyclopedia.html">Build Encyclopedia</a></li>
<li><a href="bazel-query-v2.html">Bazel Query Reference</a></li>
</ul>
<h2>Contents</h2>
<div id="nav" class="nav-2-levels"></div>
<h2 id='introduction'>Introduction</h2>
<h3>What is Bazel?</h3>
<p>
Bazel is a build system that
emphasizes <i>correctness</i> and <i>reproducibility</i> of the
build, <i>speed</i> of clean and incremental builds,
and <i>integration</i> of the toolchain with IDEs and analysis
tools. It is both a specification for code organization and a language for
expressing software dependencies and the steps involved in a build.
</p>
<h3>Background reading</h3>
<p>
Various aspects of the Bazel build system are described in other
documents.
The <a href="build-ref.html">BUILD Concept Reference</a> introduces
the primary concepts of the Bazel build system; this is a place to
start if you are new to Bazel.
The <a
href="build-encyclopedia.html">Bazel
BUILD Encyclopedia of Functions</a> describes all the functions of
the Bazel build language, including the syntax and semantics of
the current build rules.
<a href="write_build_file.html">Getting Started
with BUILD files</a> is a tutorial on how to write BUILD files.
</p>
<h2 id='concepts'>Bazel concepts</h2>
<p>
Running the <code>bazel</code> tool is easy. Simply go to your
workspace root and type <code>bazel</code>.
(Bazel may also be invoked from the subdirectories of your
workspace.)
</p>
<pre>
% bazel help
Usage: bazel &lt;command&gt; &lt;options&gt; ...
Available commands:
<a href='#analyze-profile'>analyze-profile</a> Analyzes build profile data.
<a href='#build'>build</a> Builds the specified targets.
<a href='#canonicalize'>canonicalize-flags</a> Canonicalize Bazel flags.
<a href='#clean'>clean</a> Removes output files and optionally stops the server.
<a href='#help'>help</a> Prints help for commands, or the index.
<a href='#info'>info</a> Displays runtime info about the Bazel server.
<a href='#query'>query</a> Executes a dependency graph query.
<a href='#run'>run</a> Runs the specified target.
<a href='#shutdown'>shutdown</a> Stops the Bazel server.
<a href='#test'>test</a> Builds and runs the specified test targets.
<a href='#version'>version</a> Prints version information for Bazel.
Getting more help:
bazel help &lt;command&gt;
Prints help and options for &lt;command&gt;.
bazel help <a href='#startup_options'>startup_options</a>
Options for the JVM hosting Bazel.
bazel help <a href='#target-patterns'>target-syntax</a>
Explains the syntax for specifying targets.
bazel help info-keys
Displays a list of keys used by the info command.
</pre>
<p>
The <code>bazel</code> tool performs many functions, called
commands; users of Perforce, CVS and Subversion will be familiar
with this "Swiss army knife" arrangement. The most commonly used one is of
course <code>bazel build</code>. You can browse the online help
messages using <code>bazel help</code>. The links in the message
above refer to the relevant section of this document.
</p>
<h3 id='client/server'>Client/server implementation</h3>
<p>
The Bazel system is implemented as a long-lived server process.
This allows it to perform many optimizations not possible with a
batch-oriented implementation, such as caching of BUILD files,
dependency graphs, and other metadata from one build to the
next. This improves the speed of incremental builds, and allows
different commands, such as <code>build</code>
and <code>query</code> to share the same cache of loaded packages,
making queries very fast.
</p>
<p>
When you run <code>bazel</code>, you're running the client. The
client finds the server based on the path of the workspace directory
and your userid, so if you build in multiple workspaces, you'll have
multiple Bazel server processes. Multiple users on the same
workstation can build concurrently in the same workspace. If the
client cannot find a running server instance, it starts a new one.
The server process will stop after a period of inactivity (3 hours,
by default).
</p>
<p>
For the most part, the fact that there is a server running is
invisible to the user, but sometimes it helps to bear this in mind.
For example, if you're running scripts that perform a lot of
automated builds in different directories, it's important to ensure
that you don't accumulate a lot of idle servers; you can do this by
explicitly shutting them down when you're finished with them, or by
specifying a short timeout period.
</p>
<p>
The name of a Bazel server process appears in the output of <code>ps
x</code> or <code>ps -e f</code> as
<code>bazel(<i>dirname</i>)</code>, where <i>dirname</i> is the
basename of the directory enclosing the root of the Bazel
<a href="#setup_workspace">workspace</a>. For example:
</p>
<pre>
% ps -e f
16143 ? Sl 3:00 bazel(src-jrluser2) -server -Djava.library.path=...
</pre>
<p>
This makes it easier to find out which server process belongs to a
given workspace. (Beware that with certain other options
to <code>ps</code>, Bazel server processes may be named just
<code>java</code>.) Bazel servers can be stopped using
the <a href='#shutdown'>shutdown</a> command.
</p>
<p>
In some cases, such as in continuous builds, it may be desirable to disable
client/server mode and instead run Bazel as a batch application.
See the <code class='flag'>--batch</code> switch <a href="#batch">below</a>.
</p>
<h3 id='bazelrc'><code>.bazelrc</code>, the Bazel configuration file,
the <code class='flag'>--bazelrc=<var>file</var></code> option, and the
<code class='flag'>--config=<var>value</var></code> option</h3>
<p>
Bazel accepts many options. Typically, some of these are varied
frequently (e.g. <code class='flag'>--subcommands</code>) while others stay the
same across several builds (e.g. <code class='flag'>--package_path</code>).
To avoid having to specify these constant options every time you do
a build or run some other Bazel command, Bazel allows you to
specify options in a configuration file.
</p>
<p>
Bazel looks for an optional configuration file in the location
specified by the <code class='flag'>--bazelrc=<var>file</var></code> option. If
this option is not specified then, by default, Bazel looks for the
file called <code>.bazelrc</code> in one of two directories: first,
in the workspace root directory, then in your home directory. If
it finds a file in the first (workspace-specific) location, it will
not look at the second (global) location.
</p>
<p>
The <code class='flag'>--bazelrc=<var>file</var></code> option must
appear <em>before</em> the command name (e.g. <code>build</code>),
and must use the <code>=</code> syntax&mdash;a space is not allowed.
</p>
<p>
The option <code class='flag'>--bazelrc=/dev/null</code> effectively disables the
use of a configuration file. We strongly recommend that you use
this option when performing release builds, or automated tests that
invoke Bazel.
</p>
<p>
Aside from the configuration file described above, Bazel also looks
for a master configuration file next to the binary. The name of this
file is the same as the name of the binary with the
string <code>.bazelrc</code> attached. This file is not intended to
be user-modifiable; its purpose is for the Bazel team to be able to
turn experimental features on or off immediately without releasing a
new Bazel version, should an urgent need arise. Reading of this file
can be disabled using the <code class='flag'>--nomaster_bazelrc</code> option.
</p>
<p>
Like all UNIX "rc" files, the <code>.bazelrc</code> file is a text
file with a line-based grammar. Lines starting <code>#</code> are
considered comments and are ignored, as are blank lines. Each line
contains a sequence of words, which are tokenized according to the
same rules as the Bourne shell.
The first word on each line is the name of a Bazel command, such
as <code>build</code> or <code>query</code>. The remaining words
are the default options that apply to that command.
More than one line may be used for a command; the options are combined
as if they had appeared on a single line.
(Users of CVS, another tool with a "Swiss army knife" command-line
interface, will find the syntax familiar to that of <code>.cvsrc</code>.)
</p>
<p>
Startup options may be specified in the
<code>.bazelrc</code> file using the command <code>startup</code>.
These options are described in the interactive help
at <code>bazel help startup_options</code>.
Options specified in the command line always take precedence over
those from a configuration file, and options in the user-specific
configuration file always take precedence over the master one.
Options may include words other than flags, such as the names of
build targets, etc; these are always prepended to the explicit
argument list provided on the command-line, if any.
</p>
<p>
Common command options may be specified in the
<code>.bazelrc</code> file using the command <code>common</code>.
</p>
<p>
In addition, commands may have <code>:name</code> suffixes. These
options are ignored by default, but can be pulled in through the
<code>--config=<var>name</var></code> option, either on the command line or in
a <code>.bazelrc</code> file. The intention is that these bundle command line
options that are commonly used together, for example
<code>--config=releasemode</code>.
</p>
<p>
The command named <code>import</code> is special: if Bazel encounters such
a line in a <code>.bazelrc</code> file, it parses the contents of the file
referenced by the import statement, too. Options specified in an imported file
take precedence over ones specified before the import statement, options
specified after the import statement take precedence over the ones in the
imported file, and options in files imported later take precedence over files
imported earlier.
</p>
<p>
Here's an example <code>~/.bazelrc</code> file:
</p>
<pre>
# Bob's Bazel option defaults
startup --batch --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --package_path %workspace%:/home/bob/stuff/bazel --keep_going --jobs 600
build --color=yes
query --keep_going
build:releasemode --define buildtype="Release" --test_timeout=3600
</pre>
<h2 id='build'>Building programs with Bazel</h2>
<p>
The most important function of Bazel is, of course, building code. Type
<code>bazel build</code> followed by the name of the
<a href="#target-patterns">target</a> you wish to build. Here's a typical
session:
</p>
<pre>
% bazel build //foo
Welcome to Bazel
____Loading package: foo
____Loading package: bar
____Loading package: baz
____Loading complete. Analyzing...
____Building 1 target...
____[0%] Executing Genrule //bar:helper_rule
____[10%] Executing Genrule //baz:another_helper_rule
____[95%] Building foo/foo.jar
Target //foo:foo up-to-date:
bazel-bin/foo/foo.jar
bazel-bin/foo/foo
____Elapsed time: 9.905s
</pre>
<p>
Bazel prints a welcome message, followed by progress messages as it loads all the
packages in the transitive closure of dependencies of the requested
target and analyzes them for correctness, then executes the
compilers and other tools of the build.
</p>
<p>
Bazel prints progress messages during
the <a href='#phases'>execution phase</a> of the build, showing the
current build step that is being started,
and approximately what fraction of the build is complete. If the
estimate of the total workload includes steps that are already
up-to-date, progress will advance rapidly when this is discovered.
Since progress is reported when steps are started, rather than
completed, the reported progress will never reach 100%, and, if
multiple steps are started with no intervening completions, the
reported progress will not change.
</p>
<p>
At the end of the build Bazel
prints which targets were requested, whether or not they were
successfully built, and if so, where the output files can be found.
Scripts that run builds can reliably parse this output; see <a
href='#flag--show_result'><code class='flag'>--show_result</code></a> for more
details.
</p>
<p>
Typing the same command again:
</p>
<pre>
% bazel build //foo
Welcome to Bazel
____Loading complete. Analyzing...
____Building 1 target...
Target //foo:foo up-to-date:
bazel-bin/foo/foo.jar
bazel-bin/base/foo
____Elapsed time: 0.280s
</pre>
<p>
we see an incremental build: in this case, there are no packages to
re-load, since nothing has changed, and no build steps to execute.
In most cases, this results in dramatically faster output time.
</p>
<h3 id='setup_workspace'>Setting up a Bazel workspace</h3>
<p>
Before you can start a build, you will need a Bazel workspace. This is
simply a directory tree that contains all the source files needed to build
your application.
Bazel allows you to perform a build from a completely read-only volume.
</p>
<h4 id='flag--package_path'>Setting up a <code class='flag'>--package_path</code></h4>
<p>
Bazel finds its packages by searching the package path. This is a colon
separated ordered list of bazel directories, each being the root of a
partial source tree.
</p>
<p>
<i>To specify a custom package path</i> using the
<code class='flag'>--package_path</code> option:
</p>
<pre>
% bazel build --package_path %workspace%:/some/other/root
</pre>
<p>
Package path elements may be specified in three formats:
</p>
<ol>
<li>
If the first character is <code>/</code>, the path is absolute.
</li>
<li>
If the path starts with <code>%workspace%</code>, the path is taken relative
to the nearest enclosing bazel directory.<br>
For instance, if your working directory
is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the
string <code>%workspace%</code> in the package-path is expanded
to <code>/home/bob/clients/bob_client/bazel</code>.
</li>
<li>
Anything else is taken relative to the working directory.<br> This is usually not what you mean to do,
and may behave unexpectedly if you use Bazel from directories below the bazel workspace.
For instance, if you use the package-path element <code>.</code>,
and then cd into the directory
<code>/home/bob/clients/bob_client/bazel/foo</code>, packages
will be resolved from the
<code>/home/bob/clients/bob_client/bazel/foo</code> directory.
</li>
</ol>
<p>
If you use a non-default package path, we recommend that you specify
it in your <a href='#bazelrc'>Bazel configuration file</a> for
convenience.
</p>
<p>
<i>Bazel doesn't require any packages to be in the
current directory</i>, so you can do a build from an empty bazel
workspace if all the necessary packages can be found somewhere else
on the package path.
</p>
<p>
<i>Example</i>: Building from an empty client
</p>
<pre>
% mkdir -p foo/bazel
% cd foo/bazel
% bazel build --package_path /some/other/path //foo
</pre>
<h3 id='target-patterns'>Specifying targets to build</h3>
<p>
Bazel allows a number of ways to specify the targets to be built.
Collectively, these are known as <i>target patterns</i>.
The on-line help displays a summary of supported patterns:
</p>
<pre>
% bazel help target-syntax
Target pattern syntax
=====================
The Bazel label syntax (as used in BUILD files) is used to specify a
single target. Bazel target patterns generalize this syntax to sets
of targets, and also support working directory-relative forms, recursion,
subtraction and filtering. Examples:
Specifying a single target:
//foo/bar:wiz The single target '//foo/bar:wiz'.
foo/bar/wiz Equivalent to the first existing one of these:
//foo/bar:wiz
//foo:bar/wiz
//foo/bar Equivalent to '//foo/bar:bar'.
Specifying all rules in a package:
//foo/bar:all Matches all rules in package 'foo/bar'.
Specifying all rules recursively beneath a package:
//foo/...:all Matches all rules in all packages beneath directory 'foo'.
//foo/... (ditto)
Working-directory relative forms: (assume cwd = 'bazel/foo')
Target patterns which do not begin with '//' are taken relative to
the working directory. Patterns which begin with '//' are always
absolute.
...:all Equivalent to '//foo/...:all'.
... (ditto)
bar/...:all Equivalent to '//foo/bar/...:all'.
bar/... (ditto)
bar:wiz Equivalent to '//foo/bar:wiz'.
:foo Equivalent to '//foo:foo'.
bar:all Equivalent to '//foo/bar:all'.
:all Equivalent to '//foo:all'.
Note: The "..." (recursive) syntax does not follow directory symlinks.
Summary of target wildcards:
:all, Match all rules in the specified packages.
:*, :all-targets Match all targets (rules and files) in the specified
packages, including .par and _deploy.jar files.
Subtractive patterns:
Target patterns may be preceded by '-', meaning they should be
subtracted from the set of targets accumulated by preceding
patterns. For example:
% bazel build -- bigtable/... -bigtable/contrib/...
builds everything in 'bigtable', except 'contrib'. As usual, the
'--' is required to prevent '-b' from being interpreted as an
option.
</pre>
<p>
Whereas Bazel <a href="build-ref.html#label">labels</a> are used
to specify individual targets, e.g. for declaring dependencies in
BUILD files, Bazel's target patterns are a syntax for specifying
multiple targets: they are a generalization of the label syntax
for <i>sets</i> of targets, using wildcards. In the simplest case,
any valid label is also a valid target pattern, identifying a set of
exactly one target.
</p>
<p>
<code>foo/...</code> is a wildcard over <em>packages</em>,
indicating all packages recursively beneath
directory <code>foo</code> (for all roots of the package
path). <code>:all</code> (or <code>:all-rules</code>) is a wildcard
over <em>targets</em>, matching all rules within a package. These two may be
combined, as in <code>foo/...:all</code>, and when both wildcards
are used, this may be abbreviated to <code>foo/...</code>.
</p>
<p>
In addition, <code>:*</code> (or <code>:all-targets</code>) is a
wildcard that matches <em>every target</em> in the matched packages,
including files that aren't normally built by any rule, such
as <code>_deploy.jar</code> files associated
with <code>java_binary</code> rules and <code>.par</code> files
associated with <code>py_binary</code> rules.
This implies that <code>:*</code> denotes a <em>superset</em>
of <code>:all</code>; while potentially confusing, this syntax does
allow the familiar <code>:all</code> wildcard to be used for
typical builds, in which the building of <code>_deploy.jar</code>
and <code>.par</code> targets is not desired.
</p>
<p>
In addition, Bazel allows a slash to be used instead of the colon
required by the label syntax; this is often convenient when using
Bash filename expansion. For example, <code>foo/bar/wiz</code> is
equivalent to <code>//foo/bar:wiz</code> (if there is a
package <code>foo/bar</code>) or to <code>//foo:bar/wiz</code> (if
there is a package <code>foo</code>).
</p>
<p>
Many Bazel commands accept a list of target patterns as arguments,
and they all honor the prefix negation operator `<code>-</code>'.
This can be used to subtract a set of targets from the set specified
by the preceding arguments. For example,
</p>
<pre>
bazel build foo/... bar/...
</pre>
<p>
means "build all
targets beneath <code>foo</code> <i>and</i> all targets
beneath <code>bar</code>", whereas
</p>
<pre>
bazel build -- foo/... -foo/baz/...
</pre>
<p>
means "build all targets beneath <code>foo</code> <i>except</i>
those beneath <code>foo/baz</code>".
(The <code>--</code> argument is required to prevent the subsequent
arguments starting with <code>-</code> from being interpreted as
additional options.)
</p>
<p>
Targets with <code>obsolete=1</code> or <code>tags=["manual"]</code> will
be ignored by all command line wildcards (..., :*, :all, etc). The only
way to run such targets is to specify them explicitly on the command line.
</p>
<h4>Bash completion of Bazel commands</h4>
<p>
If you use Bash, and source /etc/bash_completion,
Bash's command-completion is augmented to understand Bazel's
options, command set, and target syntax. For example,
hitting <code>TAB</code> after typing a package name followed by a
colon will expand the names of rules defined in that package:
</p>
<pre>
% source /etc/bash_completion
% bazel build bar:&lt;TAB&gt;
aardvark
alpha
chestnut
walnut
...
% bazel build bar:a&lt;TAB&gt;
aardvark
alpha
% bazel build bar:al&lt;TAB&gt;
% bazel build bar:alpha
</pre>
<p>
Similarly, hitting <code>TAB</code> after <code>bazel
test <var>package</var>:</code> will expand the names of just
the <em>test</em> rules in that package.
</p>
<p>
The completion script will additionally attempt to
expand <code>--key=value</code> options too.
</p>
<h3 id='correctness'>Correct incremental rebuilds</h3>
<p>
One of the primary goals of the Bazel project is to ensure correct
incremental rebuilds. Previous build tools, especially those based
on Make, make several unsound assumptions in their implementation of
incremental builds.
</p>
<p>
Firstly, that timestamps of files increase monotonically. While
this is the typical case, it is very easy to fall afoul of this
assumption; syncing to an earlier revision of a file causes that file's
modification time to decrease; Make-based systems will not rebuild.
A similar situation may arise when switching to a source-control view of an
earlier milestone.
</p>
<p>
More generally, while Make detects changes to files, it does
not detect changes to commands. If you alter the options passed to
the compiler in a given build step, Make will not re-run the
compiler, and it is necessary to manually discard the invalid
outputs of the previous build using <code>make clean</code>.
</p>
<p>
Also, Make is not robust against the unsuccessful termination of one
of its subprocesses after that subprocess has started writing to
its output file. While the current execution of Make will fail, the
subsequent invocation of Make will blindly assume that the truncated
output file is valid (because it is newer than its inputs), and it
will not be rebuilt. Similarly, if the Make process is killed, a
similar situation can occur.
</p>
<p>
Bazel avoids these assumptions, and others. Bazel maintains a database
of all work previously done, and will only omit a build step if it
finds that the set of input files (and their timestamps) to that
build step, and the compilation command for that build step, exactly
match one in the database, and, that the set of output files (and
their timestamps) for the database entry exactly match the
timestamps of the files on disk. Any change to the input files or
output files, or to the command itself, will cause re-execution of
the build step.
</p>
<p>
The benefit to users of correct incremental builds is: less time
wasted due to confusion. (Also, less time spent waiting for
rebuilds caused by use of <code>make clean</code>, whether necessary
or pre-emptive.)
</p>
<h4>Build consistency and incremental builds</h4>
<p>
Formally, we define the state of a build as <i>consistent</i> when
all the expected output files exist, and their contents are correct,
as specified by the steps or rules required to create them. When
you edit a source file, the state of the build is said to
be <i>inconsistent</i>, and remains inconsistent until you next run
the build tool to successful completion. We describe this situation
as <i>unstable inconsistency</i>, because it is only temporary, and
consistency is restored by running the build tool.
</p>
<p>
There is another kind of inconsistency that is pernicious: <i>stable
inconsistency</i>. If the build reaches a stable inconsistent
state, then repeated successful invocation of the build tool does
not restore consistency: the build has gotten "stuck", and the
outputs remain incorrect. Stable inconsistent states are the main
reason why users of Make (and other build tools) type <code>make
clean</code>. Discovering that the build tool has failed in this
manner (and then recovering from it) can be time consuming and very
frustrating.
</p>
<p>
Conceptually, the simplest way to achieve a consistent build is to
throw away all the previous build outputs and start again: make
every build a clean build. This approach is obviously too
time-consuming to be practical (except perhaps for release
engineers), and therefore to be useful, the build tool must be able
to perform incremental builds without compromising consistency.
</p>
<p>
Correct incremental dependency analysis is hard, and as described
above, many other build tools do a poor job of avoiding stable
inconsistent states during incremental builds. In contrast, Bazel
offers the following guarantee: after a successful invocation of the
build tool during which you made no edits, the build will be in a
consistent state. (If you edit your source files during a build,
Bazel makes no guarantee about the consistency of the result of the
current build. But it does guarantee that the results of
the <i>next</i> build will restore consistency.)
</p>
<p>
As with all guarantees, there comes some fine print: there are some
known ways of getting into a stable inconsistent state with Bazel.
We won't guarantee to investigate such problems arising from deliberate
attempts to find bugs in the incremental dependency analysis, but we
will investigate and do our best to fix all stable inconsistent
states arising from normal or "reasonable" use of the build tool.
</p>
<h3>Deleting the outputs of a build</h3>
<h4 id='clean'><code>bazel clean</code></h4>
<p>
Bazel has a <code>clean</code> command, analogous to that of Make.
It deletes the output directories for all build configurations performed
by this Bazel instance, or the entire working tree created by this
Bazel instance, and resets internal caches. If executed without any
command-line options, then the output directory for all configurations
will be cleaned.
</p>
<p>
To completely remove the entire working tree created by a Bazel
instance, you can specify the <code class='flag'>--expunge</code> option. When
executed with <code class='flag'>--expunge</code>, the clean command simply
removes the entire output base tree which, in addition to the build
output, contains all temp files created by Bazel. It also
stops the Bazel server after the clean, equivalent to the <a
href='#shutdown'><code>shutdown</code></a> command. For example, to
clean up all disk and memory traces of a Bazel instance, you could
specify:
</p>
<pre>
% bazel clean --expunge
</pre>
<p>
Alternatively, you can expunge in the background by using
<code class='flag'>--expunge_async</code>. It is safe to invoke a Bazel command
in the same client while the asynchronous expunge continues to run.
Note, however, that this may introduce IO contention.
</p>
<p>
The <code>clean</code> command is provided primarily as a means of
reclaiming disk space for workspaces that are no longer needed.
However, we recognize that Bazel's incremental rebuilds are not
perfect;
<code>clean</code> may be used to recover a consistent
state when problems arise.
</p>
<p>
Bazel's design is such that these problems are fixable; we consider
such bugs a high priority, and will do our best fix them.
We encourage developers to get out of the habit of
using <code>clean</code> and into that of reporting bugs in the
tools.
</p>
<h3 id='phases'>Phases of a build</h3>
<p>
In Bazel, a build occurs in three distinct phases; as a user,
understanding the difference between them provides insight into the
options which control a build (see below).
</p>
<h4 id='loading-phase'>Loading phase</h4>
<p>
The first is <b>loading</b> during which all the necessary BUILD
files for the initial targets, and their transitive closure of
dependencies, are loaded, parsed, evaluated and cached.
</p>
<p>
For the first build after a Bazel server is started, the loading
phase can take many seconds if many BUILD files are loaded
from high-latency / remotely hosted filesystems. In subsequent builds,
especially if no BUILD files have changed, loading occurs very
quickly.
</p>
<p>
Errors reported during this phase include: package not found, target
not found, lexical and grammatical errors in a BUILD file,
and evaluation errors.
</p>
<h4 id='analysis-phase'>Analysis phase</h4>
<p>
The second phase, <b>analysis</b>, involves the semantic analysis
and validation of each build rule, the construction of a build
dependency graph, and the determination of exactly what work is to
be done in each step of the build.
</p>
<p>
Like loading, analysis also takes several seconds when computed in
its entirety. However, Bazel can cache the dependency graph from
one build to the next, as an optimization;
see <a href='#flag--cache_analysis'><code class='flag'>--cache_analysis</code></a>).
This option makes this step extremely fast in the case where the
packages haven't changed since the previous build.
</p>
<p>
Errors reported at this stage include: inappropriate dependencies,
invalid inputs to a rule, and all rule-specific error messages.
</p>
<p>
The loading and analysis phases are generally very vast; this is partly because
Bazel avoids unnecessary file I/O at this stage, reading only BUILD
files in order to determine the work to be done. This is by design,
and makes Bazel a good foundation for analysis tools, such as
Bazel's <a href='#query'>query</a> command, which is implemented
atop the loading phase.
</p>
<h4 id='execution-phase'>Execution phase</h4>
<p>
The third and final phase of the build is <b>execution</b>. This
phase ensures that the outputs of each step in the build are
consistent with its inputs, re-running external compilation tools as
necessary. This step is where the build spends the majority of
its time, ranging from a few seconds to over an hour for a large
build. Errors reported during this phase include: missing source
files, errors in an external compilation tool, or failure of a tool to
produce the expected set of outputs.
</p>
<h2>Options</h2>
<p>
The following sections describe the options available during a
build. When <code class='flag'>--long</code> is used on a help command, the on-line
help messages provide summary information about the meaning, type and
default value for each option.
</p>
<p>
Most options can only be specified once. When specified multiple times, the
last instance wins. Options that can be specified multiple times are
identified in the on-line help with the text 'may be used multiple times'.
</p>
<h3>Options that affect how packages are located</h3>
<p>
See also the <a href='#flag--show_package_location'><code class='flag'>--show_package_location</code></a>
option.
</p>
<h4><code class='flag'>--package_path</code></h4>
<p>
This option specifies the set of directories that are searched to
find the BUILD file for a given package; see
<a href='#flag--package_path'>Setting up a Bazel workspace</a> above
for a complete explanation.
</p>
<h4 id='flag--deleted_packages'><code class='flag'>--deleted_packages</code></h4>
<p>
This option specifies a comma-separated list of packages which Bazel
should consider deleted, and not attempt to load from any directory
on the package path.
</p>
<p>
if you use a workspace layout that maps the entire source tree into some readonly path while
mapping writable subsections into another path, you may need to use this option to solve
the following problem: when you have a pending deletion of a package in your
Bazel workspace, but there is still a BUILD file for this package somewhere
on your package path, Bazel will consider the package existent unless this
option tells it not to.
</p>
<p>
Consider the following scenario: you have two
packages, <code>x</code> and <code>x/y</code> (a subpackage). When
you populate your client, both packages exist beneath both
package-path roots:
</p>
<pre>
~/src/$WORKSPACE_WRITABLE_ROOT/
/x/BUILD
/x/y/BUILD &lt;-- about to delete this
/x/y/foo.txt
~/src/$WORKSPACE_READONLY_ROOT/
/x/BUILD
/x/y/BUILD
/x/y/foo.txt
</pre>
<p>
Now you delete <code>~/src/$WORKSPACE_WRITABLE_ROOT/x/y/BUILD</code>, intending to
merge the contents of package <code>x/y</code> into <code>x</code>,
and now when x's BUILD file refers to the
file <code>x/y/foo.txt</code>, it uses the
label <code>//x:y/txt</code>.
</p>
<p>
However, x/y may have been deleted in the read/write workspace, but the
package still exists elsewhere on the package-path. In this situation, Bazel
will issue an error, saying that <code>//x:y/txt</code> is an invalid label
because package <code>x/y</code> still exists (beneath <code>$WORKSPACE_READONLY_ROOT</code>).
The solution is to specify <code class='flag'>--deleted_packages x/y</code>.
</p>
<h3 id='checking-options'>Error checking options</h3>
<p>
These options control Bazel's error-checking and/or warnings.
</p>
<h4><code class='flag'>--check_constraint <var>constraint</var></code></h4>
<p>
This option takes an argument that specifies which constraint
should be checked.
</p>
<p>
Bazel performs special checks on each rule that is annotated with the
given constraint.
</p>
<p>
The supported constraints and their checks are as follows:
</p>
<ul>
<li><code>public</code>: Verify that all java_libraries marked with
<code>constraints = ['public']</code> only depend on java_libraries
that are marked as <code>constraints = ['public']</code> too. If Bazel
finds a dependency that does not conform to this rule, Bazel will issue
an error.
</li>
</ul>
<h4 id='flag--check_licenses'><code class='flag'>--[no]check_licenses</code></h4>
<p>
This option causes Bazel to analyze the <code>licenses</code> and
<code>distribs</code> clauses in BUILD files to identify uses of third
party code that are incompatible with how a product is going to be
distributed.
</p>
<pre>
% bazel build --check_licenses //foo:bar
</pre>
<p>
will check the licensing of all packages used by "//foo:bar", to
ensure that they are compatible with how bar is distributed. If the
licensing check finds no errors, then bar will be built.
</p>
<h4 id='flag--check_visibility'><code class='flag'>--[no]check_visibility</code></h4>
<p>
If this option is set to false, visibility checks are demoted to warnings.
The default value of this option is true, so that by default, visibility
checking is done.
</p>
<h4 id='flag--output_filter'><code class='flag'>--output_filter <var>regex</var></code></h4>
<p>
The <code class='flag'>--output_filter</code> option will only show build and compilation
warnings for targets that match the regular expression. If a target does not
match the given regular expression and its execution succeeds, its standard
output and standard error are thrown away. This option is intended to be used
to help focus efforts on fixing warnings in packages under development. Here
are some typical values for this option:
</p>
<table>
<tr>
<td><code class='flag'>--output_filter=</code></td>
<td>Show all output.</td>
</tr>
<tr>
<td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td>
<td>Show the output for the specified packages.</td>
</tr>
<tr>
<td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td>
<td>Don't show output.</td>
</tr>
</table>
<p>
If this option is not given, a default filter will be created according to the
<a href="#flag--auto_output_filter"><code class='flag'>--auto_output_filter</code> option</a>.
</p>
<h4 id='flag--auto_output_filter'><code class='flag'>--auto_output_filter (none|packages|subpackages)</code></h4>
<p>
If no <a href="#--output_filter"><code class='flag'>--output_filter</code> option</a> is
given, Bazel creates an output filter from the targets listed on the command
line:
</p>
<ul>
<li>
<code>none</code> does no filtering and shows all output.
</li>
<li>
<code>packages</code> shows only the output for the packages of targets
requested on the command line. For example, the Bazel invocation
<pre> % bazel build //foo:bar //baz/...</pre>
will show the output for all targets in the package <code>foo</code> or any
package under <code>baz</code>. Warnings for dependencies in other packages
will be hidden.
</li>
<li>
<code>subpackages</code> (the default) works similar
to <code>packages</code> but also includes output from subpackages.
</li>
</ul>
<h4><code>--[no]analysis_warnings_as_errors</code></h4>
<p>
When this option is enabled, visible analysis warnings (as specified by
the output filter) are treated as errors, effectively preventing the build
phase from starting. This feature can be used to enable strict builds that
do not allow new warnings to creep into a project.
</p>
<h3 id='flags-options'>Flags options</h3>
<p>
These options control which options Bazel will pass to other tools.
</p>
<h4 id='flag--jvmopt'><code class='flag'>--jvmopt <var>jvm-option</var></code></h4>
<p>
This option allows option arguments to be passed to the Java VM. It can be used
with one big argument, or multiple times with individual arguments. For example:
</p>
<pre>
% bazel build --jvmopt="-server -Xms256m" java/com/myorg/foo/bar:all
</pre>
<p>
will use the server VM for launching all Java binaries and set the
startup heap size for the VM to 256 MB.
</p>
<h4 id='flag--javacopt'><code class='flag'>--javacopt <var>javac-option</var></code></h4>
<p>
This option allows option arguments to be passed to javac. It can be used
with one big argument, or multiple times with individual arguments. For example:
</p>
<pre>
% bazel build --javacopt="-g:source,lines" //myprojects:prog
</pre>
<p>
will rebuild a java_binary with the javac default debug info
(instead of the Bazel default).
</p>
<p>
The option is passed to javac after the Bazel built-in default options for
javac and before the per-rule options. The last specification of
any option to javac wins. The default options for javac are:
</p>
<pre>
-g -source 7 -target 7 -encoding UTF-8 -Xlint:all,-serial,-processing,-fallthrough,-deprecation,-sunapi,-rawtypes,-try,-cast,-varargs,-finally,-static,-dep-ann,-overrides,-unchecked -Werror:+divzero,+empty
</pre>
<p>
Note that changing <code class='flag'>--javacopt</code> settings will force a recompilation
of all affected classes. Also note that javacopts parameters listed in
specific java_library or java_binary build rules will be placed on the javac
command line <em>after</em> these options.
</p>
<h5 id='-Werror'><code>-Werror:<var>(+|-)warning[,(+|-)warning]*</var></code></h5>
<p>
This javac option enables selective treating of warnings as errors. To specify
all or none of the warnings, use <code>+all</code> or <code>-all</code>.
The last specification for any warning wins. A typical value that enables all
warnings as errors except those that may be caused upstream is:
</p>
<pre>
-Werror:+all,-deprecation,-unchecked
</pre>
<p>
The divzero and empty javac warnings are promoted to errors by default. These
errors cannot be disabled from the Bazel command line or the BUILD file.
However, in extreme cases they may be disabled by adding a
<code>@SuppressWarnings({"divzero", "empty"})</code> annotation to your Java
source.
</p>
<h5 id='-extra_checks'><code>-extra_checks[:(off|on)]</code></h5>
<p>
This javac option enables extra correctness checks. Any problems found will
be presented as errors.
Either <code>-extra_checks</code> or <code>-extra_checks:on</code> may be used
to force the checks to be turned on. <code>-extra_checks:off</code> completely
disables the analysis.
When this option is not specified, the default behavior is used.
</p>
<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps
(default|strict|off|warn|error)</code></h4>
<p>
This option controls whether javac checks for missing direct dependencies.
Java targets must explicitly declare all directly used targets as
dependencies. This flag instructs javac to determine the jars actually used
for type checking each java file, and warn/error if they are not the output
of a direct dependency of the current target.
</p>
<ul>
<li> <code>off</code> means checking is disabled.
</li>
<li> <code>warn</code> means javac will generate standard java warnings of
type <code>[strict]</code> for each missing direct dependency.
</li>
<li> <code>default</code>, <code>strict</code> and <code>error</code> all
mean javac will generate errors instead of warnings, causing the current
target to fail to build if any missing direct dependencies are found.
This is also the default behavior when the flag is unspecified.
</li>
</ul>
<h4><code class='flag'>--javawarn (all|cast|deprecation|empty|unchecked|fallthrough|path|rawtypes|serial|finally|overrides)</code></h4>
<p>
This option is used to enable Java warnings across an entire build. It takes
an argument which is a javac warning to be enabled, overriding any other Java
options that disable the given warning. The arguments to this option are
appended to the "-Xlint:" flag to javac, and must be exactly one of
the listed warnings.
</p>
<p>
For example:
</p>
<pre>
% bazel build --javawarn="deprecation" --javawarn="unchecked" //java/...
</pre>
<p>
Note that changing <code class='flag'>--javawarn</code> settings will force a recompilation
of all affected classes.
</p>
<h3 id='semantics-options'>Semantics options</h3>
<p>
These options affect the build commands and/or the output file contents.
</p>
<h4><code class='flag'>--java_cpu <var>cpu</var></code></h4>
<p>
This option specifies the name of the CPU architecture that should
be used to build libraries dynamically loaded by the JVM.
</p>
<h4><code class='flag'>--android_cpu <var>cpu</var></code></h4>
<p>
This option specifies the name of the CPU architecture
that should be used to build libraries dynamically loaded by the Android
applications.
</p>
<h4 id="flag--define"><code class='flag'>--define <em>name=value</em></code></h4>
<p>
This option takes an argument which is a variable
definition of the form "name=value". The defined variable is integrated
into the build environment as if they were declared in the BUILD file
using a <code>vardef</code> statement. This option can occur multiple times
on the command-line. If the same variable is declared more than once, the
<em>last</em> definition is the one which is used.
</p>
<pre>
% bazel build --define "INCLUDE_X=1" --define "LINK_Y=no" foo:bar
</pre>
<p>
will build target "foo:bar", and all its prerequisites, with the
variable assignments <code>INCLUDE_X=1</code>,
and <code>LINK_Y=no</code> in the "Make" environment.
</p>
<p>
Definitions specified in this way are global: they apply to all
packages. The order of precedence for definitions of "Make"
variables, highest first, is: <code class='flag'>--define
k=...</code>, <code>vardef('k',
...)</code>, then the global defaults.
</p>
<h4 id='flag--translations'><code class='flag'>--[no]translations</code></h4>
<p>
The <code class='flag'>--notranslations</code> option can be used to disable the bundling
of translated Java messages into the jar for each affected rule. By default,
Bazel will locate the Java message translations on the package path using the
targets defined by <a href="#--message_translations">
<code class='flag'>--message_translations</code></a> and use the resulting files for
translating the messages for each <code>java_library</code>. If no
targets are specified, Bazel does not bundle translations.
</p>
<h4 id='flag--message_translations'><code class='flag'>--message_translations
<var>translation-targets</var></code></h4>
<p>
This option specifies the targets containing the Java message
translations. These targets are used to
find the Java message translations for each locale. This option can
be used multiple times to specify a list of translations. The
targets are specified using standard label syntax. Rules that output
directories, such as
<a
href="build-encyclopedia.html#Fileset">Fileset</a>
and misbehaving genrules, cannot be used with this flag.
</p>
<p>
Typically translations will increase build times significantly.
</p>
<pre>
% bazel build \
--message_translations=//some/package/client:translations \
--message_translations=//some/package/server:translations \
java/com/myorg/myapp:Myapp_deploy.jar
</pre>
<p>
will build the <code>Myapp_deploy.jar</code> including
translations. The translations will be retrieved from the
project-specific translations in
<code>//some/package/client:translations</code>
and
<code>//some/package/server:translations</code>
</p>
<h3 id='version-options'>Version options</h3>
These options select which versions Bazel will use for the other tools that Bazel invokes.
<h4 id='android_sdk'><code class='flag'>--android_sdk <var>version</var></code></h4>
<p>
This option specifies the version of the Android SDK/platform toolchain
and Android runtime library that will be used to build any Android-related
rule.
</p>
<h4 id='flag--java_langtools'><code class='flag'>--java_langtools <var>label</var></code></h4>
<p>
This option specifies the label of the Java langtools jar (used by
Java compilation tools).
</p>
<h4><code class='flag'>--javabase <var>path</var></code></h4>
<p>
This option specifies the value of the <code>JAVABASE</code>
<a href='build-encyclopedia.html#make_variables'>"Make" variable</a>
which is passed to all subprocesses (e.g. external Java programs)
during a build.
</p>
<p>
This does not select the Java compiler that is used to compile Java
source files. There is currently no way to do that, but you can use
<code class='flag'>--javacopt="-source 5 -target 5"</code> (for example) to
select a different version of the source language (Java) or target
language (JVM) during compilation.
</p>
<h4 id='flag--javac_bootclasspath'><code class='flag'>--javac_bootclasspath <var>label</var></code></h4>
<p>
This option specifies the label of the bootclasspath that should be used by
the Java compiler. This lets you compile against different versions of the
Java class library, for example, version 7 instead of version 6.
</p>
<h3 id='strategy-options'>Build strategy options</h3>
<p>
These options affect how Bazel will execute the build.
They should not have any significant effect on the output files
generated by the build. Typically their main effect is on the
speed on the build.
</p>
<h4><code class='flag'>--jobs <var>n</var></code> (-j)</h4>
<p>
This option, which takes an integer argument, specifies a limit on
the number of jobs that should be executed concurrently during the
execution phase of the build. The default is 200.
</p>
<p>
Setting this to -1 means "no limit": use as many threads as possible.
</p>
<p>
Note that the number of concurrent jobs that Bazel will run
is determined not only by the <code class='flag'>--jobs</code> setting, but also
by Bazel's scheduler, which tries to avoid running concurrent jobs
that will use up more resources (RAM or CPU) than are available,
based on some (very crude) estimates of the resource consumption
of each job. The behavior of the scheduler can be controlled by
the <code class='flag'>--ram_utilization_factor</code> option.
</p>
<h4><code class='flag'>--progress_report_interval <var>n</var></code></h4>
<p>
Bazel periodically prints a progress report on jobs that are not
finished yet (e.g. long running tests). This option sets the
reporting frequency, progress will be printed every <code>n</code>
seconds.
</p>
<p>
The default is 0, that means an incremental algorithm: the first
report will be printed after 10 seconds, then 30 seconds and after
that progress is reported once every minute.
</p>
<h4><code class='flag'>--ram_utilization_factor</code> <var>percentage</var></h4>
<p>
This option, which takes an integer argument, specifies what percentage
of the system's RAM Bazel should try to use for its subprocesses.
This option affects how many processes Bazel will try to run
in parallel. The default value is 67.
If you run several Bazel builds in parallel, using a lower
value for this option may avoid thrashing and thus improve overall
throughput. Using a value higher than the default is NOT recommended. Note
that Bazel's estimates are very coarse, so the actual RAM usage may be much
higher or much lower than specified. Note also that this option does not
affect the amount of memory that the Bazel server itself will use.
</p>
<p>
This option has no effect if --resource_autosense is enabled.
</p>
<h4><code class='flag'>--local_resources</code> <var>availableRAM,availableCPU,availableIO</var></h4>
<p>
This option, which takes three comma-separated floating point arguments,
specifies the amount of local resources that Bazel can take into
consideration when scheduling build and test activities. Option expects amount of
available RAM (in MB), number of CPU cores (with 1.0 representing single full
core) and workstation I/O capability (with 1.0 representing average
workstation). By default Bazel will estimate amount of RAM and number of CPU
cores directly from system configuration and will assume 1.0 I/O resource.
</p>
<p>
If this option is used, Bazel will ignore both --ram_utilization_factor and
--resource_autosense options.
</p>
<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4>
<p>
This option, which is currently enabled by default, specifies
whether the runfiles symlinks for tests
should be built on the local
machine. Using <code class='flag'>--nobuild_runfile_links</code> can be useful
to validate if all targets build without incurring the overhead
for building the runfiles trees.Within Bazel's output tree, the
runfiles symlink tree is typically rooted as a sibling of the corresponding
binary or test.
</p>
<p>
When Bazel tests are executed, their
run-time data dependencies are gathered together in one place, and
may be accessed by the test using paths of the form
<code>$TEST_SRCDIR/bazel/<var>packagename</var>/<var>filename</var></code>.
The "runfiles" tree ensures that tests have access to all the files
upon which they have a declared dependence, and nothing more. By
default, the runfiles tree is implemented by constructing a set of
symbolic links to the required files. As the set of links grows, so
does the cost of this operation, and for some large builds it can
contribute significantly to overall build time, particularly because
each individual test requires its own runfiles tree.
</p>
<h4 id='flag--cache_analysis'><code class='flag'>--[no]cache_analysis</code></h4>
<p>
This option enables an optimization: caching of the results of the
analysis phase from one build to the next. The dependency graph
from the previous build will be re-used if no build packages have
been re-loaded due to changes, and no configuration options have
changed.
The optimization is enabled by default, but can be disabled
via <code class='flag'>--nocache_analysis</code>; this may be useful during fault
isolation.
</p>
<p>
Typically, this option speeds up
the <a href='#analysis-phase'>analysis phase</a> by a factor of at
least a hundred, making analysis time a negligible fraction of total
build time.
</p>
<h4 id='flag--discard_analysis_cache'>
<code class='flag'>--[no]discard_analysis_cache</code></h4>
<p>
When this option is enabled, Bazel will discard the analysis cache
right before execution starts, thus freeing up additional memory
(around 10%) for the <a href="#execution-phase">execution phase</a>.
The drawback is that further incremental builds will be slower.
</p>
<h4><code class='flag'>--[no]keep_going</code> (-k)</h4>
<p>
As in GNU Make, the execution phase of a build stops when the first
error is encountered. Sometimes it is useful to try to build as
much as possible even in the face of errors. This option enables
that behavior, and when it is specified, the build will attempt to
build every target whose prerequisites were successfully built, but
will ignore errors.
</p>
<p>
While this option is usually associated with the execution phase of
a build, it also effects the analysis phase: if several targets are
specified in a build command, but only some of them can be
successfully analyzed, the build will stop with an error
unless <code class='flag'>--keep_going</code> is specified, in which case the
build will proceed to the execution phase, but only for the targets
that were successfully analyzed.
</p>
<h4><code class='flag'>--[no]resource_autosense</code></h4>
<p>
Bazel's default scheduling algorithm is based on fixed estimates of
the available CPU/memory resources of the workstation. It does not
account for the load of any unrelated jobs that happen to be running
on your machine, such as another Bazel build in a different
workspace.
</p>
<p>
The <code class='flag'>--resource_autosense</code> option enables a different
scheduling algorithm for the execution of build steps. It causes
Bazel to poll the system CPU load and available memory periodically.
This data is used to limit the number of commands executed
simultaneously on the workstation, ensuring that the system remains
responsive, especially when other jobs are running on the machine.
</p>
<p>
(Note, neither algorithm takes into account the actual (dynamic)
cost of each build step.)
</p>
<h3 id='output-selection-options'>Output selection options</h3>
<p>
These options determine what to build or test.
</p>
<h4 id="nobuild"><code class='flag'>--[no]build</code></h4>
<p>
This option causes the execution phase of the build to occur; it is
on by default. When it is switched off, the execution phase is
skipped, and only the first two phases, loading and analysis, occur.
</p>
<p>
This option can be useful for validating BUILD files and detecting
errors in the inputs, without actually building anything.
</p>
<h4><code class='flag'>--[no]build_tests_only</code></h4>
<p>
If specified, Bazel will build only what is necessary to run the *_test
and test_suite rules that were not filtered due to their
<a href='#flag--test_size_filters'>size</a>,
<a href='#flag--test_timeout_filters'>timeout</a>,
<a href='#flag--test_tag_filters'>tag</a>, or
<a href='#flag--test_lang_filters'>language</a>.
If specified, Bazel will ignore other targets specified on the command line.
By default, this option is disabled and Bazel will build everything
requested, including *_test and test_suite rules that are filtered out from
testing. This is useful because running
<code>bazel test --build_tests_only foo/...</code> may not detect all build
breakages in the <code>foo</code> tree.
</p>
<h4 id="flag--compile_only"><code class='flag'>--[no]compile_only</code></h4>
<p>
This option forces Bazel to execute only "lightweight" compilation steps
related to the specified targets. At this time such steps only include
compilation of sources for <code>java_*</code> rules
without building dependencies.
</p>
<p>
This option can be useful to quickly validate a given Java target for
compilation errors. In particular, it might be especially useful when
specified together with the <a href="#flag--compile_one_dependency">
<code class='flag'>--compile_one_dependency</code></a> option.
</p>
<h4 id="flag--compilation_prerequisites_only"><code class='flag'>--[no]compilation_prerequisites_only</code></h4>
<p>
Given this option, Bazel will only build files that are prerequisites for
compilation of the given target (for example, generated source
files), but will not build the target itself.
</p>
<p>
This option can be useful to quickly validate a given Java target for
compilation errors. In particular, it might be especially useful when
specified together with the <a href="#flag--compile_one_dependency">
<code class='flag'>--compile_one_dependency</code></a> option.
</p>
<h4 id='flag--check_up_to_date'><code class='flag'>--[no]check_up_to_date</code></h4>
<p>
This option causes Bazel not to perform a build, but merely check
whether all specified targets are up-to-date. If so, the build
completes successfully, as usual. However, if any files are out of
date, instead of being built, an error is reported and the build
fails. This option may be useful to determine whether a build has
been performed more recently than a source edit (e.g. for pre-submit
checks) without incurring the cost of a build.
</p>
<p>
See also <a href="#flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></a>.
</p>
<h4 id='flag--compile_one_dependency'><code class='flag'>--[no]compile_one_dependency</code></h4>
<p>
Compile a single dependency of the argument files. This is useful for
syntax checking source files in IDEs, for example, by rebuilding a single
target that depends on the source file to detect errors as early as
possible in the edit/build/test cycle. This argument affects the way all
non-flag arguments are interpreted: for each source filename, one
rule that depends on it will be built.
Rules in the same language space are preferentially chosen. For
multiple rules with the same preference, the one that appears first in the
BUILD file is chosen. An explicitly named target pattern which does not
reference a source file results in an error.
</p>
<h4 id='flag--source_jars'><code class='flag'>--[no]source_jars</code></h4>
<p>
By default, this option is disabled. If enabled, Bazel will also build all
source jars in the transitive closure of the targets specified on the command
line.
</p>
<h4 id='flag--test_size_filters'><code class='flag'>--test_size_filters <var>size[,size]*</var></code></h4>
<p>
If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
is also specified) only test targets with the given size. Test size filter
is specified as comma delimited list of allowed test size values (small,
medium, large or enormous), optionally preceded with '-' sign used to denote
excluded test sizes. For example,
</p>
<pre>
% bazel test --test_size_filters=small,medium //foo:all
</pre>
and
<pre>
% bazel test --test_size_filters=-large,-enormous //foo:all
</pre>
<p>
will test only small and medium tests inside //foo.
</p>
<p>
By default, test size filtering is not applied.
</p>
<h4 id='flag--test_timeout_filters'><code class='flag'>--test_timeout_filters <var>timeout[,timeout]*</var></code></h4>
<p>
If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
is also specified) only test targets with the given timeout. Test timeout filter
is specified as comma delimited list of allowed test timeout values (short,
moderate, long or eternal), optionally preceded with '-' sign used to denote
excluded test timeouts. See <a href='#flag--test_size_filters'>--test_size_filters</a>
for example syntax.
</p>
<p>
By default, test timeout filtering is not applied.
</p>
<h4 id='flag--test_tag_filters'><code class='flag'>--test_tag_filters <var>tag[,tag]*</var></code></h4>
<p>
If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
is also specified) only test targets that have at least one required tag
(if any of them are specified) and does not have any excluded tags. Test tag
filter is specified as comma delimited list of tag keywords, optionally
preceded with '-' sign used to denote excluded tags. Required tags may also
have a preceding '+' sign.
</p>
<p>
For example,
<pre>
% bazel test --test_tag_filters=performance,stress,-flaky //myproject:all
</pre>
<p>
will test targets that are tagged with either <code>performance</code> or
<code>stress</code> tag but are <b>not</b> tagged with the <code>flaky</code>
tag.
</p>
<p>
By default, test tag filtering is not applied. Note that you can also filter
on test's <code>size</code> and <code>local</code> tags in
this manner.
</p>
<h4 id="flag--test_filter"><code class='flag'>--test_filter=<var>filter-expression</var></code></h4>
<p>
Specifies a filter that the test runner may use to pick a subset of tests for
running. All targets specified in the invocation are built, but depending on
the expression only some of them may be executed; in some cases, only certain
test methods are run.
</p>
<p>
The particular interpretation of <var>filter-expression</var> is up to
the test framework responsible for running the test. It may be a glob,
substring, or regexp. <code class='flag'>--test_filter</code> is a convenience
over passing different <code class='flag'>--test_arg</code> filter arguments,
but not all frameworks support it.
<p>
Examples:
</p>
<pre>
:my_junit3_test --test_filter=com.myorg.myproj.MyClass#testMyStuff
# class or method (multiple
# values OK, separate w/commas)
:my_junit4_test --test_filter=Frob.*ate # regexp
</pre>
<h3>Verbosity options: options that control what Bazel prints</h3>
These options control the verbosity of Bazel's output,
either to the terminal, or to additional log files.
<h4 id='flag--dump_makefile'><code class='flag'>--dump_makefile</code></h4>
<p>
If this option is specified, Bazel will dump a representation
of the action graph for the current build request in (pseudo)
<code>make</code> syntax to the file <code>Makefile.bazel</code>
in the execution root directory.
</p>
<p>
This is for debugging purposes only. The format of the output file
might change in future Bazel releases.
</p>
<h4 id='flag--dump_action_graph'><code class='flag'>--dump_action_graph</code></h4>
<p>
If this option is specified, Bazel will dump a representation of the
action graph for the current build request in GraphViz syntax to the
file 'BazelActionGraph.dot' in the workspace root.
</p>
<p>
This is for debugging purposes only. The format of the output file
might change in future Bazel releases.
</p>
<h4 id='flag--dump_action_graph_for_package'>
<code class='flag'>--dump_action_graph_for_package=package</code>
</h4>
<p>
This option restricts the parts shown in an action graph to the given packages.
This is only useful in conjunction with specifying <code class='flag'>--dump_action_graph</code>.
</p>
<h4 id='flag--dump_action_graph_with_middlemen'>
<code class='flag'>--dump_action_graph_with_middlemen</code>
</h4>
<p>
This flag selects whether middlemen are shown in an action graph or not. Middlemen could be
considered an implementation detail and tend to make graphs much larger.
This is only usful in conjuction with specifying <code class='flag'>--dump_action_graph</code>.
</p>
<h4 id='flag--dump_targets'><code class='flag'>--dump_targets=(inputs|rules|all|packages)</code></h4>
<p>
If this option is specified, Bazel will dump the targets touched
by the current build request to the file <code>BazelTargets.txt</code>.
</p>
<ul>
<li><code class='flag'>--dump_targets=inputs</code> will dump the labels of the input
file targets.</li>
<li><code class='flag'>--dump_targets=rules</code> will dump the labels of the rule
targets.</li>
<li><code class='flag'>--dump_targets=all</code> will dump the labels of the rule
and input file targets.</li>
<li><code class='flag'>--dump_targets=packages</code> will dump the package names of
the rule and input file targets.
<br/><strong>Please note:</strong>Only packages that contain
input files are dumped. BUILD files are not considered as input files.
That means that packages that do not contain any input files will not
be dumped. Even so they may be part of the transitive closure of the
current build request.</li>
</ul>
<h4 id='flag--dump_to_stdout'><code class='flag'>--dump_to_stdout</code></h4>
<p>
If this option is specified, the options
<code class='flag'>--dump_action_graph</code>, <code class='flag'>--dump_makefile</code>
and <code class='flag'>--dump_targets</code> will not dump to the files
specified above but to stdout.
</p>
<h4 id='flag--explain'><code class='flag'>--explain <var>logfile</var></code></h4>
<p>
This option, which requires a filename argument, causes the
dependency checker in <code>bazel build</code>'s execution phase to
explain, for each build step, either why it is being executed, or
that it is up-to-date. The explanation is written
to <i>logfile</i>.
</p>
<p>
If you are encountering unexpected rebuilds, this option can help to
understand the reason. Add it to your <code>.bazelrc</code> so that
logging occurs for all subsequent builds, and then inspect the log
when you see an execution step executed unexpectedly. This option
may carry a small performance penalty, so you might want to remove
it when it is no longer needed.
</p>
<h4 id='flag--verbose_explanations'><code class='flag'>--verbose_explanations</code></h4>
<p>
This option increases the verbosity of the explanations generated
when the <a href='#flag--explain'>--explain</a> option is enabled.
</p>
<p>
In particular, if verbose explanations are enabled,
and an output file is rebuilt because the command used to
build it has changed, then the output in the explanation file will
include the full details of the new command (at least for most
commands).
</p>
<p>
Using this option may significantly increase the length of the
generated explanation file and the performance penalty of using
<code class='flag'>--explain</code>.
</p>
<p>
If <code class='flag'>--explain</code> is not enabled, then
<code class='flag'>--verbose_explanations</code> has no effect.
</p>
<h4><code class='flag'>--profile <var>file</var></code></h4>
<p>
This option, which takes a filename argument, causes Bazel to write
profiling data into a file. The data then can be analyzed or parsed using the
<code>bazel analyze-profile</code> command. The Build profile can be useful in
understanding where Bazel's <code>build</code> command is spending its time.
</p>
<h4 id='flag--show_package_location'><code class='flag'>--[no]show_package_location</code></h4>
<p>
This option causes Bazel to display, as each package is loaded, the
directory on the <a href='#flag--package_path'>package path</a> beneath
which the package's BUILD file was found. This can be useful as a
diagnostic aid. Nothing is printed if the directory was the Bazel
workspace (<code>%workspace%</code>). For example:
</p>
<pre>
INFO Loading package: foo/bar/scripts
INFO Loading package: foo/bar/main
INFO Loading package: baz from ../$WORKSPACE_READONLY_ROOT
</pre>
<h4 id='flag--show_loading_progress'><code class='flag'>--[no]show_loading_progress</code></h4>
<p>
This option causes Bazel to output package-loading progress
messages. If it is disabled, the messages won't be shown.
</p>
<h4><code class='flag'>--[no]show_progress</code></h4>
<p>
This option causes progress messages to be displayed; it is on by
default. When disabled, progress messages are suppressed.
</p>
<h4><code class='flag'>--show_progress_rate_limit <var>n</var></code></h4>
<p>
This option causes Bazel to display only
one progress message per <code>n</code> seconds. If <code>n</code> is -1,
all progress messages will be displayed. The default value for this
option is -1.
</p>
<h4 id='flag--show_result'><code class='flag'>--show_result <var>n</var></code></h4>
<p>
This option controls the printing of result information at the end
of a <code>bazel build</code> command. By default, if a single
build target was specified, Bazel prints a message stating whether
or not the target was successfully brought up-to-date, and if so,
the list of output files that the target created. If multiple
targets were specified, result information is not displayed.
</p>
<p>
While the result information may be useful for builds of a single
target or a few targets, for large builds (e.g. an entire top-level
project tree), this information can be overwhelming and distracting;
this option allows it to be controlled. <code class='flag'>--show_result</code>
takes an integer argument, which is the maximum number of targets
for which full result information should be printed. By default,
the value is 1. Above this threshold, no result information is
shown for individual targets. Thus zero causes the result
information to be suppressed always, and a very large value causes
the result to be printed always.
</p>
<p>
Users may wish to choose a value in-between if they regularly
alternate between building a small group of targets (for example,
during the compile-edit-test cycle) and a large group of targets
(for example, when establishing a new workspace or running
regression tests). In the former case, the result information is
very useful whereas in the latter case it is less so. As with all
options, this can be specified implicitly via
the <a href='#bazelrc'><code>.bazelrc</code></a> file.
</p>
<p>
The files are printed so as to make it easy to copy and paste the
filename to the shell, to run built executables. The "up-to-date"
or "failed" messages for each target can be easily parsed by scripts
which drive a build.
</p>
<h4 id='flag--show_builder_stats'><code class='flag'>--show_builder_stats</code></h4>
<p>
This option will enable parallel builder to output several internal statistics
after each completed action. Statistic includes following sections:
</p>
<pre>
time since the start of execution phase;
queue: cumulative number of queued and dequeued actions. At the end of the
build those two numbers should be equal to the number of actions.
threads: number of scheduled tasks, number of active threads in the pool,
number of threads not waiting on resources and number of threads
executing action payload;
actions: number of actions waiting on single remaining unbuilt dependency
before they can get scheduled and number of total actions in the
build;
locked: number of threads being blocked by resource (ram, cpu, etc) locks.
&gt;&gt;&gt; [action name]: for actions that are potentially on the critical build path
(at the time of action completion there were no actions
awaiting execution).
</pre>
<p>
Examples:
</p>
<pre>
____13.5 s, queue: 400 / 262, threads: 138 / 20 / 19 / 18, actions: 47 (608), locked: 1
____22.8 s, queue: 464 / 453, threads: 11 / 11 / 3 / 3, actions: 16 (608), locked: 8 &gt;&gt;&gt; action 'Building foo/bar/Myapp_deploy.jar'
</pre>
<p>
Please, note, that this flag is mostly intended for internal Bazel profiling
and can change or disappear at any time.
</p>
<h4 id='flag--subcommands'><code class='flag'>--subcommands</code> (-s)</h4>
<p>
This option causes Bazel's execution phase to print the full command line
for each command prior to executing it.
</p>
<p>
Where possible, commands are printed in a Bourne shell compatible syntax,
so that they can be easily copied and pasted to a shell command prompt.
(The surrounding parentheses are provided to protect your shell from the
<code>cd</code> and <code>exec</code> calls; be sure to copy them!)
All commands output by <code class='flag'>--subcommands</code>
are executable by <code>/bin/sh</code> or <code>bash</code>.
</p>
<p>
See also <a href="#--verbose_failures">--verbose_failures</a>, below.
</p>
<h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4>
<p>
This option causes Bazel's execution phase to print the full command line
for commands that failed. This can be invaluable for debugging a
failing build.
</p>
<p>
Failing commands are printed in a Bourne shell compatible syntax, suitable
for copying and pasting to a shell prompt.
</p>
<h3 id='misc_build_options'>Miscellaneous options</h3>
<h4 id='flag--symlink_prefix'><code class='flag'>--symlink_prefix <var>string</var></code></h4>
<p>
Changes the prefix of the generated convenience symlinks. The
default value for the symlink prefix is <code>bazel-</code> which
will create the symlinks <code>bazel-bin</code>, <code>bazel-testlogs</code>, and
<code>bazel-genfiles</code>.
</p>
<p>
If the symbolic links cannot be created for any reason, a warning is
issued but the build is still considered a success. In particular,
this allows you to build in another user's client, or a read-only
directory. Any paths printed in informational
messages at the conclusion of a build will only use the
symlink-relative short form if the symlinks point to the expected
location; in other words, you can rely on the correctness of those
paths, even if you cannot rely on the symlinks being created.
</p>
<p>
Some common values of this option:
</p>
<ul>
<li>
<p><b>Suppress symlink creation:</b>
<code class='flag'>--symlink_prefix=/</code> will cause Bazel to not
create or update any symlinks. Use this option to suppress symlink
creation entirely.
</p>
</li>
<li>
<p><b>Reduce clutter:</b>
<code class='flag'>--symlink_prefix=.bazel/</code> will cause Bazel to create
symlinks called <code>bin</code> (etc) inside a hidden
directory <code>.bazel</code>. Some users use this to avoid
cluttering their bazel directory with files.
</p>
</li>
</ul>
<h2 id='test'>Running tests with Bazel</h2>
<p>
To build and run tests with Bazel, type <code>bazel test</code> followed by
the name of the test targets using embedded test runner.
</p>
<p>
By default, this command performs simultaneous build and test
activity, building all specified targets (including any non-test
targets specified on the command line) and testing
<code>*_test</code> and <code>test_suite</code> targets as soon as
their prerequisites are built, meaning that test execution is
interleaved with building. Doing so usually results in significant
speed gains, especially when using a distributed environment.
</p>
<h3>Options for <code>bazel test</code></h3>
<h4 id="flag--cache_test_results"><code class='flag'>--cache_test_results=(yes|no|auto)</code> (-t)</h4>
<p>
If this option is set to yes then Bazel will only rerun a test if any of the
following conditions apply:
</p>
<ul>
<li>Bazel detects changes in the test or its dependencies</li>
<li>the test is marked as <code>external</code></li>
<li>a cached result does not exist or is older than the interval specified by the
<code class='flag'>--test_result_expiration</code> option.</li>
</ul>
<p>
If 'auto' (the default), the caching behavior will be the same as 'yes' except that
Bazel will never cache test failures and never cache multiple test runs
that were requested with <code class='flag'>--runs_per_test</code>.
</p>
<p>
If 'no', all tests will be always executed unconditionally.
</p>
<p>
Note that test results are <em>always</em> saved in Bazel's output tree,
regardless of whether this option is enabled, so
you needn't have used <code class='flag'>--cache_test_results</code> on the
prior run(s) of <code>bazel test</code> in order to get cache hits.
The option only affects whether Bazel will <em>use</em> previously
saved results, not whether it will save results of the current run.
</p>
<p>
Users who have enabled this option by default in
their <code>.bazelrc</code> file may find the
abbreviations <code>-t</code> (on) or <code>-t-</code> (off)
convenient for overriding the default on a particular run.
</p>
<h4 id="flag--test_result_expiration"><code class='flag'>--test_result_expiration=&lt;seconds&gt;</code></h4>
<p>
Specifies interval (in seconds) during which test results from the previous test
execution will be considered valid. This option is applicable only when used with
'yes' or default ('auto') value of the <code class='flag'>--cache_test_results</code> option. Otherwise,
it is ignored. Setting option to 0 expires cached results immediately and, as such, is
the same as <code class='flag'>--nocache_test_results</code>. Setting the option to -1 results in
never expiring the cached result.
</p>
<h4 id="flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></h4>
<p>
This option tells Bazel not to run the tests, but to merely check and report
the cached test results. If there are any tests which have not been
previously built and run, or whose tests results are out-of-date (e.g. because
the source code or the build options have changed), then Bazel will report
an error message ("test result is not up-to-date"), will record the test's
status as "NO STATUS" (in red, if color output is enabled), and will return
a non-zero exit code.
</p>
<p>
This option also implies
<code><a href="#--check_up_to_date">--check_up_to_date</a></code> behavior.
</p>
<p>
This option may be useful for pre-submit checks.
</p>
<h4 id="flag--test_verbose_timeout_warnings"><code class='flag'>--test_verbose_timeout_warnings</code></h4>
<p>
This option tells Bazel to explicitly warn the user if a test's timeout is
significantly longer then the test's actual execution time. While a test's
timeout should be set such that it is not flaky, a test that has a highly
over-generous timeout can hide real problems that crop up unexpectedly.
</p>
<p>
For instance, a test that normally executes in a minute or two should not have
a timeout of ETERNAL or LONG as these are much, much too generous. Bazel can generate a warning
if the stated timeout is much too generous based on the results of the test
run. This option is useful to help users decide on a good timeout value or
sanity check existing timeout values.
</p>
<p>
Note that each test shard is allotted the timeout of the entire
<code>XX_test</code> target. Using this option does not affect a test's timeout
value, merely warns if Bazel thinks the timeout could be restricted further.
</p>
<h4 id='flag--test_keep_going'><code class='flag'>--[no]test_keep_going</code></h4>
<p>
By default, all tests are run to completion. If this flag is disabled,
however, the build is aborted on any non-passing test. Subsequent build steps
and test invocations are not run, and in-flight invocations are canceled.
Do not specify both <code class='flag'>--notest_keep_going</code> and
<code class='flag'>--keep_going</code>.
</p>
<h4 id='flag--flaky_test_attempts'><code class='flag'>--flaky_test_attempts <var>attempts</var></code></h4>
<p>
This option specifies the maximum number of times a test should be attempted
if it fails for any reason. A test that initially fails but eventually
succeeds is reported as <code>FLAKY</code> on the test summary. It is,
however, considered to be passed when it comes to identifying Bazel exit code
or total number of passed tests. Tests that fail all allowed attempts are
considered to be failed.
</p>
<p>
By default (when this option is not specified, or when it is set to
&quot;default&quot;), only a single attempt is allowed for regular tests, and
3 for test rules with the <code>flaky</code> attribute set. You can specify
an integer value to override the maximum limit of test attempts. Bazel allows
a maximum of 10 test attempts in order to prevent abuse of the system.
</p>
<h4 id='flag--runs_per_test'><code class='flag'>--runs_per_test <var>[regex@]number</var></code></h4>
<p>
This option specifies the number of times each test should be executed. All
test executions are treated as separate tests (e.g. fallback functionality
will apply to each of them independently).
</p>
<p>
The status of a target with failing runs depends on the value of the
<code>--runs_per_test_detects_flakes</code> flag:
</p>
<ul>
<li>If absent, any failing run causes the entire test to fail.</li>
<li>If present and two runs from the same shard return PASS and FAIL, the test
will receive a status of flaky (unless other failing runs cause it to
fail).</li>
</ul>
<p>
If a single number is specified, all tests will run that many times.
Alternatively, a regular expression may be specified using the syntax
regex@number. This constrains the effect of --runs_per_test to targets
which match the regex (e.g. "--runs_per_test=^//pizza:.*@4" runs all tests
under //pizza/ 4 times).
This form of --runs_per_test may be specified more than once.
</p>
<h4 id='flag--runs_per_test_detects_flakes'><code
class='flag'>--[no]runs_per_test_detects_flakes</code></h4>
<p>
If this option is specified (by default it is not), Bazel will detect flaky
test shards through --runs_per_test. If one or more runs for a single shard
fail and one or more runs for the same shard pass, the target will be
considered flaky with the flag. If unspecified, the target will report a
failing status.
</p>
<h4 id='flag--test_summary'><code class='flag'>--test_summary <var>output_style</var></code></h4>
<p>
Specifies how the test result summary should be displayed.
</p>
<ul>
<li><code>short</code> prints the results of each test along with the name of
the file containing the test output if the test failed. This is the default
value.
</li>
<li><code>terse</code> like <code>short</code>, but even shorter: only print
information about tests which did not pass.
</li>
<li><code>detailed</code> prints each individual test case that failed, not
only each test. The names of test output files are omitted.
</li>
<li><code>none</code> does not print test summary.
</li>
</ul>
<h4 id='flag--test_output'><code class='flag'>--test_output <var>output_style</var></code></h4>
<p>
Specifies how test output should be displayed:
</p>
<ul>
<li><code>summary</code> shows a summary of whether each test passed or
failed. Also shows the output log file name for failed tests. The summary
will be printed at the end of the build (during the build, one would see
just simple progress messages when tests start, pass or fail).
This is the default behavior.
</li>
<li><code>errors</code> sends combined stdout/stderr output from failed tests
only into the stdout immediately after test is completed, ensuring that
test output from simultaneous tests is not interleaved with each other.
Prints a summary at the build as per summary output above.
</li>
<li><code>all</code> is similar to <code>errors</code> but prints output for
all tests, including those which passed.
</li>
<li><code>streamed</code> streams stdout/stderr output from each test in
real-time. This option implies
<code class='flag'>--test_sharding_strategy=disabled</code>.
</li>
</ul>
<h4 id='flag--java_debug'><code class='flag'>--java_debug</code></h4>
<p>
This option causes the Java virtual machine of a java test to wait for a connection from a
JDWP-compliant debugger (such as jdb or Eclipse) before starting the test. This option implies
--test_output=streamed.
</p>
<h4 id='flag--verbose_test_summary'><code class='flag'>--[no]verbose_test_summary</code></h4>
<p>
By default this option is enabled, causing test times and other additional
information (such as test attempts) to be printed to the test summary. If
<code class='flag'>--noverbose_test_summary</code> is specified, test summary will
include only test name, test status and cached test indicator and will
be formatted to stay within 80 characters when possible.
</p>
<h4 id='flag--test_tmpdir'><code class='flag'>--test_tmpdir <var>path</var></code></h4>
<p>
Specifies temporary directory for tests executed locally. Each test will be
executed in a separate subdirectory inside this directory. The directory will
be cleaned at the beginning of the each <code>bazel test</code> command.
By default, Bazel will place this directory under Bazel output base directory.
Note that this is a directory for running tests, not storing test results
(those are always stored under the <code>bazel-out</code> directory).
</p>
<h4 id='flag--test_timeout'>
<code class='flag'>--test_timeout
<var>seconds</var></code>
OR
<code class='flag'>--test_timeout
<var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var>
</code>
</h4>
<p>
Overrides the timeout value for all tests by using specified number of
seconds as a new timeout value. If only one value is provided, then it will
be used for all test timeout categories.
</p>
<p>
Alternatively, four comma-separated values may be provided, specifying
individual timeouts for short, moderate, long and eternal tests (in that
order).
In either form, zero or a negative value for any of the test sizes will
be substituted by the default timeout for the given timeout categories.
By default, Bazel will use Test Encyclopedia timeouts for all tests by
inferring the timeout limit from the test's size whether the size is
implicitly or explicitly set.
</p>
<p>
Tests which explicitly state their timeout category as distinct from their
size will receive the same value as if that timeout had been implicitly set by
the size tag. So a test of size 'small' which declares a 'long' timeout will
have the same effective timeout that a 'large' tests has with no explicit
timeout.
</p>
<h4 id='flag--test_arg'><code class='flag'>--test_arg <var>arg</var></code></h4>
<p>
Passes command-line options/flags/arguments to the test (not to the test runner). This
option can be used multiple times to pass several arguments, e.g.
<code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>.
</p>
<h4 id='flag--test_env'><code class='flag'>--test_env <var>variable</var>=<i>value</i></code>
OR
<code class='flag'>--test_env <var>variable</var></code></h4>
<p>
Specifies additional variables that must be injected into the test
environment for each test. If <var>value</var> is not specified it will be
inherited from the shell environment used to start the <code>bazel test</code>
command.
</p>
<p>
The environment can be accessed from within a test by using
<code>System.getenv("var")</code> (Java),
</p>
<h4 id='sharding-strategy'><code class='flag'>--test_sharding_strategy <var>strategy</var>
</code></h4>
<p>
Specifies one of the following strategies to be used for
test sharding.
With test sharding, each shard will run as a separate process and will
execute approximately <code>(1/N)</code>th of the total number of tests
methods. This can result in significant test latency improvements.
</p>
<p>
The default is <code>explicit</code>.
</p>
<ul>
<li><code>explicit</code> will only use sharding if the
<code>shard_count</code> BUILD attribute is present.
</li>
<li><code>disabled</code> will never shard tests.
</li>
<li><code>experimental_heuristic</code> (experimental) will enable sharding
on distributed tests without an explicit <code>shard_count</code> attribute
which link in a supported framework. This option is considered experimental
primarily because there may be false positives: in certain pathological
circumstances, Bazel might attempt to shard a test that does not speak the
sharding protocol.
</li>
</ul>
<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
<p>
This specifies a prefix that the test runner will insert in front
of the test command before running it. The
<var>command-prefix</var> is split into words using Bourne shell
tokenization rules, and then the list of words is prepended to the
command that will be executed.
</p>
<p>
If the first word is a fully qualified label (i.e. starts with
<code>//</code>) it is built. Then the label is substituted by the
corresponding executable location that is prepended to the command
that will be executed along with the other words.
<p>
Some caveats apply:
</p>
<ul>
<li>
The PATH used for running tests may be different than the PATH in your environment,
so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code>
command (the first word in <var>command-prefix</var>).
</li>
<li>
<b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code>
can't be used for interactive commands.
</li>
</ul>
<p>
Examples:
</p>
<pre>
--run_under=/usr/bin/valgrind
--run_under=/usr/bin/strace
--run_under='/usr/bin/strace -c'
--run_under='/usr/bin/valgrind --quiet --num-callers=20'
--run_under=//testing/valgrind:tsan
--run_under='//testing/valgrind:memcheck --gen-suppressions=all -v'
</pre>
<h4>Test selection</h4>
<p>
As documented under <a href='#output-selection-options'>Output selection options</a>,
you can filter tests by <a href='#flag--test_size_filters'>size</a>,
<a href='#flag--test_timeout_filters'>timeout</a>,
<a href='#flag--test_tag_filters'>tag</a>, or
<a href='#flag--test_lang_filters'>language</a>. A convenience
<a href='#flag--test_filter'>general name filter</a> can forward particular
filter args to the test runner.
</p>
<h4>Other options for <code>bazel test</code></h4>
<p>
The syntax and the remaining options are exactly like
<a href='#build'>bazel build</a>.
</p>
<h3 id='tags_keywords'>Test rule <code>tags</code> attribute keywords and other
common attributes</h3>
<p>
Bazel modifies test behavior if it finds the following keywords in the
<code>tags</code> attribute of the test rule:
</p>
<ul>
<li><code>exclusive</code> keyword will force test to be run in the
&quot;exclusive&quot; mode, ensuring that no other tests are running at the
same time. Such tests will be executed in serial fashion after all build
activity and non-exclusive tests have been completed.
</li>
<li><code>manual</code> keyword will force test to be ignored by all command
line wildcards (<code>...</code>, <code>:*</code>, <code>:all</code>, etc).
It will also be ignored by the <code>test_suite</code> rules that do not
mention this test explicitly. The only way
to run such test is to specify it explicitly on the command line.
</li>
<li><code>external</code> keyword will force test to be unconditionally
executed (regardless of <code class='flag'>--cache_test_results</code> value).
</li>
</ul>
<p>
There are also several other attributes that affect test behavior:
</p>
<ul>
<li>Test rules marked with the <code>flaky=1</code> attribute are considered
to be flaky and will be automatically retried up to 3 times unless larger
<code class='flag'>--flaky_test_attempts</code> value has been specified.
</li>
<li>Test rules marked with the <code>obsolete=1</code> attribute will be
ignored by the <code>test_suite</code> rules and by all command line
wildcards - this behavior is identical to the <code>manual</code> keyword
described above.
</li>
</ul>
<h2 id='run'>Running executables with Bazel</h2>
<p>
The <code>bazel run</code> command is similar to <code>bazel build</code>, except
it is used to build and run a single target. Here is a typical session:
</p>
<pre>
% bazel run -- java/myapp:myapp --arg1 --arg2
Welcome to Bazel
INFO: Loading package: java/myapp
INFO: Loading package: foo/bar
INFO: Loading complete. Analyzing...
INFO: Building 1 target...
[0%] Building java/myapp/myapp
[0%] Creating runfiles directory java/myapp/myapp.runfiles
...
Target //java/myapp:myappp up-to-date:
bazel-bin/java/myapp:myapp
INFO: Elapsed time: 5.072s
Hello there
$EXEC_ROOT/java/myapp/myapp
--arg1
--arg2
</pre>
<p>
Note the use of the <code>--</code>. This is needed so that Bazel
does not interpret <code>--arg1</code> and <code>--arg2</code> as
Bazel options, but rather as part of the command line for running the binary.
</p>
<h3>Options for <code>bazel run</code></h3>
<h4 id='flag--run_under_run'><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
<p>
This has the same effect as the <code class='flag'>--run_under</code> option for
<code>bazel test</code> (<a href='#flag--run_under'>see above</a>),
except that it applies to the command being run by <code>bazel
run</code> rather than to the tests being run by <code>bazel test</code>
and cannot run under label.
</p>
<h2 id='query'>Querying the dependency graph with Bazel</h2>
<p>
Bazel includes a query language for asking questions about the
dependency graph used during the build. The query tool is an
invaluable aid to many software engineering tasks.
</p>
<p>
The query language is based on the idea of
algebraic operations over graphs; it is documented in detail
in <a href='bazel-query-v2.html'>Bazel Query Language, revision
2</a>. Please refer to that document for reference, for
examples, and for query-specific command-line options.
</p>
<p>
The query tool accepts several command-line
option. <code class='flag'>--output</code> selects the output format.
<code class='flag'>--[no]keep_going</code> (disabled by default) causes the query
tool to continue to make progress upon errors; this behavior may be
disabled if an incomplete result is not acceptable in case of errors.
</p>
<p>
The <code class='flag'>--[no]implicit_deps</code> option, enabled by default, causes
implicit dependencies
to be included in the dependency graph over which the query operates. An
implicit dependency is one that is not explicitly specified in the BUILD file
but added by Bazel.
</p>
<p>
Example: "Show the locations of the definitions (in BUILD files) of
all genrules required to build all the tests in the ABC tree."
</p>
<pre>
bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
</pre>
<h2 id='misc'>Miscellaneous Bazel commands and options</h2>
<h3 id='help'>The <code>help</code> command</h3>
<p>
The <code>help</code> command provides on-line help. By default, it
shows a summary of available commands and help topics, as shown in
the <a href='#concepts'><i>Bazel Concepts</i></a> section above.
Specifying an argument displays detailed help for a particular
topic. Most topics are Bazel commands, e.g. <code>build</code>
or <code>query</code>, but there are some additional help topics
that do not correspond to commands.
</p>
<h4><code class='flag'>--[no]long</code> (-l)</h4>
<p>
By default, <code>bazel help [<var>topic</var>]</code> prints only a
summary of the relevant options for a topic. If
the <code class='flag'>--long</code> option is specified, the type, default value
and full description of each option is also printed.
</p>
<h3 id='shutdown'>The <code>shutdown</code> command</h3>
<p>
Bazel server processes (see <a href='#client/server'>Client/server
implementation</a>) may be stopped by using the <code>shutdown</code>
command. This command causes the Bazel server to exit as soon as it
becomes idle (i.e. after the completion of any builds or other
commands that are currently in progress).
Bazel servers stop themselves after an idle timeout, so this command
is rarely necessary; however, it can be useful in scripts when it is
known that no further builds will occur in a given workspace.
</p>
<p>
<code>shutdown</code> accepts one
option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which
requires an integer argument. If specified, this makes the shutdown
conditional on the amount of memory already consumed. This is
useful for scripts that initiate a lot of builds, as any memory
leaks in the Bazel server could cause it to crash spuriously on
occasion; performing a conditional restart preempts this condition.
</p>
<h3 id='info'>The <code>info</code> command</h3>
<p>
The <code>info</code> command prints various values associated with
the Bazel server instance, or with a specific build configuration.
(These may be used by scripts that drive a build.)
</p>
<p>
The <code>info</code> command also permits a single (optional)
argument, which is the name of one of the keys in the list below.
In this case, <code>bazel info <var>key</var></code> will print only
the value for that one key. (This is especially convenient when
scripting Bazel, as it avoids the need to pipe the result
through <code>sed -ne /key:/s/key://p</code>:
</p>
<h4>Configuration-independent data</h4>
<ul>
<li><code>release</code>: the release label for this Bazel
instance, or "development version" if this is not a released
binary.
</li>
<li><code>workspace</code> the absolute path to this Baze;
workspace.
</li>
<li><code>install_base</code>: the absolute path to the installation
directory used by this Bazel instance for the current user. Bazel
installs its internally required executables below this directory.
</li>
<li><code>output_base</code>: the absolute path to the base output
directory used by this Bazel instance for the current user and
workspace combination. Bazel puts all of its scratch and build
output below this directory.
</li>
<li><code>execution_root</code>: the absolute path to the execution
root directory under output_base. This directory is the root for all files
accessible to commands executed during the build, and is the working
directory for those commands. If the workspace directory is writable, a
symlink is placed there pointing to this
directory.
</li>
<li><code>output_path</code>: the absolute path to the output
directory beneath the execution root used for all files actually
generated as a result of build commands. If the workspace directory is
writable, a symlink named <code>bazel-out</code> is placed there pointing
to this directory.
</li>
<li><code>server_pid</code>: the process ID of the Bazel server
process. </li>
<li><code>command_log</code>: the absolute path to the command log file;
this contains the interleaved stdout and stderr streams of the most recent
Bazel command. Note that running <code>bazel info</code> will overwrite the
contents of this file, since it then becomes the most recent Bazel command.
However, the location of the command log file will not change unless you
change the setting of the <code class='flag'>--output_base</code> or
<code class='flag'>--output_user_root</code> options.
</li>
<li><code>server_log</code>: the absolute path to the Bazel server's
log file; this contains useful information for debugging Bazel.
</li>
<li><code>used-heap-size</code>,
<code>committed-size</code>,
<code>max-heap-size</code>: reports various JVM heap size
parameters. Respectively: memory currently used, memory currently
guaranteed to be available to the JVM from the system, maximum
possible allocation.
</li>
<li><code>gc-count</code>, <code>gc-time</code>: The cumulative count of
garbage collections since the start of this Bazel server and the time spent
to perform them. Note that these values are not reset at the start of every
build.
</li>
<li><code>package_path</code>: A colon-separated list of paths which would be
searched for packages by Bazel. Has the same format as the
<code class='flag'>--package_path</code> build command line argument.
</li>
</ul>
<p>
Example: the process ID of the Bazel server.
</p>
<pre>% bazel info server_pid
1285
</pre>
<h4>Configuration-specific data</h4>
<p>
These data may be affected by the configuration options passed
to <code>bazel info</code>, for
example <code class='flag'>--define</code>.
The <code>info</code> command accepts all
the <a href='#analysis-options'>options that control dependency
analysis</a>, since some of these determine the location of the
output directory of a build, the choice of compiler, etc.
</p>
<ul>
<li>
<code>bazel-bin</code>, <code>bazel-testlogs</code>,
<code>bazel-genfiles</code>: reports the absolute path to
the <code>bazel-*</code> directories in which programs generated by the
build are located. This is usually, though not always, the same as
the <code>bazel-*</code> symlinks created in the bazel workspace after a
successful build. However, if the workspace directory is read-only,
no <code>bazel-*</code> symlinks can be created. Scripts that use
the value reported by <code>bazel info</code>, instead of assuming the
existence of the symlink, will be more robust.
</li>
<li>
The complete
<a href='build-encyclopedia.html#make_variables'
>"Make" environment</a>. If the <code class='flag'>--show_make_env</code> flag is
specified, all variables in the current configuration's "Make" environment
are also displayed (e.g. <code>JAVABASE</code>).
These are the variables accessed using the <code>$(JAVABASE)</code>
or <code>varref("JAVABASE")</code> syntax inside BUILD files.
</li>
</ul>
<h3 id='version'>The <code>version</code> command</h3>
<p>
The version command prints version details about the built Bazel
binary, including the changelist at which it was built and the date.
These are particularly useful in determining if you have the latest
Bazel. Some of the interesting values are:
</p>
<ul>
<li><code>label</code>: the release label for this Bazel
instance, or "development version" if this is not a released
binary.
</li>
</ul>
<h3 id='analyze-profile'>The <code>analyze-profile</code> command</h3>
<p>
The <code>analyze-profile</code> command analyzes data previously gathered
during the build using <code class='flag'>--profile</code> option. It provides several
options to either perform analysis of the build execution or export data in
the specified format.
</p>
<h3 id='canonicalize'>The <code>canonicalize-flags</code> command</h3>
<p>
The <code>canonicalize-flags</code> command, which takes a list of options for
a Bazel command and returns a list of options that has the same effect. The
new list of options is canonical, i.e., two lists of options with the same
effect are canonicalized to the same new list.
</p>
<p>
The <code class='flag'>--for_command</code> option can be used to select between different
commands. At this time, only <code>build</code> and <code>test</code> are
supported. Options that the given command does not support cause an error.
</p>
<p>
Note that a small number of options cannot be reordered, because Bazel cannot
ensure that the effect is identical.
</p>
<h3 id='startup_options'>Bazel startup options</h3>
<p>
The options described in this section affect the startup of the Java
virtual machine used by Bazel server process, and they apply to all
subsequent commands handled by that server. If there is an already
running Bazel server and the startup options do not match, it will
be restarted.
</p>
<p>
All of the options described in this section must be specified using the
<code class='flag'>--key=value</code> or <code class='flag'>--key value</code>
syntax. Also, these options must appear <i>before</i> the name of the Bazel
command.
</p>
<h4><code class='flag'>--output_base=<var>dir</var></code></h4>
<p>
This option requires a path argument, which must specify a
writable directory. Bazel will use this location to write all its
output. The output base is also the key by which the client locates
the Bazel server. By changing the output base, you change the server
which will handle the command.
</p>
<p>
By default, the output base is derived from the user's login name,
and the name of the workspace directory (actually, its MD5 digest),
so a typical value looks
like: <code>/usr/local/_bazel_myname/d41d8cd98f00b204e9800998ecf8427e</code>.
Note that the client uses the output base to find the Bazel server
instance, so if you specify a different output base in a Bazel
command, a different server will be found (or started) to handle the
request. It's possible to perform two concurrent builds in the same
bazel workspace by varying the output base:
</p>
<pre>
% bazel --output_base /tmp/1 build //foo &amp; bazel --output_base /tmp/2 build //bar
</pre>
<p>
In this command, the two Bazel commands run concurrently (because of
the shell <code>&amp;</code> operator), each using a different Bazel
server instance (because of the different output bases).
In contrast, if the default output base was used in both commands,
then both requests would be sent to the same server, which would
handle them sequentially: a <code>foo</code> build first, followed
by an incremental build of <code>bar</code>.
</p>
<p>
We recommend you do not use NFS locations for the output base, as
the higher access latency of NFS will cause noticeably slower
builds. Also, this places unnecessary loads on the NFS filers.
</p>
<h4><code class='flag'>--output_user_root=<var>dir</var></code></h4>
<p>
By default, the <code>output_base</code> value is chosen to as to
avoid conflicts between multiple users building in the same client.
In some situations, though, it is desirable to build from a client
shared between multiple users; release engineers may do this. In
those cases it may be useful to deliberately override the default so
as to ensure "conflicts" (i.e., sharing) between multiple users.
Use the <code class='flag'>--output_user_root</code> option to achieve this: the
output base is placed in a subdirectory of the output user root,
with a unique name based on the workspace, so the result of using an
output user root that is not a function of <code>$USER</code> is
sharing. Of course, it is important to ensure (via umask and group
membership) that all the cooperating users can read/write each
others files.
</p>
<p>
If the <code class='flag'>--output_base</code> option is specified, it overrides
using <code class='flag'>--output_user_root</code> to calculate the output base.
</p>
<p>
The install base location is also calculated based on
<code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded
binaries.
</p>
<p>
You can also use the <code class='flag'>--output_user_root</code> option to choose an
alternate base location for all of Bazel's output (install base and output
base) if there is a better location in your filesystem layout.
</p>
<h4><code class='flag'>--host_jvm_args=<var>string</var></code></h4>
<p>
Specifies a space-separated list of startup options to be passed to
the Java virtual machine in which <i>Bazel itself</i> runs. This
can be used to set the stack size, for example:
</p>
<pre>
% bazel --host_jvm_args="-Xss256K" build //base
</pre>
<p>
This option can be used multiple times with individual arguments. Note that
setting this flag should rarely be needed. Default heap size values passed
to the JVM from Bazel are set aggressively in both the 32-bit and 64-bit
case (<code>3000MB</code> and <code>10GB</code>, respectively).
</p>
<p>
(Please note that this does <i>not</i> affect any JVMs used by
subprocesses of Bazel: applications, tests, tools, etc. To pass
JVM options to executable Java programs, whether run by <code>bazel
run</code> or on the command-line, you should use
the <code>--jvm_flags</code> argument which
all <code>java_binary</code> and <code>java_test</code> programs
support. Alternatively for tests, use <code>bazel
test --test_arg=--jvm_flags=foo ...</code>.)
</p>
<h4><code class='flag'>--host_jvm_debug</code></h4>
<p>
This option causes the Java virtual machine to wait for a connection
from a JDWP-compliant debugger (such as jdb or Eclipse) before
calling the main method of <i>Bazel itself</i>. This is primarily
intended for use by Bazel developers.
</p>
<p>
(Please note that this does <i>not</i> affect any JVMs used by
subprocesses of Bazel: applications, tests, tools, etc.)
</p>
<h4 id='batch'><code class='flag'>--batch</code></h4>
<p>
This switch will cause Bazel to be run in batch mode, instead of the
standard client/server mode described <a href='#client/server'>above</a>.
Doing so provides more predictable semantics with respect to signal handling,
job control, and environment variable inheritance.
</p>
<p>
Batch mode retains proper queueing semantics within the same output_base.
That is, simultaneous invocations will be processed in order, without overlap.
If a batch mode Bazel is run on a client with a running server, it first
kills the server before processing the command.
</p>
<p>
Bazel will run slower in batch mode, compared to client/server mode.
Among other things, the build file cache is memory-resident, so it is not
preserved between sequential batch invocations.
Therefore, using batch mode often makes more sense in cases where performance
is less critical, such as continuous builds.
</p>
<h4><code class='flag'>--max_idle_secs <var>n</var></code></h4>
<p>
This option specifies how long, in seconds, the Bazel server process
should wait after the last client request, before it exits. The
default value is 10800 (3 hours).
</p>
<p>
This option may be used by scripts that invoke Bazel to ensure that
they do not leave Bazel server processes on a user's machine when they
would not be running otherwise.
For example, an automated script might wish to
invoke <code>bazel query</code> to ensure that a user's pending
change does not introduce unwanted dependencies. However, if the
user has not done a recent build in that workspace, it would be
undesirable for the script to start a Bazel server just
for it to remain idle for the rest of the day.
By specifying a small value of <code class='flag'>--max_idle_secs</code> in the
query request, the script can ensure that <i>if</i> it caused a new
server to start, that server will exit promptly, but if instead
there was already a server running, that server will continue to run
until it has been idle for the usual time. Of course, the existing
server's idle timer will be reset.
</p>
<h4><code class='flag'>--[no]block_for_lock</code></h4>
<p>
If enabled, Bazel will wait for other Bazel commands holding the
server lock to complete before progressing. If disabled, Bazel will
exit in error if it cannot immediately acquire the lock and
proceed.
Developers might use this to avoid long waits caused
by another Bazel command in the same client.
</p>
<h4><code class='flag'>--io_nice_level <var>n</var></code></h4>
<p>
Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority,
7 is lowest. The anticipatory scheduler may only honor up to priority 4.
Negative values are ignored.
</p>
<h4><code class='flag'>--batch_cpu_scheduling</code></h4>
<p>
Use <code>batch</code> CPU scheduling for Bazel. This policy is useful for
workloads that are non-interactive, but do not want to lower their nice value.
See 'man 2 sched_setscheduler'. This policy may provide for better system
interactivity at the expense of Bazel throughput.
</p>
<h3 id='misc_options'>Miscellaneous options</h3>
<h4 id='flag--announce_rc'><code class='flag'>--[no]announce_rc</code></h4>
<p>
Controls whether Bazel announces the options read from the bazelrc file when
starting up.
</p>
<h4><code class='flag'>--color (yes|no|auto)</code></h4>
<p>
This option determines whether Bazel will use colors to highlight
its output on the screen.
</p>
<p>
If this option is set to <code>yes</code>, color output is enabled.
If this option is set to <code>auto</code>, Bazel will use color output only if
the output is being sent to a terminal and the TERM environment variable
is set to a value other than <code>dumb</code>, <code>emacs</code>, or <code>xterm-mono</code>.
If this option is set to <code>no</code>, color output is disabled,
regardless of whether the output is going to a terminal and regardless
of the setting of the TERM environment variable.
</p>
<h4 id='flag--config'><code class='flag'>--config <var>name</var></code></h4>
<p>
Selects additional config sections from the rc files; for the current
<code>command</code>, it also pulls in the options from
<code>command:name</code> if such a section exists. Note that it is currently
only possible to provide these options on the command line, not in the rc
files.
</p>
<h4><code class='flag'>--curses (yes|no|auto)</code></h4>
<p>
This option determines whether Bazel will use cursor controls
in its screen output. This results in less scrolling data, and a more
compact, easy-to-read stream of output from Bazel. This works well with
<code class='flag'>--color</code>.
</p>
<p>
If this option is set to <code>yes</code>, use of cursor controls is enabled.
If this option is set to <code>no</code>, use of cursor controls is disabled.
If this option is set to <code>auto</code>, use of cursor controls will be
enabled under the same conditions as for <code class='flag'>--color=auto</code>.
</p>
<h4><code class='flag'>--logging <var>n</var></code></h4>
<p>
This option controls the level of logging output produced by Bazel.
The default level of logging is 3 (INFO log level); higher numbers mean more
output. The most detailed output is produced at level = 6. A value of 0 turns
logging off.
</p>
<p>
Note, the logging output is highly technical and not intended for
consumption by Bazel users. Instead, we recommend using one
of the following more user-friendly options to control the
diagnostic information printed by Bazel.
</p>
<ul>
<li>For understanding the dependency graph,
use <a href='#query'><code>bazel query</code></a>.
</li>
<li>To see the full command line for commands that failed,
use <a href='#flag--verbose_failures'><code class='flag'>--verbose_failures</code></a>.
</li>
<li>For monitoring all executed commands,
use <a href='#flag--subcommands'><code class='flag'>--subcommands</code></a>.
</li>
<li>To understand why a particular step was rebuilt,
use <a href='#flag--explain'><code class='flag'>--explain</code></a>.
</li>
<li>For profiling a build,
use <a href='#flag--profile'><code class='flag'>--profile</code></a>.
</li>
<li>To disable progress messages,
use <a href='#flag--show_progress'><code class='flag'>--noshow_progress</code></a>.
</li>
<li>To control the display of build result information,
use <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a>.
</li>
<li>To prefix all log messages with a timestamp,
use <a href='#flag--show_timestamps'><code class='flag'>--show_timestamps</code></a>.
</li>
<li>To show where each BUILD file is loaded from,
use <a href='#flag--show_package_location'><code class='flag'>--show_package_location</code></a>.
</li>
</ul>
<h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4>
<p>
If specified, a timestamp is added to each message generated by
Bazel specifying the time at which the message was displayed.
</p>
<h2 id='scripting'>Calling Bazel from scripts</h2>
<p>
Bazel can be called from scripts in order to perform a build, run
tests or query the dependency graph. Bazel has been designed to
enable effective scripting, but this section lists some details to
bear in mind to make your scripts more robust.
</p>
<h3>Choosing the output base</h3>
<p>
The <code class='flag'>--output_base</code> option controls where the Bazel process should
write the outputs of a build to, as well as various working files used
internally by Bazel, one of which is a lock that guards against
concurrent mutation of the output base by multiple Bazel processes.
</p>
<p>
Choosing the correct output base directory for your script depends
on several factors. If you need to put the build outputs in a
specific location, this will dictate the output base you need to
use. If you are making a "read only" call to Bazel
(e.g. <code>bazel query</code>), the locking factors will be more important.
In particular, if you need to run multiple instances of your script
concurrently, you will need to give each one a different (or random) output
base.
</p>
<p>
If you use the default output base value, you will be contending for
the same lock used by the user's interactive Bazel commands. If the
user issues long-running commands such as builds, your script will
have to wait for those commands to complete before it can continue.
</p>
<h3>Server or no server?</h3>
<p>
By default, Bazel uses a long-running <a
href='#client/server'>server process</a> as an optimization; this
behavior can be disabled using the <a
href='#batch'><code class='flag'>--batch</code></a> option. There's no hard and
fast rule about whether or not your script should use a server, but
in general, the trade-off is between performance and reliability.
The server mode makes a sequence of builds, especially incremental
builds, faster, but its behavior is more complex and prone to
failure. We recommend in most cases that you use batch mode unless
the performance advantage is critical.
</p>
<p>
If you do use the server, don't forget to call <code>shutdown</code>
when you're finished with it, or, specify
<code class='flag'>--max_idle_secs=5</code> so that idle servers shut themselves
down promptly.
</p>
<h3>What exit code will I get?</h3>
<p>
Bazel attempts to differentiate failures due to the source code under
consideration from external errors that prevent Bazel from executing properly.
Bazel execution can result in following exit codes:
</p>
<b>Exit Codes common to all commands:</b>
<ul>
<li><code>0</code> - Success</li>
<li><code>2</code> - Command Line Problem, Bad or Illegal flags or command
combination, or Bad Environment Variables. Your command line must be
modified.</li>
<li><code>8</code> - Build Interrupted but we terminated with an orderly shutdown.</li>
<li><code>33</code> - OOM failure. You need to modify your command line.</li>
<li><code>36</code> - Local Environmental Issue, suspected permanent.</li>
<li><code>37</code> - Unhandled Exception / Internal Bazel Error.</li>
<li><code>40-44</code> - Reserved for errors in Bazel's command line launcher,
<code>bazel.cc</code> that are not command line
related. Typically these are related to Bazel server
being unable to launch itself.</li>
</ul>
<b>Return codes for commands <code>bazel build</code>, <code>bazel test</code>.</b>
<ul>
<li><code>1</code> - Build failed.</li>
<li><code>3</code> - Build OK, but some tests failed or timed out.</li>
<li><code>4</code> - Build successful but no tests were found even though
testing was requested.</li>
</ul>
<b>For <code>bazel run</code>:</b>
<ul>
<li><code>1</code> - Build failed.</li>
<li><code>6</code> - Run command failure. The executed subprocess returned a
non-zero exit code. The actual subprocess exit code is
given in stderr.</li>
</ul>
<b>For <code>bazel query</code>:</b>
<ul>
<li><code>3</code> - Partial success, but the query encountered 1 or more
errors in the input BUILD file set and therefore the
results of the operation are not 100% reliable.
This is likely due to a <code class='flag'>--keep_going</code> option
on the command line.
<li><code>7</code> - Analyze or Query command failure.</li>
</ul>
<p>
Future Bazel versions may add additional exit codes, replacing generic failure
exit code <code>1</code> with a different non-zero value with a particular
meaning. However, all non-zero exit values will always constitute an error.
</p>
<h3>Reading the .bazelrc file</h3>
<p>
By default, Bazel will read the <a
href='#bazelrc'><code>.bazelrc</code> file</a> from the workspace
directory or the user's home directory. Whether or not this is
desirable is a choice for your script; if your script needs to be
perfectly hermetic (e.g. when doing release builds), you should
disable reading the .bazelrc file by using the option
<code class='flag'>--bazelrc=/dev/null</code>. If you want to perform a build
using the user's preferred settings, the default behavior is better.
</p>
<h3 id='master_log'>Using the Bazel master log</h3>
<p>
On each build, test, analyze, or coverage command, Bazel will
write a readily-parseable summary log. The output is in the form of
a line-based grammar, familiar to standard unix tools (grep, sed,
sort, awk, etc.).
</p>
<p>
The master log contains information on the result of each target
and test. You'll be able to determine, for instance, if a given target
passed the loading phase, but not the analysis phase. We also
provide references to test log files and test time information.
You can find the master log file with the following command:
</p>
<pre>
% bazel info master-log
</pre>
<p>
Say you were interested in seeing the three longest-running tests
in your most recent test command. Here's how you could do it:
</p>
<pre>
% grep '^test ' $(bazel info master-log 2&gt;/dev/null) | awk '{print $5,$2}' | sort -nr | head -n 3
2404 //foo:foo_test
713 //bar:bar_test
624 //baz:baz_test
</pre>
<h4>Master log format</h4>
<p>
Line ordering is generally unspecified (exceptions are handled on a
case-by-case basis), but the file will contain the following contents:
</p>
<ul>
<li>
<code>startup_options</code><br/>
The line contains a properly quoted representation of the startup options
used to start Bazel, including <code>.bazelrc</code> options.
</li>
<li>
<code>cmd_line</code><br/>
The line contains a properly quoted representation of the user's command
line arguments. This includes <code>.bazelrc</code> options, but not the
startup options, command, or target patterns specified on the command line.
</li>
<li>
<code>build_id <var>uuid</var></code><br/>
<var>uuid</var> is a string uniquely identifying this build.
The identifier is guaranteed to be unique across any other Bazel build,
even those of other users.
</li>
<li>
<code>version_num <var>number</var></code><br/>
<var>number</var> is the version number of the master log.
Incompatible changes may be made to the master log
only if <var>number</var> is increased.
</li>
<li>
<code>pattern <var>pattern</var> ...</code><br/>
A single line with a space-separated list of target patterns as they
appeared on the command line. e.g., for <code>bazel build foo //bar:*</code>,
the line would read: <code>pattern foo //bar:*</code>.
</li>
<li>
<code>command <var>command_name</var></code><br/>
<var>command_name</var> is the name of the command executed by Bazel. (e.g., build or test).
</li>
<li>
<code>bazel_version <var>version string</var></code><br/>
<var>version string</var> is a human readable version descriptor indicating the Bazel version
used for the build.
</li>
<li>
<code>log_starting <var>log_name</var> <var>log_path</var></code><br/>
<var>log_name</var> is the name of the log being started.<br/>
<var>log_path</var> is the absolute path to the log file.
</li>
<li>
<code>start_time <var>time</var></code><br/>
<var>time</var> is the start time of the build, in milliseconds since
midnight, January 1, 1970 UTC.
</li>
<li>
<code>stop_time <var>time</var></code><br/>
<var>time</var> is the end time of the build, in milliseconds since
midnight, January 1, 1970 UTC.
</li>
<li>
<code>output_fs <var>filesystem_type</var></code><br/>
<var>filesystem_type</var> is the type of the filesystem that contains the Bazel output
directory (does not contain spaces).
</li>
<li>
<code>runs_per_test <var>runs</var></code><br/>
<var>runs</var> is the number of test runs Bazel is configured to perform on
each test target.
</li>
<li>
<code>working_directory <var>cwd</var></code><br/>
<var>cwd</var> is the working directory from which Bazel was invoked.
</li>
<li>
<code>symlink_prefix <var>string</var></code><br/>
<var>string</var> is the value of the <code class='flag'>--symlink_prefix</code> flag.
See <a href="#flag--symlink_prefix"><code class='flag'>--symlink_prefix</code></a>.
</li>
<li>
<code>target <var>label</var> <var>kind</var></code><br/>
One line for each target the that was parsed from the command line.
e.g.,
<pre>
target //foo:foo java_library rule
target //bar:t1 source file
target //bar:t2 generated file
</pre>
If a <code>test_suite</code> target is specified in the pattern, just one
<code>target</code> line will appear for it, but no <code>target</code> lines
will appear for the test targets it expands to. If the test targets build
successfully, you can use the
<code>test_target</code> lines to determine target language.
</li>
<li>
<code>test_target <var>label</var> <var>kind</var> <var>shards</var></code>
<br/><var>label</var> is the label identifying the target.
<br/><var>kind</var> is the type of rule the target tests as (e.g. java_test).
<br/><var>shards</var> is the number of shards the test is configured to use.
<p>One line for each test target that Bazel will attempt to execute.
These targets have been successfully loaded, analyzed, and have not been
filtered via <a href='#flag--test_size_filters'>size</a>,
<a href='#flag--test_timeout_filters'>timeout</a>,
<a href='#flag--test_tag_filters'>tag</a>, or
<a href='#flag--test_lang_filters'>language</a>. Note that these tests may not
be executed if the execution phase is not entered, is interrupted, or fails.
These lines will appear before any <code>status</code>,
<code>test</code>, <code>test_status</code> lines.
If a <code>test_suite</code> target is specified in the pattern, a
<code>test_target</code> line will appear for each test target it expands to.
</p>
</li>
<li>
<code>make_var <var>key</var> <var>value</var></code><br/>
One line with a key value pair for each
<a href="build-encyclopedia.html#make_variables">make variable</a>.
<p>Available make variables may be displayed with:</p>
<pre>
bazel info --show_make_env
</pre>
</li>
<li id="status_line">
<code>
<a name="status">status</a> <var>label</var> <var>result</var>
<var>time</var> <var>cached</var>
</code>
<br/>
<var>label</var> is the name of the target for which status is reported.<br/>
<var>result</var> is the status of the target; see below for values.<br/>
<var>time</var> is the time of target completion, in milliseconds since
midnight, January 1, 1970 UTC.
<var>cached</var> is "cached" only if the entire target is cached;
i.e. all artifacts required to run the target were cached from a previous
build <em>of the same target</em>. Otherwise, it is "not_cached".
<p>
One status line for each <code>target</code> line. In the
<code class='flag'>--keep_going</code> case, different targets may reach
different phases (e.g. loading vs. analysis) before failing.
However, in the default case, all <var>result</var> values will be
identical, because the build stops as soon as the first error is
encountered. This line strictly reports build statuses; for test status
reporting, see <a href="#test_status"><code>test_status</code></a>.
</p>
<p>
<var>result</var> may be one of:
</p>
<ul>
<li><code>parsing-failed</code>: the target could not be parsed (due to the
architecture of Bazel, this is sometimes also emitted when the target
simply does not exist). Also see
<a href="#parsing_failed">parsing_failed</a></li>
<li><code>target-filtered</code>: the target got filtered out by a negative
target specifier that came later in the command line.</li>
<li><code>loading-failed</code>: the target contained
a <a href='#loading-phase'>loading phase</a> error.</li>
<li><code>analysis-failed</code>: the target contained
an <a href='#analysis-phase'>analysis phase</a> error.</li>
<li><code>test-filtered</code>: the target was loaded and analyzed
successfully, but was not built or run because it did not match the
current
<a href='#flag--test_size_filters'>size</a>,
<a href='#flag--test_timeout_filters'>timeout</a>,
<a href='#flag--test_tag_filters'>tag</a>, or
<a href='#flag--test_lang_filters'>language</a> test
filter settings.</li>
<li><code>not-built</code>: the target was loaded and analyzed successfully,
but was not built or run because Bazel did not perform the
<a href="#execution-phase">execution phase</a>;
e.g. if the <a href="#nobuild">--nobuild</a> flag was specified.</li>
<li><code>build-failed</code>: the target could not be built
because of an error during
the <a href='#execution-phase'>execution phase</a>.</li>
<li><code>built</code>: the target was built successfully.</li>
</ul>
These lines are not guaranteed to be printed in the case of a Bazel crash.
</li>
<li>
<code>action_executed <var>target</var> <var>type</var> <var>outcome</var>
<var>stdout</var> <var>stderr</var> <var>primary_input</var>
<var>primary_output</var></code><br/>
One such line is generated for every action with stdout/stderr that Bazel executed.<br/>
<var>target</var>: The target the action was associated with, or
<code>&lt;none&gt;</code> if the action does not belong to any target.<br/>
<var>type</var>: The type of the action. This is intended to be a clue as to
how the output of the action should be parsed. It does not precisely
determine the compiler that was executed;
<var>outcome</var>: <code>success</code> or <code>failure</code> depending
on whether the action succeeded or failed.<br/>
<var>stdout</var>: the file containing the standard output of the action.
<code>/dev/null</code> if the action did not write anything there.<br/>
<var>stderr</var>: the file containing the standard error of the action.
<code>/dev/null</code> if the action did not write anything there.<br/>
<var>primary_input</var>: the "primary" input artifact processed by this
action.
<code>null</code> if the action has no input artifacts.<br/>
<var>primary_output</var>: the "primary" output artifact processed by this
action.
<code>null</code> if the action has no output artifacts.<br/>
</li>
<li>
<code>
<a name="root_cause">root_cause</a> <var>target</var> <var>cause</var>
</code>
<br/>
When a target is not built, and Bazel has information about the reason,
a <code>root_cause</code> line is added. Such a line means that the
reason why <var>target</var> could not be built is that there was a
problem with building one of its dependencies, <var>cause</var>. Note
that there can be multiple <code>root_cause</code> lines for a single
target when that target has multiple faulty dependencies which do not
depend on each other. Also note that a target can be its own root cause.
Root cause lines are most meaningful in the presence of --keep_going; in
builds lacking -k, only the first failing target will report root causes
(and because actions are executed in parallel, which target fails first is
not deterministic).
</li>
<li>
<code>bazel_crashed <var>description</var></code><br/>
This line is included if the build crashed unexpectedly. This could happen,
for example, in the case of an <code>OutOfMemoryError</code>.
</li>
<li>
<code>bazel_catastrophe</code><br/>
This line is included if there is a severe enough failure such that Bazel halts the build before
completion, even if <code>keep_going</code> is set. One example of this is unexpected IO failure
when writing to local disk, whether due to physical failure or filesystem corruption.
</li>
<li id="parsing_failed">
<code>parsing_failed <var>pattern</var> &ldquo;<var>description</var>&rdquo;
</code><br/>
In the event that a user-supplied target pattern cannot be parsed, this line
will be emitted with the failing target pattern and a description of the error
(surrounded by double quotes). Certain error types (those which occur after
targets are parsed from the pattern) will emit corresponding
<a href="#status_line">status //target parsing-failed</a> lines; others will
not. If multiple target patterns are specified on the command
line, one parsing_failed line will be emitted for each failing pattern.
</li>
<li>
<code>output_file <var>label</var> <var>path</var> <var>tags</var></code><br/>
One output file line for each non-input file built for each
successfully built target. The <var>tags</var>
value is a comma separated and terminated sequence of strings.
Currently, the only possible value is <code>executable</code>, which is
printed if and only if the file is the target's executable
output. Each target may have at most one executable.
</li>
<li id="test_line">
<code>test <var>label</var>
<var>shard_num</var>/<var>total_shards</var> <var>result</var> <var>time</var>
<var>log_file</var></code><br/>
One test line for <em>each run of each shard</em> of a successfully-built
test target. For the aggregate status of the entire target, see
<a href="#test_status"><code>test_status</code></a>.
<p>Multiple runs and flaky attempts will appear on different lines.
Targets which failed to build or were filtered out due to language
or tags will appear as soon as the failure or filtering occurs.</p>
<var>shard_num</var>: The zero-based shard index, or zero if
sharding is disabled.<br/>
<var>total_shards</var>: The total number of shards, or zero if
sharding is disabled.<br/>
<var>result</var>: One of <code>no_status</code>, <code>passed</code>,
<code>failed</code>, <code>timeout</code> or <code>flaky</code>.<br/>
<var>time</var>: The duration of test execution in milliseconds,
or -1 if the test was not executed because of caching.<br/>
<var>log_file</var>: The absolute path to the test log file.
</li>
<li>
<code>test <var>label</var> failed_to_build</code> (deprecated) <br/>
One test failed_to_build line for each test target that failed to build.
</li>
<li id="test_status"> <code>test_status <var>label</var>
<var>result</var></code>
<p>
Reports the final testing status of each test <em>target</em> as soon as it
becomes available.
For individual shard and run results, refer to
<a href="#test_line"><code>test</code></a>. The status codes roughly
mirror the status lines output to the console. Possible status codes are:
</p>
<ul>
<li><code>passed</code>: the target passed testing.</li>
<li><code>failed</code>: the target failed in testing.</li>
<li><code>timeout</code>: the target timed out in testing.</li>
<li><code>flaky</code>: the target produced flaky results in testing.</li>
<li><code>incomplete</code>: the target began testing but never completed,
most likely due to an interrupt.</li>
<li><code>failed-to-build</code>: the target couldn't be tested because it
failed to build.</li>
<li><code>no-status</code>: the target was scheduled to be tested but
testing was never actually performed on it, most likely due to an interrupt
or failure while building an earlier target.
</li>
</ul>
</li>
<li>
<code>baseline_coverage <var>label</var> <var>filename</var></code><br/>
Reference to the baseline LCOV-based coverage file produced for the given label.
</li>
<li>
<code>build_interrupted</code><br/>
This line is included if the build was interrupted by the user via SIGINT.
This only applies to server mode. In batch mode, the master build log
will be truncated before this line would be emitted.
</li>
<li>
<code>eof</code><br/>
This line is guaranteed to be the last non-whitespace line in the file.
</li>
</ul>
<h3>Command log</h3>
<p>
The Bazel output is also available in a command log file which you can
find with the following command:
</p>
<pre>
% bazel info command_log
</pre>
<p>
The command log file contains the interleaved stdout and stderr streams
of the most recent Bazel command. Note that running <code>bazel info</code>
will overwrite the contents of this file, since it then becomes the most
recent Bazel command. However, the location of the command log file will
not change unless you change the setting of the <code class='flag'>--output_base</code>
or <code class='flag'>--output_user_root</code> options.
</p>
<h3>Parsing output</h3>
<p>
The Bazel output is quite easy to parse for many purposes. Two
options that may be helpful for your script are
<code class='flag'>--noshow_progress</code> which suppresses progress messages,
and <code class='flag'>--show_result <var>n</var></code>, which controls whether
or not "build up-to-date" messages are printed; these messages may
be parsed to discover which targets were successfully built, and the
location of the output files they created. Be sure to specify a
very large value of <i>n</i> if you rely on these messages.
</p>
<p>
Note that it often makes sense to use the
<a href='#master_log'>master log</a> instead of parsing Bazel output
directly.
</p>
</body>
</html>