Google Git
Sign in
bazel / bazel / cb6e5c24b82e0e20a243145fb6ea32b09e3d1de3 / . / site / docs / user-manual.html
blob: d98598de0fb425f58c3502e0de2ece430cab65fe [file] [log] [blame]
---
layout: documentation
title: User manual
---
<h1>Commands and options</h1>
<h2 id='target-patterns'>Target syntax</h2>
Some commands, like <code>build</code> or <code>test</code>, can operate
on a list of targets. They use a syntax more flexible than labels, which is
documented in the "<a href="guide.html#specifying-targets-to-build">Specifying
targets to build</a>" section of the User's Guide.
<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>Package location</h3>
<h4 id='flag--package_path'><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.
</p>
<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='guide.html#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
% touch WORKSPACE
% bazel build --package_path /some/other/path //foo
</pre>
<h3 id='checking-options'>Error checking</h3>
<p>
These options control Bazel's error-checking and/or warnings.
</p>
<h4 id='flag--check_constraint'><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_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.
</p>
<p>
Here are some typical values for this option:
</p>
<table>
<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='^//((?!(first/bad_project|second/bad_project):).)*$'</code></td>
<td>Don't show output for the specified packages.</td>
</tr>
<tr>
<td><code class='flag'>--output_filter=</code></td>
<td>Show everything.
</td>
</tr>
<tr>
<td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td>
<td>Show nothing.
</td>
</tr>
</table>
<h3 id='flags-options'>Tool flags</h3>
<p>
These options control which options Bazel will pass to other tools.
</p>
<h4 id='flag--copt'><code class='flag'>--copt <var>cc-option</var></code></h4>
<p>
This option takes an argument which is to be passed to the compiler.
The argument will be passed to the compiler whenever it is invoked
for preprocessing, compiling, and/or assembling C, C++, or
assembler code. It will not be passed when linking.
</p>
<p>
This option can be used multiple times.
For example:
</p>
<pre>
% bazel build --copt="-g0" --copt="-fpic" //foo
</pre>
<p>
will compile the <code>foo</code> library without debug tables, generating
position-independent code.
</p>
<p>
Note that changing <code class='flag'>--copt</code> settings will force a recompilation
of all affected object files. Also note that copts values listed in specific
cc_library or cc_binary build rules will be placed on the compiler command line
<em>after</em> these options.
</p>
<p>
Warning: C++-specific options (such as <code>-fno-implicit-templates</code>)
should be specified in <code class='flag'>--cxxopt</code>, not in
<code class='flag'>--copt</code>. Likewise, C-specific options (such as -Wstrict-prototypes)
should be specified in <code class='flag'>--conlyopt</code>, not in <code>copt</code>.
Similarly, compiler options that only have an
effect at link time (such as <code>-l</code>) should be specified in
<code class='flag'>--linkopt</code>, not in <code class='flag'>--copt</code>.
</p>
<h4 id='flag--host_copt'><code class='flag'>--host_copt <var>cc-option</var></code></h4>
<p>
This option takes an argument which is to be passed to the compiler for source files
that are compiled in the host configuration. This is analogous to
the <a href='#flag--copt'><code class='flag'>--copt</code></a> option, but applies only to the
host configuration.
</p>
<h4 id='flag--host_cxxopt'><code class='flag'>--host_cxxopt <var>cc-option</var></code></h4>
<p>
This option takes an argument which is to be passed to the compiler for C++ source files
that are compiled in the host configuration. This is analogous to
the <a href='#flag--cxxopt'><code class='flag'>--cxxopt</code></a> option, but applies only to the
host configuration.
</p>
<h4 id='flag--conlyopt'><code class='flag'>--conlyopt <var>cc-option</var></code></h4>
<p>
This option takes an argument which is to be passed to the compiler when compiling C source files.
</p>
<p>
This is similar to <code class='flag'>--copt</code>, but only applies to C compilation,
not to C++ compilation or linking. So you can pass C-specific options
(such as <code>-Wno-pointer-sign</code>) using <code class='flag'>--conlyopt</code>.
</p>
<p>
Note that copts parameters listed in specific cc_library or cc_binary build rules
will be placed on the compiler command line <em>after</em> these options.
</p>
<h4 id='flag--cxxopt'><code class='flag'>--cxxopt <var>cc-option</var></code></h4>
<p>
This option takes an argument which is to be passed to the compiler when compiling C++ source
files.
</p>
<p>
This is similar to <code class='flag'>--copt</code>, but only applies to C++ compilation,
not to C compilation or linking. So you can pass C++-specific options
(such as <code>-fpermissive</code> or <code>-fno-implicit-templates</code>) using <code class='flag'>--cxxopt</code>.
For example:
</p>
<pre>
% bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code
</pre>
<p>
Note that copts parameters listed in specific cc_library or cc_binary build rules
will be placed on the compiler command line <em>after</em> these options.
</p>
<h4 id='flag--linkopt'><code class='flag'>--linkopt <var>linker-option</var></code></h4>
<p>
This option takes an argument which is to be passed to the compiler when linking.
</p>
<p>
This is similar to <code class='flag'>--copt</code>, but only applies to linking,
not to compilation. So you can pass compiler options that only make sense
at link time (such as <code>-lssp</code> or <code>-Wl,--wrap,abort</code>)
using <code class='flag'>--linkopt</code>. For example:
</p>
<pre>
% bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code
</pre>
<p>
Build rules can also specify link options in their attributes. This option's
settings always take precedence. Also see
<a href="be/c-cpp.html#cc_library.linkopts">cc_library.linkopts</a>.
</p>
<h4 id='flag--strip'><code class='flag'>--strip (always|never|sometimes)</code></h4>
<p>
This option determines whether Bazel will strip debugging information from
all binaries and shared libraries, by invoking the linker with the <code>-Wl,--strip-debug</code> option.
<code class='flag'>--strip=always</code> means always strip debugging information.
<code class='flag'>--strip=never</code> means never strip debugging information.
The default value of <code class='flag'>--strip=sometimes</code> means strip if the <code class='flag'>--compilation_mode</code>
is <code>fastbuild</code>.
</p>
<pre>
% bazel build --strip=always //foo:bar
</pre>
<p>
will compile the target while stripping debugging information from all generated
binaries.
</p>
<p>
Note that if you want debugging information, it's not enough to disable stripping; you also need to make
sure that the debugging information was generated by the compiler, which you can do by using either
<code>-c dbg</code> or <code class='flag'>--copt -g</code>.
</p>
<p>
Note also that Bazel's <code class='flag'>--strip</code> option corresponds with ld's <code>--strip-debug</code> option:
it only strips debugging information. If for some reason you want to strip <em>all</em> symbols,
not just <em>debug</em> symbols, you would need to use ld's <code>--strip-all</code> option,
which you can do by passing <code class='flag'>--linkopt=-Wl,--strip-all</code> to Bazel. Also be
aware that setting Bazel's <code class='flag'>--strip</code> flag will override
<code class='flag'>--linkopt=-Wl,--strip-all</code>, so you should only set one or the other.
</p>
<h4 id='flag--stripopt'><code class='flag'>--stripopt <var>strip-option</var></code></h4>
<p>
An additional option to pass to the <code>strip</code> command when generating
a <a href="be/c-cpp.html#cc_binary_implicit_outputs"><code>*.stripped</code>
binary</a>. The default is <code>-S -p</code>. This option can be used
multiple times.
</p>
<p>
Note that <code class='flag'>--stripopt</code> does not apply to the stripping of the main
binary with <code><a href='#flag--strip'>--strip</a>=(always|sometimes)</code>.
</p>
<h4 id='flag--fdo_instrument'><code class='flag'>--fdo_instrument <var>profile-output-dir</var></code></h4>
<p>
The <code class='flag'>--fdo_instrument</code> option enables the generation of
FDO (feedback directed optimization) profile output when the
built C/C++ binary is executed. For GCC, the argument provided is used as a
directory prefix for a per-object file directory tree of .gcda files
containing profile information for each .o file.
</p>
<p>
Once the profile data tree has been generated, the profile tree
should be zipped up, and provided to the
<code class='flag'>--fdo_optimize=<var>profile-zip</var></code>
Bazel option to enable the FDO-optimized compilation.
</p>
<p>
For the LLVM compiler the argument is also the directory under which the raw LLVM profile
data file(s) is dumped, e.g.
<code class='flag'>--fdo_instrument=<var>/path/to/rawprof/dir/</var></code>.
</p>
<p>
The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>--fdo_optimize</code>
cannot be used at the same time.
</p>
<h4 id='flag--fdo_optimize'><code class='flag'>--fdo_optimize <var>profile-zip</var></code></h4>
<p>
The <code class='flag'>--fdo_optimize</code> option enables the use of the
per-object file profile information to perform FDO (feedback
directed optimization) optimizations when compiling. For GCC, the argument
provided is the zip file containing the previously-generated file tree
of .gcda files containing profile information for each .o file.
</p>
<p>
Alternatively, the argument provided can point to an auto profile
identified by the extension .afdo.
</p>
<p>
Note that this option also accepts labels that resolve to source files. You
may need to add an <code>exports_files</code> directive to the corresponding package to
make the file visible to Bazel.
</p>
<p>
For the LLVM compiler the argument provided should point to the indexed LLVM
profile output file prepared by the llvm-profdata tool, and should have a .profdata
extension.
</p>
<p>
The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>
--fdo_optimize</code> cannot be used at the same time.
</p>
<h4 id='flag--output_symbol_counts'><code class='flag'>--[no]output_symbol_counts</code></h4>
<p>
If enabled, each gold-invoked link of a C++ executable binary will output
a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold
option). For each linker input, the file logs the number of symbols that were
defined and the number of symbols that were used in the binary.
This information can be used to track unnecessary link dependencies.
The symbol counts file is written to the binary's output path with the name
<code>[targetname].sc</code>.
</p>
<p>
This option is disabled by default.
</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/example/common/foo: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>
-source 8 -target 8 -encoding UTF-8
</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='-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>
<h3 id='semantics-options'>Build semantics</h3>
<p>
These options affect the build commands and/or the output file contents.
</p>
<h4 id='flag--compilation_mode'><code class='flag'>--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4>
<p>
The <code class="flag">--compilation_mode</code> option (often shortened to <code>-c</code>,
especially <code>-c opt</code>) takes an argument of <code>fastbuild</code>, <code>dbg</code>
or <code>opt</code>, and affects various C/C++ code-generation
options, such as the level of optimization and the completeness of
debug tables. Bazel uses a different output directory for each
different compilation mode, so you can switch between modes without
needing to do a full rebuild <i>every</i> time.
</p>
<ul>
<li> <code>fastbuild</code> means build as fast as possible:
generate minimal debugging information (<code>-gmlt
-Wl,-S</code>), and don't optimize. This is the
default. Note: <code>-DNDEBUG</code> will <b>not</b> be set.
</li>
<li> <code>dbg</code> means build with debugging enabled (<code>-g</code>),
so that you can use gdb (or another debugger).
</li>
<li> <code>opt</code> means build with optimization enabled and
with <code>assert()</code> calls disabled (<code>-O2 -DNDEBUG</code>).
Debugging information will not be generated in <code>opt</code> mode
unless you also pass <code class='flag'>--copt -g</code>.
</li>
</ul>
<h4 id='flag--cpu'><code class='flag'>--cpu <var>cpu</var></code></h4>
<p>
This option specifies the target CPU architecture to be used for
the compilation of binaries during the build.
</p>
<p>
</p>
<p>
Note that a particular combination of crosstool version, compiler version,
and target CPU is allowed only if it has been specified in the currently
used CROSSTOOL file.
</p>
<h4 id='flag--action_env'>
<code class='flag'>--action_env=<var>VAR=VALUE</var></code>
</h4>
<p>
Specifies the set of environment variables available during the execution of all actions.
Variables can be either specified by name, in which case the value will be taken from the
invocation environment, or by the `name=value` pair which sets the value independent of the
invocation environment.
This `--action_env` flag can be specified multiple times. If a value is assigned to the same
variable across multiple `--action_env` flags, the latest assignment wins.
</p>
<h4 id='flag--experimental_action_listener'>
<code class='flag'>--experimental_action_listener=<var>label</var></code>
</h4>
<p>
The <code>experimental_action_listener</code> option instructs Bazel to use
details from the <a href="be/extra-actions.html#action_listener"
><code>action_listener</code></a> rule specified by <var>label</var> to
insert <a href="be/extra-actions.html#extra_action"
><code>extra_actions</code></a> into the build graph.
</p>
<h4 id='flag--experimental_extra_action_top_level_only'>
<code class='flag'>--[no]experimental_extra_action_top_level_only</code>
</h4>
<p>
If this option is set to true, extra actions specified by the
<a href='#flag--experimental_action_listener'> <code>
--experimental_action_listener</code></a> command line option will only be
scheduled for top level targets.
</p>
<h4 id='flag--experimental_extra_action_filter'>
<code class='flag'>--experimental_extra_action_filter=<var>regex</var></code>
</h4>
<p>
The <code>experimental_extra_action_filter</code> option instructs Bazel to
filter the set of targets to schedule <code>extra_actions</code> for.
</p>
<p>
This flag is only applicable in combination with the
<a href='#flag--experimental_action_listener'
><code>--experimental_action_listener</code></a> flag.
</p>
<p>
By default all <code>extra_actions</code> in the transitive closure of the
requested targets-to-build get scheduled for execution.
<code>--experimental_extra_action_filter</code> will restrict scheduling to
<code>extra_actions</code> of which the owner's label matches the specified
regular expression.
</p>
<p>
The following example will limit scheduling of <code>extra_actions</code>
to only apply to actions of which the owner's label contains '/bar/':
</p>
<pre>% bazel build --experimental_action_listener=//test:al //foo/... \
--experimental_extra_action_filter=.*/bar/.*
</pre>
<h4 id='flag--host_cpu'><code class='flag'>--host_cpu <var>cpu</var></code></h4>
<p>
This option specifies the name of the CPU architecture that should be
used to build host tools.
</p>
<h4 id='flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu <var>cpu[,cpu]*</var></code></h4>
<p>
The CPUs to build C/C++ libraries for in the transitive <code>deps</code> of
<code>android_binary</code>
rules. Other C/C++ rules are not affected. For example, if a <code>cc_library</code>
appears in the transitive <code>deps</code> of an <code>android_binary</code> rule and a
<code>cc_binary</code> rule, the <code>cc_library</code> will be built at least twice:
once for each CPU specified with <code class='flag'>--fat_apk_cpu</code> for the
<code>android_binary</code> rule, and once for the CPU specified with
<code class='flag'>--cpu</code> for the <code>cc_binary</code> rule.
<p>
The default is <code>armeabi-v7a</code>.
</p>
<p>
One <code>.so</code> file will be created and packaged in the APK for
each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The name of the <code>.so</code>
file will be the name of the <code>android_binary</code> rule prefixed with "lib", e.g., if the name
of the <code>android_binary</code> is "foo", then the file will be <code>libfoo.so</code>.
</p>
<p>
Note that an Android-compatible crosstool must be selected.
If an <code>android_ndk_repository</code> rule is defined in the
WORKSPACE file, an Android-compatible crosstool is automatically selected.
Otherwise, the crostool can be selected using the
<a href='#flag--android_crosstool_top'><code class='flag'>--android_crosstool_top</code></a>
or <a href='#flag--crosstool_top'><code class='flag'>--crosstool_top</code></a> flags.
</p>
</p>
<h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt
<var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4>
<p>
When present, any C++ file with a label or an execution path matching one of the inclusion regex
expressions and not matching any of the exclusion expressions will be built
with the given options. The label matching uses the canonical form of the label
(i.e //<code>package</code>:<code>label_name</code>).
The execution path is the relative path to your workspace directory including the base name
(including extension) of the C++ file. It also includes any platform dependent prefixes.
Note, that if only one of the label or the execution path matches the options will be used.
</p>
<p>
<b>Notes</b>:
To match the generated files (e.g. genrule outputs)
Bazel can only use the execution path. In this case the regexp shouldn't start with '//'
since that doesn't match any execution paths. Package names can be used like this:
<code class='flag'>--per_file_copt=base/.*\.pb\.cc@-g0</code>. This will match every
<code>.pb.cc</code> file under a directory called <code>base</code>.
</p>
<p>
This option can be used multiple times.
</p>
<p>
The option is applied regardless of the compilation mode used. I.e. it is possible
to compile with <code class='flag'>--compilation_mode=opt</code> and selectively compile some
files with stronger optimization turned on, or with optimization disabled.
</p>
<p>
<b>Caveat</b>: If some files are selectively compiled with debug symbols the symbols
might be stripped during linking. This can be prevented by setting
<code class='flag'>--strip=never</code>.
</p>
<p>
<b>Syntax</b>: <code>[+-]regex[,[+-]regex]...@option[,option]...</code> Where
<code>regex</code> stands for a regular expression that can be prefixed with
a <code>+</code> to identify include patterns and with <code>-</code> to identify
exclude patterns. <code>option</code> stands for an arbitrary option that is passed
to the C++ compiler. If an option contains a <code>,</code> it has to be quoted like so
<code>\,</code>. Options can also contain <code>@</code>, since only the first
<code>@</code> is used to separate regular expressions from options.
</p>
<p>
<b>Example</b>:
<code class='flag'>--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs</code>
adds the <code>-O0</code> and the <code>-fprofile-arcs</code> options to the command
line of the C++ compiler for all <code>.cc</code> files in <code>//foo/</code> except
<code>file.cc</code>.
</p>
<h4 id='flag--dynamic_mode'><code class='flag'>--dynamic_mode <var>mode</var></code></h4>
<p>
Determines whether C++ binaries will be linked dynamically, interacting with
the <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic
attribute</a> on build rules.
</p>
<p>
Modes:
</p>
<ul>
<li><code>auto</code>: Translates to a platform-dependent mode;
<code>default</code> for linux and <code>off</code> for cygwin.</li>
<li><code>default</code>: Allows bazel to choose whether to link dynamically.
See <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic</a> for more
information.</li>
<li><code>fully</code>: Links all targets dynamically. This will speed up
linking time, and reduce the size of the resulting binaries.
</li>
<li><code>off</code>: Links all targets in
<a href='be/c-cpp.html#cc_binary.linkstatic'>mostly static</a> mode.
If <code>-static</code> is set in linkopts, targets will change to fully
static.</li>
</ul>
<h4 id='flag--fission'><code class='flag'>--fission (yes|no|[dbg][,opt][,fastbuild])</code></h4>
<p>
Enables
<a href='https://gcc.gnu.org/wiki/DebugFission'>Fission</a>,
which writes C++ debug information to dedicated .dwo files instead of .o files, where it would
otherwise go. This substantially reduces the input size to links and can reduce link times.
</p>
<p>
When set to <code class='flag'>[dbg][,opt][,fastbuild]</code> (example:
<code class='flag'>--fission=dbg,fastbuild</code>), Fission is enabled
only for the specified set of compilation modes. This is useful for bazelrc
settings. When set to <code class='flag'>yes</code>, Fission is enabled
universally. When set to <code class='flag'>no</code>, Fission is disabled
universally. Default is <code class='flag'>dbg</code>.
</p>
<h4 id='flag--force_ignore_dash_static'><code class='flag'>--force_ignore_dash_static</code></h4>
<p>
If this flag is set, any <code>-static</code> options in linkopts of
<code>cc_*</code> rules BUILD files are ignored. This is only intended as a
workaround for C++ hardening builds.
</p>
<h4 id='flag--force_pic'><code class='flag'>--[no]force_pic</code></h4>
<p>
If enabled, all C++ compilations produce position-independent code ("-fPIC"),
links prefer PIC pre-built libraries over non-PIC libraries, and links produce
position-independent executables ("-pie"). Default is disabled.
</p>
<p>
Note that dynamically linked binaries (i.e. <code>--dynamic_mode fully</code>)
generate PIC code regardless of this flag's setting. So this flag is for cases
where users want PIC code explicitly generated for static links.
</p>
<h4 id='flag--android_resource_shrinking'><code class='flag'>--android_resource_shrinking</code></h4>
<p>
Selects whether to perform resource shrinking for android_binary rules. Sets the default for the
<a href='be/android.html#android_binary.shrink_resources'>shrink_resources attribute</a> on
android_binary rules; see the documentation for that rule for further details. Defaults to off.
</p>
<h4 id='flag--custom_malloc'><code class='flag'>--custom_malloc <var>malloc-library-target</var></code></h4>
<p>
When specified, always use the given malloc implementation, overriding all
<code>malloc="target"</code> attributes, including in those targets that use the
default (by not specifying any <code>malloc</code>).
</p>
<h4 id='flag--crosstool_top'><code class='flag'>--crosstool_top <var>label</var></code></h4>
<p>
This option specifies the location of the crosstool compiler suite
to be used for all C++ compilation during a build. Bazel will look in that
location for a CROSSTOOL file and uses that to automatically determine
settings for
<code class='flag'>--compiler</code>.
</p>
<h4 id='flag--host_crosstool_top'><code class='flag'>--host_crosstool_top <var>label</var></code></h4>
<p>
If not specified, bazel uses the value of <code class='flag'>--crosstool_top</code> to compile
code in the host configuration, i.e., tools run during the build. The main purpose of this flag
is to enable cross-compilation.
</p>
<h4 id='flag--apple_crosstool_top'><code class='flag'>--apple_crosstool_top <var>label</var></code></h4>
<p>
The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites
<code class='flag'>--crosstool_top</code>.
</p>
<h4 id='flag--android_crosstool_top'><code class='flag'>--android_crosstool_top <var>label</var></code></h4>
<p>
The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
<code>android_binary</code> rules. This is useful if other targets in the
build require a different crosstool. The default is to use the crosstool
generated by the <code>android_ndk_repository</code> rule in the WORKSPACE file.
See also <a href='#flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu</code></a>.
</p>
<h4 id='flag--compiler'><code class='flag'>--compiler <var>version</var></code></h4>
<p>
This option specifies the C/C++ compiler version (e.g. <code>gcc-4.1.0</code>)
to be used for the compilation of binaries during the build. If you want to
build with a custom crosstool, you should use a CROSSTOOL file instead of
specifying this flag.
</p>
<p>
Note that only certain combinations of crosstool version, compiler version,
and target CPU are allowed.
</p>
<h4 id='flag--android_sdk'><code class='flag'>--android_sdk <var>label</var></code></h4>
<p>
This option specifies the Android SDK/platform toolchain
and Android runtime library that will be used to build any Android-related
rule.
The Android SDK will be automatically selected if an <code>android_sdk_repository</code>
rule is defined in the WORKSPACE file.
</p>
<h4 id='flag--java_toolchain'><code class='flag'>--java_toolchain <var>label</var></code></h4>
<p>
This option specifies the label of the java_toolchain used to compile Java
source files.
</p>
<h4 id='flag--host_java_toolchain'><code class='flag'>--host_java_toolchain <var>label</var></code></h4>
<p>
If not specified, bazel uses the value of <code class='flag'>--java_toolchain</code> to compile
code in the host configuration, i.e., tools run during the build. The main purpose of this flag
is to enable cross-compilation.
</p>
<h4 id='flag--javabase'><code class='flag'>--javabase (<var>label</var>)</code></h4>
<p>
This option sets the <i>label</i> of the base Java installation to use for <i>bazel run</i>,
<i>bazel test</i>, and for Java binaries built by <code>java_binary</code> and
<code>java_test</code> rules. The <code>JAVABASE</code> and <code>JAVA</code>
<a href='be/make-variables.html'>"Make" variables</a> are derived from this option.
</p>
<h4 id='flag--host_javabase'><code class='flag'>--host_javabase <var>label</var></code></h4>
<p>
This option sets the <i>label</i> of the base Java installation to use in the host configuration,
for example for host build tools including JavaBuilder and Singlejar.
</p>
<p>
This does not select the Java compiler that is used to compile Java
source files. The compiler can be selected by settings the
<a href="#flag--java_toolchain"><code class='flag'>--java_toolchain</code></a>
option.
</p>
<h3 id='strategy-options'>Execution strategy</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 id='flag--spawn_strategy'><code class='flag'>--spawn_strategy <var>strategy</var></code></h4>
<p>
This option controls where and how commands are executed.
</p>
<ul>
<li>
<code>standalone</code> causes commands to be executed as local subprocesses. This value is
deprecated. Please use <code>local</code> instead.
</li>
<li>
<code>sandboxed</code> causes commands to be executed inside a sandbox on the local machine.
This requires that all input files, data dependencies and tools are listed as direct
dependencies in the <code>srcs</code>, <code>data</code> and <code>tools</code> attributes.
This is the default on systems that support sandboxed execution.
</li>
<li>
<code>local</code> causes commands to be executed as local subprocesses.
</li>
<li>
<code>worker</code> causes commands to be executed using a persistent worker, if available.
</li>
<li>
<code>docker</code> causes commands to be executed inside a docker sandbox on the local machine.
This requires that docker is installed.
</li>
<li>
<code>remote</code> causes commands to be executed remotely; this is only available if a
remote executor has been configured separately.
</li>
</ul>
<h4 id='flag--strategy'><code class='flag'>--strategy <var>mnemonic</var>=<var>strategy</var></code></h4>
<p>
This option controls where and how commands are executed, overriding the default setting on a
per-mnemonic basis. See
<code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported
strategies and their effects.
</p>
<h4 id='flag--strategy_regexp'><code class='flag'>--strategy_regexp <var>&lt;filter,filter,...&gt;=&lt;strategy&gt;</var></code></h4>
<p>
This option specifies which strategy should be used to execute commands that have descriptions
matching a certain <code>regex_filter</code>. See
<code class='flag'><a href="#flag--per_file_copt">--per_file_copt</a></code> for details on
regex_filter matching. See
<code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported
strategies and their effects.
</p>
<p>
The first <code>regex_filter</code> that matches the description is used. This option overrides
other flags for specifying strategy.
</p>
<ul>
<li>
Example: <code>--strategy_regexp=//foo.*\\.cc,-//foo/bar=local</code> means to run actions using
<code>local</code> strategy if their descriptions match //foo.*.cc but not //foo/bar.
</li>
<li>
Example:
<code>--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed</code>
will run 'Compiling //foo/bar/baz' with the <code>local</code> strategy, but reversing the order
would run it with <code>sandboxed</code>.
</li>
</ul>
<h4 id='flag--genrule_strategy'><code class='flag'>--genrule_strategy <var>strategy</var></code></h4>
<p>
This is a deprecated short-hand for
<code class='flag'>--strategy=Genrule=<var>strategy</var></code>.
</p>
<h4 id='flag--jobs'><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.
</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'>--local_ram_resources</code> option.
</p>
<h4 id='flag--progress_report_interval'><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 id='flag--local_{ram,cpu}_resources'><code class='flag'>--local_{ram,cpu}_resources</code>
<var>resources or resource expression</var></h4>
<p>
These options specify the amount of local resources (RAM in MB and number of CPU logical cores)
that Bazel can take into consideration when scheduling build and test activities. They take
an integer, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by [-|*<float>float</float>]
(for example, <code class='flag'>--local_cpu_resources=2</code>,
<code class='flag'>--local_ram_resources=HOST_RAM*.5</code>,
<code class='flag'>--local_cpu_resources=HOST_CPUS-1</code>).
The flags are independent; one or both may be set. By default Bazel will estimate amount of RAM
and number of CPU cores directly from system configuration.
</p>
<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4>
<p>
This option, which is enabled by default, specifies whether the runfiles
symlinks for tests and binaries should be built in the output directory.
Using <code class='flag'>--nobuild_runfile_links</code> can be useful
to validate if all targets compile without incurring the overhead
for building the runfiles trees.
</p>
<p>
When tests (or applications) are executed, their run-time data
dependencies are gathered together in one place. Within Bazel's
output tree, this "runfiles" tree is typically rooted as a sibling of
the corresponding binary or test.
During test execution, runfiles may be accessed using paths of the form
<code>$TEST_SRCDIR/workspace/<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 (or application) requires its own runfiles tree.
</p>
<h4 id='flag--build_runfile_manifests'><code class='flag'>--[no]build_runfile_manifests</code></h4>
<p>
This option, which is enabled by default, specifies whether runfiles manifests
should be written to the output tree.
Disabling it implies <code class='flag'>--nobuild_runfile_links</code>.
It can be disabled when executing tests remotely, as runfiles trees will
be created remotely from in-memory manifests.
<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="guide.html#execution-phase">execution phase</a>.
The drawback is that further incremental builds will be slower. See also
<a href="/versions/{{ current_version }}/memory-saving-mode.html">
memory-saving mode</a>.
</p>
<h4 id='flag--keep_going'><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 id='flag--use_ijars'><code class='flag'>--[no]use_ijars</code></h4>
<p>
This option changes the way <code>java_library</code> targets are
compiled by Bazel. Instead of using the output of a
<code>java_library</code> for compiling dependent
<code>java_library</code> targets, Bazel will create interface jars
that contain only the signatures of non-private members (public,
protected, and default (package) access methods and fields) and use
the interface jars to compile the dependent targets. This makes it
possible to avoid recompilation when changes are only made to
method bodies or private members of a class.
</p>
<p>
Note that using <code class='flag'>--use_ijars</code> might give you a different
error message when you are accidentally referring to a non visible
member of another class: Instead of getting an error that the member
is not visible you will get an error that the member does not exist.
</p>
<p>
Note that changing the <code class='flag'>--use_ijars</code> setting will force
a recompilation of all affected classes.
</p>
<h4 id='flag--interface_shared_objects'>
<code class='flag'>--[no]interface_shared_objects</code>
</h4>
<p>
This option enables <i>interface shared objects</i>, which makes binaries and
other shared libraries depend on the <i>interface</i> of a shared object,
rather than its implementation. When only the implementation changes, Bazel
can avoid rebuilding targets that depend on the changed shared library
unnecessarily.
</p>
<h3 id='output-selection-options'>Output selection</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 id='flag--build_tests_only'><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--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. For
C++ and Java
sources, 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--save_temps'><code class='flag'>--save_temps</code></h4>
<p>
The <code class='flag'>--save_temps</code> option causes temporary outputs from the compiler to be
saved. These include .s files (assembler code), .i (preprocessed C) and .ii
(preprocessed C++) files. These outputs are often useful for debugging. Temps will only be
generated for the set of targets specified on the command line.
</p>
<p>
Note that our implementation of <code class='flag'>--save_temps</code> does not use the compiler's
<code>-save-temps</code> flag. Instead, we do two passes, one with <code>-S</code>
and one with <code>-E</code>. A consequence of this is that if your build fails,
Bazel may not yet have produced the ".i" or ".ii" and ".s" files.
If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation,
you may need to also use <code class='flag'>--keep_going</code> so that Bazel will still try to
produce the preprocessed files after the compilation fails.
</p>
<p>
The <code class='flag'>--save_temps</code> flag currently works only for cc_* rules.
</p>
<p>
To ensure that Bazel prints the location of the additional output files, check that
your <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a>
setting is high enough.
</p>
<h4 id='flag--build_tag_filters'><code class='flag'>--build_tag_filters <var>tag[,tag]*</var></code></h4>
<p>
If specified, Bazel will build only targets that have at least one required tag
(if any of them are specified) and does not have any excluded tags. Build 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>
When running tests, Bazel ignores <code class='flag'>--build_tag_filters</code> for test targets,
which are built and run even if they do not match this filter. To avoid building them, filter
test targets using <code class='flag'>--test_tag_filters</code> or by explicitly excluding them.
</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_lang_filters'><code class='flag'>--test_lang_filters <var>lang[,lang]*</var></code></h4>
<p>
Specifies a comma-separated list of test languages for languages with an official <code>*_test</code> rule the
(see <a href="be/overview.html">build encyclopedia</a> for a full list of these). Each
language can be optionally preceded with '-' to specify excluded
languages. The name used for each language should be the same as
the language prefix in the <code>*_test</code> rule, for example,
<code>cc</code>, <code>java</code> or <code>sh</code>.
</p>
<p>
If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
is also specified) only test targets of the specified language(s).
</p>
<p>
For example,
</p>
<pre>
% bazel test --test_lang_filters=cc,java foo/...
</pre>
<p>
will test only the C/C++ and Java tests (defined using
<code>cc_test</code> and <code>java_test</code> rules, respectively)
in <code>foo/...</code>, while
</p>
<pre>
% bazel test --test_lang_filters=-sh,-java foo/...
</pre>
<p>
will run all of the tests in <code>foo/...</code> except for the
<code>sh_test</code> and <code>java_test</code> tests.
</p>
<p>
By default, test language filtering is not applied.
</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>
<h3 id='verbosity'>Verbosity</h3>
These options control the verbosity of Bazel's output,
either to the terminal, or to additional log files.
<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 id='flag--profile'><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_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 id='flag--show_progress'><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 id='flag--show_progress_rate_limit'><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, where <var>n</var> is a real number.
If <code>n</code> is -1, all progress messages will be displayed. The default value for
this option is 0.03, meaning bazel will limit the progress messages to one per every
0.03 seconds.
</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='guide.html#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--subcommands'><code class='flag'>--subcommands</code> (<code>-s</code>)</h4>
<p>
This option causes Bazel's execution phase to print the full command line
for each command prior to executing it.
</p>
<pre>
&gt;&gt;&gt;&gt;&gt; # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
(cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
exec env - \
/usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)
</pre>
<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!)
However some commands are implemented internally within Bazel, such as
creating symlink trees. For these there's no command line to display.
</p>
<p>
<code class='flag'>--subcommands=pretty_print</code> may be passed to print
the arguments of the command as a list rather than as a single line. This may
help make long command lines more readable.
</p>
<p>
See also <a href="#flag--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='workspace_status'>Workspace status</h3>
<p>
Use these options to "stamp" Bazel-built binaries: to embed additional information into the
binaries, such as the source control revision or other workspace-related information. You can use
this mechanism with rules that support the <code>stamp</code> attribute, such as
<code>genrule</code>, <code>cc_binary</code>, and more.
</p>
<h4 id='flag--workspace_status_command'><code class='flag'>--workspace_status_command <var>program</var></code></h4>
<p>
This flag lets you specify a binary that Bazel runs before each build. The program can report
information about the status of the workspace, such as the current source control revision.
</p>
<p>
The flag's value must be a path to a native program. On Linux/macOS this may be any executable.
On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file.
</p>
<p>
The program should print zero or more key/value pairs to standard output, one entry on each line,
then exit with zero (otherwise the build fails). The key names can be anything but they may only
use upper case letters and underscores. The first space after the key name separates it from the
value. The value is the rest of the line (including additional whitespaces).
</p>
<p>
Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and
"volatile" are a bit counter-intuitive, so don't think much about them.)
</p>
<p>Bazel then writes the key-value pairs into two files:</p>
<ul>
<li>
<code>bazel-out/stable-status.txt</code>
contains all keys and values where the key's name starts with <code>STABLE_</code>
</li>
<li>
<code>bazel-out/volatile-status.txt</code>
contains the rest of the keys and their values
</li>
</ul>
<p>The contract is:</p>
<ul>
<li>
<p>
"stable" keys' values should change rarely, if possible. If the contents of
<code>bazel-out/stable-status.txt</code>
change, Bazel invalidates the actions that depend on them. In
other words, if a stable key's value changes, Bazel will rerun stamped actions.
Therefore the stable status should not contain things like timestamps, because they change all
the time, and would make Bazel rerun stamped actions with each build.
</p>
<p>Bazel always outputs the following stable keys:</p>
<ul>
<li><code>BUILD_EMBED_LABEL</code>: value of <code class='flag'>--embed_label</code></li>
<li><code>BUILD_HOST</code>: the name of the host machine that Bazel is running on</li>
<li><code>BUILD_USER</code>: the name of the user that Bazel is running as</li>
</ul>
</li>
<li>
<p>
"volatile" keys' values may change often. Bazel expects them to change all the time, like
timestamps do, and duly updates the
<code>bazel-out/volatile-status.txt</code>
file. In order to avoid
rerunning stamped actions all the time though, <b>Bazel pretends that the volatile file never
changes</b>. In other words, if the volatile status file is the only file whose contents has
changed, Bazel will not invalidate actions that depend on it. If other inputs of the actions
have changed, then Bazel reruns that action, and the action will see the updated volatile
status, but just the volatile status changing alone will not invalidate the action.
</p>
<p>Bazel always outputs the following volatile keys:</p>
<ul>
<li>
<code>BUILD_TIMESTAMP</code>: time of the build in seconds since the Unix Epoch (the value
of <code>System.currentTimeMillis()</code> divided by a thousand)
</li>
</ul>
</li>
</ul>
<p>
On Linux/macOS you can pass <code class='flag'>--workspace_status_command=/bin/true</code> to
disable retrieving workspace status, because <code>true</code> does nothing, successfully (exits
with zero) and prints no output. On Windows you can pass the path of MSYS's <code>true.exe</code>
for the same effect.
</p>
<p>If the workspace status command fails (exits non-zero) for any reason, the build will fail.</p>
<p>Example program on Linux using Git:</p>
<pre>
#!/bin/bash
echo "CURRENT_TIME $(date +%s)"
echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)"
echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
echo "STABLE_USER_NAME $USER"
</pre>
<p>
Pass this program's path with <code>--workspace_status_command</code>, and the stable status file
will include the STABLE lines and the volatile status file will include the rest of the lines.
</p>
<h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4>
<p>
This option controls whether stamping is enabled for
rule types that support it. For most of the supported rule types stamping is
enabled by default (e.g. <code>cc_binary</code>).
By default, stamping is disabled for all tests. Specifying
<code class='flag'>--stamp</code> does not force affected targets to be rebuilt,
if their dependencies have not changed.
</p>
<p>
Stamping can be enabled or disabled explicitly in BUILD using
the <code>stamp</code> attribute of certain rule types, please refer to
the <a href="be/overview.html">build encyclopedia</a> for details. For
rules that are neither explicitly or implicitly configured as <code>stamp =
0</code> or <code>stamp = 1</code>, the <code class='flag'>--[no]stamp</code> option
selects whether stamping is enabled. Bazel never stamps binaries that are
built for the host configuration, regardless of the stamp attribute.
</p>
<h3 id='platform_build_options'>Platform</h3>
<p>
Use these options to control the host and target platforms that configure how builds work, and to
control what execution platforms and toolchains are available to Bazel rules.
</p>
<p>
Please see background information on
<a href="platforms.html">Platforms</a> and <a href="toolchains.html">Toolchains</a>.
</p>
<h4 id="flag--platforms"><code class='flag'>--platforms <var>labels</var></code></h4>
<p>
The labels of the platform rules describing the target platforms for the
current command.
</p>
<h4 id="flag--host_platform"><code class='flag'>--host_platform <var>label</var></code></h4>
<p>
The label of a platform rule that describes the host system.
</p>
<h4 id="flag--extra_execution_platforms"><code class='flag'>--extra_execution_platforms <var>labels</var></code></h4>
<p>
The platforms that are available as execution platforms to run actions.
Platforms can be specified by exact target, or as a target pattern. These
platforms will be considered before those declared in the WORKSPACE file by
<a href="skylark/lib/globals.html#register_execution_platforms">
register_execution_platforms()</a>.
</p>
<h4 id="flag--extra_toolchains"><code class='flag'>--extra_toolchains <var>labels</var></code></h4>
<p>
The toolchain rules to be considered during toolchain resolution. Toolchains
can be specified by exact target, or as a target pattern. These toolchains will
be considered before those declared in the WORKSPACE file by
<a href="skylark/lib/globals.html#register_toolchains">
register_toolchains()</a>.
</p>
<h4 id="flag--toolchain_resolution_debug"><code class='flag'>--toolchain_resolution_debug=false</code></h4>
<p>
Print debug information while finding toolchains for a rule. This might help
developers of Bazel or Starlark rules with debugging failures due to missing
toolchains.
</p>
<h3 id='misc_build_options'>Miscellaneous</h3>
<h4 id='flag--flag_alias'><code class='flag'>--flag_alias <var>alias_name=target_path</var></code></h4>
<p>
A convenience flag used to bind longer Starlark build settings to a shorter name. For more
details, see the
<a href=https://docs.bazel.build/versions/master/skylark/config.html#using-build-setting-aliases">Starlark Configurations</a>.
</p>
<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 a read-only directory or one that you have no
permission to write into. 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, including the <code>bazel-out</code> and
<code>bazel-&lt;workspace&gt;</code>
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>.
</p>
</li>
</ul>
<h4 id='flag--platform_suffix'><code class='flag'>--platform_suffix <var>string</var></code></h4>
<p>
Adds a suffix to the configuration short name, which is used to determine the
output directory. Setting this option to different values puts the files into
different directories, for example to improve cache hit rates for builds that
otherwise clobber each others output files, or to keep the output files around
for comparisons.
</p>
<h4 id='flag--default_visibility'><code class='flag'>--default_visibility=<var>(private|public)</var></code></h4>
<p>
Temporary flag for testing bazel default visibility changes. Not intended for general use
but documented for completeness' sake.
</p>
<h4 id='flag--use_action_cache'><code class='flag'>--[no]use_action_cache</code></h4>
<p>
This option is enabled by default. If disabled, Bazel will not use its local action cache.
Disabling the local action cache saves memory and disk space for clean builds, but will make
incremental builds slower.
</p>
<h4 id='flag--starlark_cpu_profile'><code class='flag'>--starlark_cpu_profile=<i>file</i></code></h4>
<p>
This flag, whose value is the name of a file, causes Bazel to gather
statistics about CPU usage by all Starlark threads,
and write the profile, in <a href='https://github.com/google/pprof'>pprof</a> format,
to the named file.
Use this option to help identify Starlark functions that
make loading and analysis slow due to excessive computation. For example:
</p>
<pre>
$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
$ pprof /tmp/pprof.gz
(pprof) top
Type: CPU
Time: Feb 6, 2020 at 12:06pm (PST)
Duration: 5.26s, Total samples = 3.34s (63.55%)
Showing nodes accounting for 3.34s, 100% of 3.34s total
flat flat% sum% cum cum%
1.86s 55.69% 55.69% 1.86s 55.69% sort_source_files
1.02s 30.54% 86.23% 1.02s 30.54% expand_all_combinations
0.44s 13.17% 99.40% 0.44s 13.17% range
0.02s 0.6% 100% 3.34s 100% sorted
0 0% 100% 1.38s 41.32% my/project/main/BUILD
0 0% 100% 1.96s 58.68% my/project/library.bzl
0 0% 100% 3.34s 100% main
</pre>
<p>
For different views of the same data, try the <code>pprof</code> commands <code>svg</code>,
<code>web</code>, and <code>list</code>.
</p>
<h2 id='bazel-releng'>Using Bazel for releases</h2>
<p>
Bazel is used both by software engineers during the development
cycle, and by release engineers when preparing binaries for deployment
to production. This section provides a list of tips for release
engineers using Bazel.
</p>
<h3>Significant options</h3>
<p>
When using Bazel for release builds, the same issues arise as for
other scripts that perform a build, so you should read
the <a href='guide.html#scripting'>scripting</a> section of this manual.
In particular, the following options are strongly recommended:
</p>
<ul>
<li><a href='guide.html#bazelrc'><code class='flag'>--bazelrc=/dev/null</code></a></li>
<li><a href='#flag--keep_state_after_build'><code class='flag'>--nokeep_state_after_build</code></a></li>
</ul>
<p>
These options are also important:
</p>
<ul>
<li><a href='#flag--package_path'><code class='flag'>--package_path</code></a></li>
<li><a href='#flag--symlink_prefix'><code class='flag'>--symlink_prefix</code></a>:
for managing builds for multiple configurations,
it may be convenient to distinguish each build
with a distinct identifier, e.g. "64bit" vs. "32bit". This option
differentiates the <code>bazel-bin</code> (etc.) symlinks.
</li>
</ul>
<h2 id='test'>Running tests</h2>
<p>
To build and run tests with bazel, type <code>bazel test</code> followed by
the name of the test targets.
</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.
</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> (<code>-t</code>)</h4>
<p>
If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the
following conditions applies:
</p>
<ul>
<li>Bazel detects changes in the test or its dependencies</li>
<li>the test is marked as <code>external</code></li>
<li>multiple test runs were requested with <code class='flag'>--runs_per_test</code></li>
<li>the test failed.</li>
</ul>
<p>
If 'no', all tests will be executed unconditionally.
</p>
<p>
If 'yes', the caching behavior will be the same as auto
except that it may cache test failures and test runs with
<code class='flag'>--runs_per_test</code>.
</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--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="#flag--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 than 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.
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.
</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 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 as
defined by the page
<a href="test-encyclopedia.html">Writing Tests</a>.
By default, Bazel will use these 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 each test process. 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),
<code>getenv("var")</code> (C or C++),
</p>
<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>
<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/strace
--run_under='/usr/bin/strace -c'
--run_under=/usr/bin/valgrind
--run_under='/usr/bin/valgrind --quiet --num-callers=20'
</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 id="other_options_for_bazel_test">Other options for <code>bazel test</code></h4>
<p>
The syntax and the remaining options are exactly like
<a href='guide.html#build'>bazel build</a>.
</p>
<h3 id='clean'>Cleaning build outputs</h3>
<h4>The <code>clean</code> command</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>Recall that each Bazel instance is associated with a single workspace, thus the
<code>clean</code> command will delete all outputs from all builds you've done
with that Bazel instance in that workspace.
</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 might not be
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. If you
ever find an incorrect incremental build, please file a bug report.
We encourage developers to get out of the habit of
using <code>clean</code> and into that of reporting bugs in the
tools.
</p>
<h2 id='run'>Running executables</h2>
<p>
The <code>bazel run</code> command is similar to <code>bazel build</code>, except
it is used to build <em>and run</em> 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: Found 1 target...
...
Target //java/myapp:myapp up-to-date:
bazel-bin/java/myapp:myapp
INFO: Elapsed time: 0.638s, Critical Path: 0.34s
INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2
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.
(The program being run simply says hello and prints out its args.)
</p>
<p><code>bazel run</code> is similar, but not identical, to directly invoking
the binary built by Bazel and its behavior is different depending on whether the
binary to be invoked is a test or not.
When the binary is not a test, the current working directory will be the
runfiles tree of the binary.
When the binary is a test, the current working directory will be the exec root
and a good-faith attempt is made to replicate the environment tests are usually
run in. The emulation is not perfect, though, and tests that have multiple
shards cannot be run this way (the
<code>--test_sharding_strategy=disabled</code> command line option can be used
to work around this)
The following extra environment variables are also available to the binary:
<ul>
<li>
<code>BUILD_WORKSPACE_DIRECTORY</code>: the root of the workspace where the
build was run.
</li>
<li>
<code>BUILD_WORKING_DIRECTORY</code>: the current working directory where
Bazel was run from.
</li>
</ul>
These can be used, for example, to interpret file names on the command line in
a user-friendly way.
<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>
<h3>Executing tests</h3>
<p>
<code>bazel run</code> can also execute test binaries, which has the effect of
running the test in a close approximation of the environment described at
<a href='test-encyclopedia.html'>Writing Tests</a>. Note that none of the
<code>--test_*</code> arguments have an effect when running a test in this manner except
<code>--test_arg</code> .
</p>
<h2 id='query'>Querying the dependency graph</h2>
<p>
Bazel includes a query language for asking questions about the
dependency graph used during the build. The query language is used
by two commands: query and cquery. The major difference between the
two commands is that query runs after the <a href='guide.html#loading-phase'>loading phase</a>
and cquery runs after the <a href='guide.html#analysis-phase'>analysis phase</a>. These tools are 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="query.html">Bazel Query Reference</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]tool_deps</code> option,
enabled by default, causes dependencies in non-target configurations to be included in the
dependency graph over which the query operates.
</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 PEBL tree."
</p>
<pre>
bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
</pre>
<h2 id='aquery'>Querying the action graph</h2>
<b>Caution</b>: The aquery command is still experimental and its API will change.
<p>
The <code>aquery</code> command allows you to query for actions in your build graph.
It operates on the post-analysis configured target graph and exposes
information about actions, artifacts and their relationships.
</p>
<p>
The tool accepts several command-line options.
<code class='flag'>--output</code> selects the output format. The default output format
(<code>text</code>) is human-readable, use <code>proto</code> or <code>textproto</code> for
machine-readable format.
Notably, the aquery command runs on top of a regular Bazel build and inherits
the set of options available during a build.
</p>
<p>
It supports the same set of functions that is also available to traditional
<code>query</code> but <code>siblings</code>, <code>buildfiles</code> and
<code>tests</code>.
</p>
<p>
More details on aquery can be found <a href="aquery.html">here</a>.
</p>
<h2 id='misc'>Miscellaneous commands and options</h2>
<h3 id='help'><code>help</code></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='guide.html#overview'><i>Bazel overview</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 id='flag--long'><code class='flag'>--[no]long</code> (<code>-l</code>)</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'><code>shutdown</code></h3>
<p>
Bazel server processes (see <a href='guide.html#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 (in MB). 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'><code>info</code></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 the base workspace
directory.
</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 named
<code>bazel-&lt;workspace&gt;</code>
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>server_log</code>: the absolute path to the Bazel server's debug log file.
This file contains debugging information for all commands over the lifetime of the
Bazel server, and is intended for human consumption by Bazel developers and power users.
</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>used-heap-size</code>,
<code>committed-heap-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'>--cpu</code>, <code class='flag'>--compilation_mode</code>,
etc. 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 base workspace directory 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='be/make-variables.html'
>"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>CC</code>, <code>GLIBC_VERSION</code>, etc).
These are the variables accessed using the <code>$(CC)</code>
or <code>varref("CC")</code> syntax inside BUILD files.
</li>
</ul>
<p>
Example: the C++ compiler for the current configuration.
This is the <code>$(CC)</code> variable in the "Make" environment,
so the <code class='flag'>--show_make_env</code> flag is needed.
</p>
<pre>
% bazel info --show_make_env -c opt COMPILATION_MODE
opt
</pre>
<p>
Example: the <code>bazel-bin</code> output directory for the current
configuration. This is guaranteed to be correct even in cases where
the <code>bazel-bin</code> symlink cannot be created for some reason
(e.g. you are building from a read-only directory).
</p>
<pre>% bazel info --cpu=piii bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
% bazel info --cpu=k8 bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin
</pre>
<h3 id='version'><code>version</code> and <code>--version</code></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, or if you are reporting bugs. Some of the interesting values
are:
</p>
<ul>
<li><code>changelist</code>: the changelist at which this version of
Bazel was released.
</li>
<li><code>label</code>: the release label for this Bazel
instance, or "development version" if this is not a released
binary. Very useful when reporting bugs.
</li>
</ul>
<p>
<code>bazel --version</code>, with no other args, will emit the same output as
<code>bazel version --gnu_format</code>, except without the side-effect of potentially starting
a Bazel server or unpacking the server archive. <code>bazel --version</code> can be run from
anywhere - it does not require a workspace directory.
</p>
<h3 id='mobile-install'><code>mobile-install</code></h3>
<p>
The <code>mobile-install</code> command installs apps to mobile devices.
Currently only Android devices running ART are supported.
See <a href="mobile-install.html">bazel mobile-install</a>
for more information.
</p>
<p>
Note that this command does not install the same thing that
<code>bazel build</code> produces: Bazel tweaks the app so that it can be
built, installed and re-installed quickly. This should, however, be mostly
transparent to the app.
</p>
<p>
The following options are supported:
</p>
<h4 id='flag--incremental'><code class='flag'>--incremental</code></h4>
<p>
If set, Bazel tries to install the app incrementally, that is, only those
parts that have changed since the last build. This cannot update resources
referenced from <code>AndroidManifest.xml</code>, native code or Java
resources (i.e. ones referenced by <code>Class.getResource()</code>). If these
things change, this option must be omitted. Contrary to the spirit of Bazel
and due to limitations of the Android platform, it is the
<b>responsibility of the user</b> to know when this command is good enough and
when a full install is needed.
If you are using a device with Marshmallow or later, consider the
<a href='#flag--split_apks'><code class='flag'>--split_apks</code></a> flag.
</p>
<h4 id='flag--split_apks'><code class='flag'>--split_apks</code></h4>
<p>
Whether to use split apks to install and update the application on the device.
Works only with devices with Marshmallow or later. Note that the
<a href='#flag--incremental'><code class='flag'>--incremental</code></a> flag
is not necessary when using <code class='flag'>--split_apks</code>.
</p>
<h4 id='flag--start_app'><code class='flag'>--start_app</code></h4>
<p>
Starts the app in a clean state after installing. Equivalent to
<code>--start=COLD</code>.
</p>
<h4 id='flag--debug_app'><code class='flag'>--debug_app</code></h4>
<p>
Waits for debugger to be attached before starting the app in a clean state after installing.
Equivalent to <code>--start=DEBUG</code>.
</p>
<h4 id='flag--start'><code class='flag'>--start=<i>start_type</i></code></h4>
<p>
How the app should be started after installing it. Supported <i>start_type</i>s are:
<ul>
<li><code>NO</code> Does not start the app. This is the default.</li>
<li><code>COLD</code> Starts the app from a clean state after install.</li>
<li><code>WARM</code> Preserves and restores the application state on incremental installs.</li>
<li><code>DEBUG</code> Waits for the debugger before starting the app in a clean state after install.</li>
</ul>
Note that if more than one of <code class='flag'>--start=<i>start_type</i></code>,
<code class='flag'>--start_app</code> or
<code class='flag'>--debug_app</code> is set, the last value will be used.
</p>
<h4 id='flag--adb'><code class='flag'>--adb <var>path</var></code></h4>
<p>
Indicates the <code>adb</code> binary to be used.
The default is to use the adb in the Android SDK specified by
<a href='#flag--android_sdk'><code class='flag'>--android_sdk</code></a>.
</p>
<h4 id='flag--adb_arg'><code class='flag'>--adb_arg <var>arg</var></code></h4>
<p>
Extra arguments to <code>adb</code>. These come before the subcommand in the
command line and are typically used to specify which device to install to.
For example, to select the Android device or emulator to use:
<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
</pre>
will invoke <code>adb</code> as
<pre>
adb -s deadbeef install ...
</pre>
</p>
<h4 id='flag--incremental_install_verbosity'><code class='flag'>--incremental_install_verbosity <var>number</var></code></h4>
<p>
The verbosity for incremental install. Set to 1 for debug logging to be
printed to the console.
</p>
<h3 id='dump'><code>dump</code></h3>
<p>
The <code>dump</code> command prints to stdout a dump of the
internal state of the Bazel server. This command is intended
primarily for use by Bazel developers, so the output of this command
is not specified, and is subject to change.
</p>
<p>
By default, command will just print help message outlining possible
options to dump specific areas of the Bazel state. In order to dump
internal state, at least one of the options must be specified.
</p>
<p>
Following options are supported:
</p>
<ul>
<li><code class='flag'>--action_cache</code> dumps action cache content.</li>
<li><code class='flag'>--packages</code> dumps package cache content.</li>
<li><code class='flag'>--skyframe</code> dumps state of internal Bazel dependency graph.</li>
<li><code class='flag'>--rules</code> dumps rule summary for each rule and aspect class,
including counts and action counts. This includes both native and Starlark rules.
If memory tracking is enabled, then the rules' memory consumption is also printed.</li>
<li><code class='flag'>--skylark_memory</code> dumps a
<href a=https://github.com/google/pprof>pprof</href> compatible .gz file to the specified path.
You must enable memory tracking for this to work.</li>
<li><code class='flag'>--action_graph=/path/to/file</code> dumps the state of
the internal Bazel action graph in proto format to
<code>/path/to/file</code>. You have to run (at least) the analysis phase
for the targets you are interested in (for example, <code>bazel build --nobuild
//foo:bar</code>). Note that this feature is still experimental, subject to
change and will probably be integrated into <code>cquery</code> in the
future.
<li><code class='flag'>--action_graph:targets=target1,target2,...</code>
filters the actions to the comma-separated list of targets when dumping the
action graph.</li>
<li><code class='flag'>--action_graph:include_cmdline</code> Include the command lines of actions
in the action graph dump.</li>
</ul>
<h4 id='memory-tracking'>Memory tracking</h4>
<p>
Some <code>dump</code> commands require memory tracking. To turn this on, you have to pass
startup flags to Bazel:
</p>
<ul>
<li><code>--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar</code></li>
<li><code>--host_jvm_args=-DRULE_MEMORY_TRACKER=1</code></li>
</ul>
<p>
The java-agent is checked into bazel at
third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar, so make
sure you adjust <code>$BAZEL</code> for where you keep your bazel repository.
Do not forget to keep passing these options to Bazel for every command or the server will
restart.
</p>
<p>Example:</p>
<pre>
% bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
--host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
build --nobuild &lt;targets&gt;
# Dump rules
% bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
--host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
dump --rules
# Dump Starlark heap and analyze it with pprof
% bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
--host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
dump --skylark_memory=$HOME/prof.gz
% pprof -flame $HOME/prof.gz
</pre>
<h3 id='analyze-profile'><code>analyze-profile</code></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>
<p>
The following options are supported:
</p>
<ul>
<li><code id='flag--dump'>--dump</code> displays all gathered data in a
<a href='guide.html#dump-text-format'>human-readable format</a>. However,
this it does not support other formats yet.</li>
</ul>
<p>
See the section on <a href='guide.html#profiling'>Troubleshooting performance by profiling</a> for
format details and usage help.
</p>
<h3 id='canonicalize'><code>canonicalize-flags</code></h3>
<p>
The <a href="https://docs.bazel.build/command-line-reference.html#canonicalize-flags-options">
<code>canonicalize-flags</code></a> 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. Also note that this command
<i>does not</i> expand flags from <code>--config</code>.
</p>
<p>
As an example:
</p>
<pre>
% bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint"
--config=any_name
--test_tag_filters=-lint
</pre>
<h3 id='startup_options'>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 id='flag--output_base'><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>/var/tmp/google/_bazel_johndoe/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
workspace directory by varying the output base.
</p>
<p>For example:</p>
<pre><code>
OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
% bazel --output_base $OUTPUT_BASE build //foo &amp; bazel --output_base $OUTPUT_BASE build //bar
</code></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: building <code>//foo</code> 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.
</p>
<h4 id='flag--output_user_root'><code class='flag'>--output_user_root=<var>dir</var></code></h4>
<p>
Points to the root directory where output bases are created unless
overriden with <code class='flag'>--output_base</code>. The directory
must either not exist or be owned by the calling user. In the past,
this was allowed to point to a directory shared among various users
but it's not allowed any longer. (We can reconsider allowing this once
<a href='https://github.com/bazelbuild/bazel/issues/11100'>#11100</a>
is addressed.)
</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>
<a name="startup_flag--host_javabase"></a>
<h4 id='startup_flag--server_javabase'><code class='flag'>--server_javabase=<var>dir</var></code></h4>
<p>
Specifies the Java virtual machine in which <i>Bazel itself</i> runs. The value must be a path to
the directory containing a JDK or JRE. It should not be a label.
This option should appear before any Bazel command, for example:
</p>
<pre>
% bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo
</pre>
<p>
This flag does <i>not</i> affect the JVMs used by Bazel subprocesses such as applications, tests,
tools, and so on. Use build options <a href='#flag--javabase'>--javabase</a> or
<a href='#flag--host_javabase'>--host_javabase</a> instead.
</p>
<p>
This flag was previously named <code>--host_javabase</code> (sometimes referred to as the
'left-hand side' <code>--host_javabase</code>), but was renamed to avoid confusion with the
build flag <a href='#flag--host_javabase'>--host_javabase</a> (sometimes referred to as the
'right-hand side' <code>--host_javabase</code>).
</p>
<h4 id='flag--host_jvm_args'><code class='flag'>--host_jvm_args=<var>string</var></code></h4>
<p>
Specifies a startup option 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 //foo
</pre>
<p>
This option can be used multiple times with individual arguments. Note that
setting this flag should rarely be needed. You can also pass a space-separated list of strings,
each of which will be interpreted as a separate JVM argument, but this feature will soon be
deprecated.
</p>
<p>
That this does <i>not</i> affect any JVMs used by
subprocesses of Bazel: applications, tests, tools, and so on. 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 id='flag--host_jvm_debug'><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 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='flag--autodetect_server_javabase'><code class='flag'>--autodetect_server_javabase</code></h4>
<p>
This option causes Bazel to automatically search for an installed JDK on startup,
and to fall back to the installed JRE if the embedded JRE isn't available.
<code>--explicit_server_javabase</code> can be used to pick an explicit JRE to
run bazel with.
</p>
<h4 id='flag--batch'><code class='flag'>--batch</code></h4>
<p>
Batch mode causes Bazel to not use the standard client/server mode described
<a href='guide.html#client/server'>above</a>, instead running a bazel java process for a
single command, which has been used for more predictable semantics with respect
to signal handling, job control, and environment variable inheritance, and is
necessary for running bazel in a chroot jail.
</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, or with the alternatives described above.
This is because, 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>
<p>
<i>WARNING:</i> <code class='flag'>--batch</code> is sufficiently slower than standard
client/server mode. Additionally it might not support all of the features and optimizations which
are made possible by a persistent Bazel server. If you're using <code class='flag'>--batch</code>
for the purpose of build isolation, we recommend using the command option
<code class='flag'>--nokeep_state_after_build</code>, which guarantees that no incremental
in-memory state is kept between builds. In order to restart the Bazel server and JVM after a
build, please explicitly do so using the "shutdown" command.
</p>
<h4 id='flag--max_idle_secs'><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). <code class='flag'>--max_idle_secs=0</code> will cause the
Bazel server process to persist indefinitely. <i>NOTE:</i> this flag is only read if Bazel needs
to start a new server. Changing this option will not cause the server to restart.
</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, a presubmit 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 presubmit 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 id='flag--shutdown_on_low_sys_mem'><code class='flag'>--[no]shutdown_on_low_sys_mem</code></h4>
<p>
If enabled and <code class='flag'>--max_idle_secs</code> is set to a positive duration,
after the build server has been idle for a while, shut down the server when the system is
low on memory. Linux only.
</p>
<p>
In addition to running an idle check corresponding to max_idle_secs, the build server will
starts monitoring available system memory after the server has been idle for some time.
If the available system memory becomes critically low, the server will exit.
</p>
<h4 id='flag--block_for_lock'><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 in presubmit checks to avoid long waits caused
by another Bazel command in the same client.
</p>
<h4 id='flag--io_nice_level'><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 id='flag--batch_cpu_scheduling'><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 command options read from the bazelrc file when
starting up. (Startup options are unconditionally announced.)
</p>
<h4 id='flag--color'><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 section 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. Can be specified multiple
times to add flags from several config sections. Expansions can refer to other
definitions (i.e. expansions can be chained).
</p>
<h4 id='flag--curses'><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 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>