Branch Bazel docs into version directory.
--
MOS_MIGRATED_REVID=131156143
diff --git a/site/versions/master/docs/bazel-user-manual.html b/site/versions/master/docs/bazel-user-manual.html
new file mode 100644
index 0000000..7944974
--- /dev/null
+++ b/site/versions/master/docs/bazel-user-manual.html
@@ -0,0 +1,3735 @@
+---
+layout: documentation
+title: User Manual
+---
+<h1>A User's Guide to Bazel</h1>
+
+<h2 id='overview'>Bazel overview</h2>
+
+<p>
+ To run Bazel, go to
+
+ your base <a href="/docs/build-ref.html#workspaces">workspace</a> directory
+ or any of its subdirectories and type <code>bazel</code>.
+</p>
+
+<pre>
+ % bazel help
+ [Bazel release bazel-<<i>version</i>>]
+ Usage: bazel <command> <options> ...
+
+ Available commands:
+ <a href='#analyze-profile'>analyze-profile</a> Analyzes build profile data.
+ <a href='#build'>build</a> Builds the specified targets.
+
+ <a href='#canonicalize'>canonicalize-flags</a> Canonicalize Bazel flags.
+ <a href='#clean'>clean</a> Removes output files and optionally stops the server.
+
+ <a href='#help'>help</a> Prints help for commands, or the index.
+
+ <a href='#info'>info</a> Displays runtime info about the bazel server.
+
+ <a href='#fetch'>fetch</a> Fetches all external dependencies of a target.
+ <a href='#mobile-install'>mobile-install</a> Installs apps on mobile devices.
+
+ <a href='#query'>query</a> Executes a dependency graph query.
+
+ <a href='#run'>run</a> Runs the specified target.
+ <a href='#shutdown'>shutdown</a> Stops the Bazel server.
+ <a href='#test'>test</a> Builds and runs the specified test targets.
+ <a href='#version'>version</a> Prints version information for Bazel.
+
+ Getting more help:
+ bazel help <command>
+ Prints help and options for <command>.
+ bazel help <a href='#startup_options'>startup_options</a>
+ Options for the JVM hosting Bazel.
+ bazel help <a href='#target-patterns'>target-syntax</a>
+ Explains the syntax for specifying targets.
+ bazel help info-keys
+ Displays a list of keys used by the info command.
+
+</pre>
+<p>
+ The <code>bazel</code> tool performs many functions, called
+ commands; users of CVS and Subversion will be familiar
+ with this "Swiss army knife" arrangement. The most commonly used one is of
+ course <code>bazel build</code>. You can browse the online help
+ messages using <code>bazel help</code>.
+</p>
+
+<h3 id='client/server'>Client/server implementation</h3>
+
+<p>
+ The Bazel system is implemented as a long-lived server process.
+ This allows it to perform many optimizations not possible with a
+ batch-oriented implementation, such as caching of BUILD files,
+ dependency graphs, and other metadata from one build to the
+ next. This improves the speed of incremental builds, and allows
+ different commands, such as <code>build</code>
+ and <code>query</code> to share the same cache of loaded packages,
+ making queries very fast.
+</p>
+<p>
+ When you run <code>bazel</code>, you're running the client. The
+ client finds the server based on the path of the base workspace directory
+ and your userid, so if you build in multiple workspaces, you'll have
+ multiple Bazel server processes. Multiple users on the same
+ workstation can build concurrently in the same workspace. If the
+ client cannot find a running server instance, it starts a new one.
+ The server process will stop after a period of inactivity (3 hours,
+ by default).
+</p>
+<p>
+ For the most part, the fact that there is a server running is
+ invisible to the user, but sometimes it helps to bear this in mind.
+ For example, if you're running scripts that perform a lot of
+ automated builds in different directories, it's important to ensure
+ that you don't accumulate a lot of idle servers; you can do this by
+ explicitly shutting them down when you're finished with them, or by
+ specifying a short timeout period.
+</p>
+<p>
+ The name of a Bazel server process appears in the output of <code>ps
+ x</code> or <code>ps -e f</code> as
+ <code>bazel(<i>dirname</i>)</code>, where <i>dirname</i> is the
+ basename of the directory enclosing the root your workspace directory.
+ For example:
+</p>
+<pre>
+ % ps -e f
+ 16143 ? Sl 3:00 bazel(src-jrluser2) -server -Djava.library.path=...
+</pre>
+<p>
+ This makes it easier to find out which server process belongs to a
+ given workspace. (Beware that with certain other options
+ to <code>ps</code>, Bazel server processes may be named just
+ <code>java</code>.) Bazel servers can be stopped using
+ the <a href='#shutdown'>shutdown</a> command.
+</p>
+<p>
+ You can also run Bazel in batch mode using the <code>--batch</code>
+ startup flag. This will immediately shut down the process after the
+ command (build, test, etc.) has finished and not keep a server process
+ around.
+</p>
+
+<p>
+ When running <code>bazel</code>, the client first checks that the
+ server is the appropriate version; if not, the server is stopped and
+ a new one started. This ensures that the use of a long-running
+ server process doesn't interfere with proper versioning.
+</p>
+
+<h3 id='bazelrc'><code>.bazelrc</code>, the Bazel configuration file,
+the <code class='flag'>--bazelrc=<var>file</var></code> option, and the
+<code class='flag'>--config=<var>value</var></code> option</h3>
+
+<p>
+ Bazel accepts many options. Typically, some of these are varied
+ frequently (e.g. <code class='flag'>--subcommands</code>) while others stay the
+ same across several builds (e.g. <code class='flag'>--package_path</code>).
+ To avoid having to specify these constant options every time you do
+ a build or run some other Bazel command, Bazel allows you to
+ specify options in a configuration file.
+</p>
+<p>
+ Bazel looks for an optional configuration file in the location
+ specified by the <code class='flag'>--bazelrc=<var>file</var></code> option. If
+ this option is not specified then, by default, Bazel looks for the
+ file called <code>.bazelrc</code> in one of two directories: first,
+ in your base workspace directory, then in your home directory. If
+ it finds a file in the first (workspace-specific) location, it will
+ not look at the second (global) location.
+</p>
+<p>
+ The <code class='flag'>--bazelrc=<var>file</var></code> option must
+ appear <em>before</em> the command name (e.g. <code>build</code>).
+</p>
+<p>
+ The option <code class='flag'>--bazelrc=/dev/null</code> effectively disables the
+ use of a configuration file. We strongly recommend that you use
+ this option when performing release builds, or automated tests that
+ invoke Bazel.
+</p>
+
+<p>
+ Aside from the configuration file described above, Bazel also looks
+ for a master configuration file next to the binary, in the workspace
+ at <code>tools/bazel.rc</code> or system-wide at
+ <code>/etc/bazel.bazelrc</code>. These files are here to support
+ installation-wide options or options shared between users.
+</p>
+<p>
+ Like all UNIX "rc" files, the <code>.bazelrc</code> file is a text
+ file with a line-based grammar. Lines starting <code>#</code> are
+ considered comments and are ignored, as are blank lines. Each line
+ contains a sequence of words, which are tokenized according to the
+ same rules as the Bourne shell.
+ The first word on each line is the name of a Bazel command, such
+ as <code>build</code> or <code>query</code>. The remaining words
+ are the default options that apply to that command.
+ More than one line may be used for a command; the options are combined
+ as if they had appeared on a single line.
+ (Users of CVS, another tool with a "Swiss army knife" command-line
+ interface, will find the syntax familiar to that of <code>.cvsrc</code>.)
+</p>
+<p>
+ Startup options may be specified in the
+ <code>.bazelrc</code> file using the command <code>startup</code>.
+ These options are described in the interactive help
+ at <code>bazel help startup_options</code>.
+</p>
+<p>
+ Options specified in the command line always take precedence over
+ those from a configuration file. In configuration files, lines for a more specific command take
+ precedence over lines for a less specific command (e.g. the 'test' command inherits all the
+ options from the 'build' command, so a 'test --foo=bar' line takes precedence over a
+ 'build --foo=baz' line, regardless of which configuration files these two lines are in) and lines
+ equally specific for which command they apply have precedence based on the configuration file they
+ are in, with the user-specific configuration file taking precedence over the master one.
+</p>
+<p>
+ Options may include words other than flags, such as the names of
+ build targets, etc; these are always prepended to the explicit
+ argument list provided on the command-line, if any.
+</p>
+<p>
+ Common command options may be specified in the
+ <code>.bazelrc</code> file using the command <code>common</code>.
+</p>
+<p>
+ In addition, commands may have <code>:name</code> suffixes. These
+ options are ignored by default, but can be pulled in through the
+ <code>--config=<var>name</var></code> option, either on the command line or in
+ a <code>.bazelrc</code> file. The intention is that these bundle command line
+ options that are commonly used together, for example
+ <code>--config=memcheck</code>.
+</p>
+<p>
+ Note that some config sections are defined in the master bazelrc file.
+ To avoid conflicts, user-defined sections
+ should start with the '_' (underscore) character.
+</p>
+<p>
+ The command named <code>import</code> is special: if Bazel encounters such
+ a line in a <code>.bazelrc</code> file, it parses the contents of the file
+ referenced by the import statement, too. Options specified in an imported file
+ take precedence over ones specified before the import statement, options
+ specified after the import statement take precedence over the ones in the
+ imported file, and options in files imported later take precedence over files
+ imported earlier.
+</p>
+<p>
+ Here's an example <code>~/.bazelrc</code> file:
+</p>
+<pre>
+ # Bob's Bazel option defaults
+
+ startup --batch --host_jvm_args=-XX:-UseParallelGC
+ import /home/bobs_project/bazelrc
+ build --show_timestamps --keep_going --jobs 600
+ build --color=yes
+ query --keep_going
+
+ build:memcheck --strip=never --test_timeout=3600
+</pre>
+
+<h2 id='build'>Building programs with Bazel</h2>
+<h3>The <code>build</code> command</h3>
+
+<p>
+ The most important function of Bazel is, of course, building code. Type
+ <code>bazel build</code> followed by the name of the
+ <a href="#target-patterns">target</a> you wish to build. Here's a typical
+ session:
+</p>
+<pre>
+ % bazel build //foo
+ ____Loading package: foo
+ ____Loading package: bar
+ ____Loading package: baz
+ ____Loading complete. Analyzing...
+ ____Building 1 target...
+ ____[0 / 3] Executing Genrule //bar:helper_rule
+ ____[1 / 3] Executing Genrule //baz:another_helper_rule
+ ____[2 / 3] Building foo/foo.bin
+ Target //foo:foo up-to-date:
+ bazel-bin/foo/foo.bin
+ bazel-bin/foo/foo
+ ____Elapsed time: 9.905s
+</pre>
+<p>
+ Bazel prints the progress messages as it loads all the
+ packages in the transitive closure of dependencies of the requested
+ target, then analyzes them for correctness and to create the build actions,
+ finally executing the compilers and other tools of the build.
+</p>
+<p>
+ Bazel prints progress messages during
+ the <a href='#execution-phase'>execution phase</a> of the build, showing the
+ current build step (compiler, linker, etc.) that is being started,
+ and the number of completed over total number of build actions. As the
+ build starts the number of total actions will often increase as Bazel
+ discovers the entire action graph, but the number will usually stabilize
+ within a few seconds.
+</p>
+<p>
+ At the end of the build Bazel
+ prints which targets were requested, whether or not they were
+ successfully built, and if so, where the output files can be found.
+ Scripts that run builds can reliably parse this output; see <a
+ href='#flag--show_result'><code class='flag'>--show_result</code></a> for more
+ details.
+</p>
+<p>
+ Typing the same command again:
+</p>
+<pre>
+ % bazel build //foo
+ ____Loading...
+ ____Found 1 target...
+ ____Building complete.
+ Target //foo:foo up-to-date:
+ bazel-bin/foo/foo.bin
+ bazel-bin/foo/foo
+ ____Elapsed time: 0.280s
+</pre>
+<p>
+ we see a "null" build: in this case, there are no packages to
+ re-load, since nothing has changed, and no build steps to execute.
+ (If something had changed in "foo" or some of its dependencies, resulting in the
+ reexecution of some build actions, we would call it an "incremental" build, not a
+ "null" build.)
+</p>
+
+<p>
+ Before you can start a build, you will need a Bazel workspace. This is
+ simply a directory tree that contains all the source files needed to build
+ your application.
+ Bazel allows you to perform a build from a completely read-only volume.
+</p>
+
+<h4 id='flag--package_path'>Setting up a <code class='flag'>--package_path</code></h4>
+<p>
+ Bazel finds its packages by searching the package path. This is a colon
+ separated ordered list of bazel directories, each being the root of a
+ partial source tree.
+</p>
+
+<p>
+ <i>To specify a custom package path</i> using the
+ <code class='flag'>--package_path</code> option:
+</p>
+<pre>
+ % bazel build --package_path %workspace%:/some/other/root
+</pre>
+<p>
+Package path elements may be specified in three formats:
+</p>
+<ol>
+ <li>
+ If the first character is <code>/</code>, the path is absolute.
+ </li>
+ <li>
+ If the path starts with <code>%workspace%</code>, the path is taken relative
+ to the nearest enclosing bazel directory.<br>
+ For instance, if your working directory
+ is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the
+ string <code>%workspace%</code> in the package-path is expanded
+ to <code>/home/bob/clients/bob_client/bazel</code>.
+ </li>
+ <li>
+ Anything else is taken relative to the working directory.<br> This is usually not what you mean to do,
+ and may behave unexpectedly if you use Bazel from directories below the bazel workspace.
+ For instance, if you use the package-path element <code>.</code>,
+ and then cd into the directory
+ <code>/home/bob/clients/bob_client/bazel/foo</code>, packages
+ will be resolved from the
+ <code>/home/bob/clients/bob_client/bazel/foo</code> directory.
+ </li>
+</ol>
+<p>
+ If you use a non-default package path, we recommend that you specify
+ it in your <a href='#bazelrc'>Bazel configuration file</a> for
+ convenience.
+</p>
+<p>
+ <i>Bazel doesn't require any packages to be in the
+ current directory</i>, so you can do a build from an empty bazel
+ workspace if all the necessary packages can be found somewhere else
+ on the package path.
+</p>
+<p>
+ <i>Example</i>: Building from an empty client
+</p>
+<pre>
+ % mkdir -p foo/bazel
+ % cd foo/bazel
+ % bazel build --package_path /some/other/path //foo
+</pre>
+<h3 id='target-patterns'>Specifying targets to build</h3>
+<p>
+ Bazel allows a number of ways to specify the targets to be built.
+ Collectively, these are known as <i>target patterns</i>.
+ The on-line help displays a summary of supported patterns:
+</p>
+<pre>
+% bazel help target-syntax
+
+Target pattern syntax
+=====================
+
+The BUILD file label syntax is used to specify a single target. Target
+patterns generalize this syntax to sets of targets, and also support
+working-directory-relative forms, recursion, subtraction and filtering.
+Examples:
+
+Specifying a single target:
+
+ //foo/bar:wiz The single target '//foo/bar:wiz'.
+ foo/bar/wiz Equivalent to:
+ '//foo/bar/wiz:wiz' if foo/bar/wiz is a package,
+ '//foo/bar:wiz' if foo/bar is a package,
+ '//foo:bar/wiz' otherwise.
+ //foo/bar Equivalent to '//foo/bar:bar'.
+
+Specifying all rules in a package:
+
+ //foo/bar:all Matches all rules in package 'foo/bar'.
+
+Specifying all rules recursively beneath a package:
+
+ //foo/...:all Matches all rules in all packages beneath directory 'foo'.
+ //foo/... (ditto)
+
+ By default, directory symlinks are followed when performing this recursive traversal, except
+ those that point to under the output base (for example, the convenience symlinks that are created
+ in the root directory of the workspace) But we understand that your workspace may intentionally
+ contain directories with unusual symlink structures that you don't want consumed. As such, if a
+ directory has a file named
+ 'DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN' then symlinks
+ in that directory won't be followed when evaluating recursive target patterns.
+
+Working-directory relative forms: (assume cwd = 'workspace/foo')
+
+ Target patterns which do not begin with '//' are taken relative to
+ the working directory. Patterns which begin with '//' are always
+ absolute.
+
+ ...:all Equivalent to '//foo/...:all'.
+ ... (ditto)
+
+ bar/...:all Equivalent to '//foo/bar/...:all'.
+ bar/... (ditto)
+
+ bar:wiz Equivalent to '//foo/bar:wiz'.
+ :foo Equivalent to '//foo:foo'.
+
+ bar Equivalent to '//foo/bar:bar'.
+ foo/bar Equivalent to '//foo/foo/bar:bar'.
+
+ bar:all Equivalent to '//foo/bar:all'.
+ :all Equivalent to '//foo:all'.
+
+Summary of target wildcards:
+
+ :all, Match all rules in the specified packages.
+ :*, :all-targets Match all targets (rules and files) in the specified
+ packages, including ones not built by default, such
+ as _deploy.jar files.
+
+Subtractive patterns:
+
+ Target patterns may be preceded by '-', meaning they should be
+ subtracted from the set of targets accumulated by preceding
+ patterns. (Note that this means order matters.) For example:
+
+ % bazel build -- foo/... -foo/contrib/...
+
+ builds everything in 'foo', except 'contrib'. In case a target not
+ under 'contrib' depends on something under 'contrib' though, in order to
+ build the former bazel has to build the latter too. As usual, the '--' is
+ required to prevent '-f' from being interpreted as an option.
+</pre>
+<p>
+ Whereas <a href="build-ref.html#labels">labels</a> are used
+ to specify individual targets, e.g. for declaring dependencies in
+ BUILD files, Bazel's target patterns are a syntax for specifying
+ multiple targets: they are a generalization of the label syntax
+ for <i>sets</i> of targets, using wildcards. In the simplest case,
+ any valid label is also a valid target pattern, identifying a set of
+ exactly one target.
+</p>
+<p>
+ <code>foo/...</code> is a wildcard over <em>packages</em>,
+ indicating all packages recursively beneath
+ directory <code>foo</code> (for all roots of the package
+ path). <code>:all</code> is a wildcard
+ over <em>targets</em>, matching all rules within a package. These two may be
+ combined, as in <code>foo/...:all</code>, and when both wildcards
+ are used, this may be abbreviated to <code>foo/...</code>.
+</p>
+<p>
+ In addition, <code>:*</code> (or <code>:all-targets</code>) is a
+ wildcard that matches <em>every target</em> in the matched packages,
+ including files that aren't normally built by any rule, such
+ as <code>_deploy.jar</code> files associated
+ with <code>java_binary</code> rules.
+</p>
+<p>
+ This implies that <code>:*</code> denotes a <em>superset</em>
+ of <code>:all</code>; while potentially confusing, this syntax does
+ allow the familiar <code>:all</code> wildcard to be used for
+ typical builds, where building targets like the <code>_deploy.jar</code>
+ is not desired.
+</p>
+<p>
+ In addition, Bazel allows a slash to be used instead of the colon
+ required by the label syntax; this is often convenient when using
+ Bash filename expansion. For example, <code>foo/bar/wiz</code> is
+ equivalent to <code>//foo/bar:wiz</code> (if there is a
+ package <code>foo/bar</code>) or to <code>//foo:bar/wiz</code> (if
+ there is a package <code>foo</code>).
+</p>
+<p>
+ Many Bazel commands accept a list of target patterns as arguments,
+ and they all honor the prefix negation operator `<code>-</code>'.
+ This can be used to subtract a set of targets from the set specified
+ by the preceding arguments. (Note that this means order matters.)
+ For example,
+</p>
+<pre>
+ bazel build foo/... bar/...
+</pre>
+<p>
+ means "build all
+ targets beneath <code>foo</code> <i>and</i> all targets
+ beneath <code>bar</code>", whereas
+</p>
+<pre>
+ bazel build -- foo/... -foo/bar/...
+</pre>
+<p>
+ means "build all targets beneath <code>foo</code> <i>except</i>
+ those beneath <code>foo/bar</code>".
+
+ (The <code>--</code> argument is required to prevent the subsequent
+ arguments starting with <code>-</code> from being interpreted as
+ additional options.)
+</p>
+<p>
+ It's important to point out though that subtracting targets this way will not
+ guarantee that they are not built, since they may be dependencies of targets
+ that weren't subtracted. For example, if there were a target
+ <code>//foo:all-apis</code> that among others depended on
+ <code>//foo/bar:api</code>, then the latter would be built as part of
+ building the former.
+</p>
+<p>
+ Targets with <code>tags=["manual"]</code> will not be included in wildcard target patterns (...,
+ :*, :all, etc). You should specify such test targets with explicit target patterns on the command
+ line if you want Bazel to build/test them.
+</p>
+
+<h3 id='fetch'>Fetching external dependencies</h3>
+
+<p>
+ By default, Bazel will download and symlink external dependencies during the
+ build. However, this can be undesirable, either because you'd like to know
+ when new external dependendencies are added or because you'd like to
+ "prefetch" dependencies (say, before a flight where you'll be offline). If you
+ would like to prevent new dependencies from being added during builds, you
+ can specify the <code>--fetch=false</code> flag. Note that this flag only
+ applies to repository rules that do not point to a directory in the local
+ file system. Changes, for example, to <code>local_repository</code>,
+ <code>new_local_repository</code> and Android SDK and NDK repository rules
+ will always take effect regardless of the value <code>--fetch</code> .
+</p>
+
+<p>
+ If you disallow fetching during builds and Bazel finds new external
+ dependencies, your build will fail.
+</p>
+
+<p>
+ You can manually fetch dependencies by running <code>bazel fetch</code>. If
+ you disallow during-build fetching, you'll need to run <code>bazel
+ fetch</code>:
+ <ol>
+ <li>Before you build for the first time.
+ <li>After you add a new external dependency.
+ </ol>
+ Once it has been run, you should not need to run it again until the WORKSPACE
+ file changes.
+</p>
+
+<p>
+ <code>fetch</code> takes a list of targets to fetch dependencies for. For
+ example, this would fetch dependencies needed to build <code>//foo:bar</code>
+ and <code>//bar:baz</code>:
+<pre>
+$ bazel fetch //foo:bar //bar:baz
+</pre>
+</p>
+
+<p>
+ To fetch all external dependencies for a workspace, run:
+<pre>
+$ bazel fetch //...
+</pre>
+</p>
+
+<p>
+ You do not need to run bazel fetch at all if you have all of the tools you are
+ using (from library jars to the JDK itself) under your workspace root.
+ However, if you're using anything outside of the workspace directory then you
+ will need to run <code>bazel fetch</code> before running
+ <code>bazel build</code>.
+</p>
+
+<h3 id='configurations'>Build configurations and cross-compilation</h3>
+
+<p>
+ All the inputs that specify the behavior and result of a given
+ build can be divided into two distinct categories.
+ The first kind is the intrinsic information stored in the BUILD
+ files of your project: the build rule, the values of its attributes,
+ and the complete set of its transitive dependencies.
+ The second kind is the external or environmental data, supplied by
+ the user or by the build tool: the choice of target architecture,
+ compilation and linking options, and other toolchain configuration
+ options. We refer to a complete set of environmental data as
+ a <b>configuration</b>.
+</p>
+<p>
+ In any given build, there may be more than one configuration.
+ Consider a cross-compile, in which you build
+ a <code>//foo:bin</code> executable for a 64-bit architecture,
+ but your workstation is a 32-bit machine. Clearly, the build
+ will require building <code>//foo:bin</code> using a toolchain
+ capable of creating 64-bit executables, but the build system must
+ also build various tools used during the build itself—for example
+ tools that are built from source, then subsequently used in, say, a
+ genrule—and these must be built to run on your workstation.
+ Thus we can identify two configurations: the <b>host
+ configuration</b>, which is used for building tools that run during
+ the build, and the <b>target configuration</b> (or <i>request
+ configuration</i>, but we say "target configuration" more often even
+ though that word already has many meanings), which is
+ used for building the binary you ultimately requested.
+</p>
+<p>
+ Typically, there are many libraries that are prerequisites of both
+ the requested build target (<code>//foo:bin</code>) and one or more of
+ the host tools, for example some base libraries. Such libraries must be built
+ twice, once for the host configuration, and once for the target
+ configuration.<br/>
+ Bazel takes care of ensuring that both variants are built, and that
+ the derived files are kept separate to avoid interference; usually
+ such targets can be built concurrently, since they are independent
+ of each other. If you see progress messages indicating that a given
+ target is being built twice, this is most likely the explanation.
+</p>
+<p>
+ Bazel uses one of two ways to select the host configuration, based
+ on the <code class='flag'>--distinct_host_configuration</code> option. This
+ boolean option is somewhat subtle, and the setting may improve (or
+ worsen) the speed of your builds.
+</p>
+
+<h4><code class='flag'>--distinct_host_configuration=false</code></h4>
+<p>
+ When this option is false, the host and
+ request configurations are identical: all tools required during the
+ build will be built in exactly the same way as target programs.
+ This setting means that no libraries need to be built twice during a
+ single build, so it keeps builds short.
+ However, it does mean that any change to your request configuration
+ also affects your host configuration, causing all the tools to be
+ rebuilt, and then anything that depends on the tool output to be
+ rebuilt too. Thus, for example, simply changing a linker option
+ between builds might cause all tools to be re-linked, and then all
+ actions using them reexecuted, and so on, resulting in a very large rebuild.
+ Also, please note: if your host architecture is not capable of
+ running your target binaries, your build will not work.
+</p>
+<p>
+ If you frequently make changes to your request configuration, such
+ as alternating between <code>-c opt</code> and <code>-c dbg</code>
+ builds, or between simple- and cross-compilation, we do not
+ recommend this option, as you will typically rebuild the majority of
+ your codebase each time you switch.
+</p>
+
+<h4><code class='flag'>--distinct_host_configuration=true</code> <i>(default)</i></h4>
+<p>
+ If this option is true, then instead of using the same configuration
+ for the host and request, a completely distinct host configuration
+ is used. The host configuration is derived from the target
+ configuration as follows:
+</p>
+<ul>
+ <li>Use the same version of Crosstool
+ (<code class='flag'>--crosstool_top</code>) as specified in the request
+ configuration, unless <code class='flag'>--host_crosstool_top</code> is
+ specified.
+ </li>
+ <li>
+ Use the value of <code class="flag">--host_cpu</code> for
+ <code class='flag'>--cpu</code>
+
+ (default: <code>k8</code>).
+ </li>
+ <li>Use the same values of these options as specified in the request
+ configuration:
+ <code class='flag'>--compiler</code>,
+ <code class='flag'>--thin_archives</code>,
+ <code class='flag'>--use_ijars</code>,
+ <code class='flag'>--java_toolchain</code>,
+ If <code class='flag'>--host_crosstool_top</code> is used, then the value of
+ <code class='flag'>--host_cpu</code> is used to look up a
+ <code>default_toolchain</code> in the Crosstool
+ (ignoring <code class='flag'>--compiler</code>) for the host configuration.
+ </li>
+ <li>Use optimized builds for C++ code (<code>-c opt</code>).
+ </li>
+ <li>Generate no debugging information (<code class='flag'>--copt=-g0</code>).
+ </li>
+ <li>Strip debug information from executables and shared libraries
+ (<code class='flag'>--strip=always</code>).
+ </li>
+ <li>Place all derived files in a special location, distinct from
+ that used by any possible request configuration.
+ </li>
+ <li>Suppress stamping of binaries with build data
+ (see <code class='flag'>--embed_*</code> options).
+ </li>
+ <li>All other values remain at their defaults.
+ </li>
+</ul>
+<p>
+ There are many reasons why it might be preferable to select a
+ distinct host configuration from the request configuration.
+ Some are too esoteric to mention here, but two of them are worth
+ pointing out.
+</p>
+<p>
+ Firstly, by using stripped, optimized binaries, you reduce the time
+ spent linking and executing the tools, the disk space occupied by
+ the tools, and the network I/O time in distributed builds.
+</p>
+<p>
+ Secondly, by decoupling the host and request configurations in all
+ builds, you avoid very expensive rebuilds that would result from
+ minor changes to the request configuration (such as changing a linker options
+ does), as described earlier.
+</p>
+<p>
+ That said, for certain builds, this option may be a hindrance. In
+ particular, builds in which changes of configuration are infrequent
+ (especially certain Java builds), and builds where the amount of code that
+ must be built in both host and target configurations is large, may
+ not benefit.
+</p>
+
+<h3 id='correctness'>Correct incremental rebuilds</h3>
+
+<p>
+ One of the primary goals of the Bazel project is to ensure correct
+ incremental rebuilds. Previous build tools, especially those based
+ on Make, make several unsound assumptions in their implementation of
+ incremental builds.
+</p>
+<p>
+ Firstly, that timestamps of files increase monotonically. While
+ this is the typical case, it is very easy to fall afoul of this
+ assumption; syncing to an earlier revision of a file causes that file's
+ modification time to decrease; Make-based systems will not rebuild.
+</p>
+<p>
+ More generally, while Make detects changes to files, it does
+ not detect changes to commands. If you alter the options passed to
+ the compiler in a given build step, Make will not re-run the
+ compiler, and it is necessary to manually discard the invalid
+ outputs of the previous build using <code>make clean</code>.
+</p>
+<p>
+ Also, Make is not robust against the unsuccessful termination of one
+ of its subprocesses after that subprocess has started writing to
+ its output file. While the current execution of Make will fail, the
+ subsequent invocation of Make will blindly assume that the truncated
+ output file is valid (because it is newer than its inputs), and it
+ will not be rebuilt. Similarly, if the Make process is killed, a
+ similar situation can occur.
+</p>
+<p>
+ Bazel avoids these assumptions, and others. Bazel maintains a database
+ of all work previously done, and will only omit a build step if it
+ finds that the set of input files (and their timestamps) to that
+ build step, and the compilation command for that build step, exactly
+ match one in the database, and, that the set of output files (and
+ their timestamps) for the database entry exactly match the
+ timestamps of the files on disk. Any change to the input files or
+ output files, or to the command itself, will cause re-execution of
+ the build step.
+</p>
+<p>
+ The benefit to users of correct incremental builds is: less time
+ wasted due to confusion. (Also, less time spent waiting for
+ rebuilds caused by use of <code>make clean</code>, whether necessary
+ or pre-emptive.)
+</p>
+
+<h4>Build consistency and incremental builds</h4>
+<p>
+ Formally, we define the state of a build as <i>consistent</i> when
+ all the expected output files exist, and their contents are correct,
+ as specified by the steps or rules required to create them. When
+ you edit a source file, the state of the build is said to
+ be <i>inconsistent</i>, and remains inconsistent until you next run
+ the build tool to successful completion. We describe this situation
+ as <i>unstable inconsistency</i>, because it is only temporary, and
+ consistency is restored by running the build tool.
+</p>
+<p>
+ There is another kind of inconsistency that is pernicious: <i>stable
+ inconsistency</i>. If the build reaches a stable inconsistent
+ state, then repeated successful invocation of the build tool does
+ not restore consistency: the build has gotten "stuck", and the
+ outputs remain incorrect. Stable inconsistent states are the main
+ reason why users of Make (and other build tools) type <code>make
+ clean</code>. Discovering that the build tool has failed in this
+ manner (and then recovering from it) can be time consuming and very
+ frustrating.
+</p>
+<p>
+ Conceptually, the simplest way to achieve a consistent build is to
+ throw away all the previous build outputs and start again: make
+ every build a clean build. This approach is obviously too
+ time-consuming to be practical (except perhaps for release
+ engineers), and therefore to be useful, the build tool must be able
+ to perform incremental builds without compromising consistency.
+</p>
+<p>
+ Correct incremental dependency analysis is hard, and as described
+ above, many other build tools do a poor job of avoiding stable
+ inconsistent states during incremental builds. In contrast, Bazel
+ offers the following guarantee: after a successful invocation of the
+ build tool during which you made no edits, the build will be in a
+ consistent state. (If you edit your source files during a build,
+ Bazel makes no guarantee about the consistency of the result of the
+ current build. But it does guarantee that the results of
+ the <i>next</i> build will restore consistency.)
+</p>
+<p>
+ As with all guarantees, there comes some fine print: there are some
+ known ways of getting into a stable inconsistent state with Bazel.
+ We won't guarantee to investigate such problems arising from deliberate
+ attempts to find bugs in the incremental dependency analysis, but we
+ will investigate and do our best to fix all stable inconsistent
+ states arising from normal or "reasonable" use of the build tool.
+</p>
+<p>
+ If you ever detect a stable inconsistent state with Bazel, please report a bug.
+
+</p>
+
+<h4 id='sandboxing'>Sandboxed execution</h4>
+<p>
+ Bazel uses sandboxes to guarantee that actions run hermetically<sup>1</sup> and correctly.
+ Bazel runs <i>Spawn</i>s (loosely speaking: actions) in sandboxes that only contain the minimal
+ set of files the tool requires to do its job. Currently sandboxing works on Linux 3.12 or newer
+ with the <code>CONFIG_USER_NS</code> option enabled.
+</p>
+<p>
+ Bazel will print a warning if your system does not support sandboxing to alert you to the fact
+ that builds are not guaranteed to be hermetic and might affect the host system in unknown ways.
+ To disable this warning you can pass the <code>--ignore_unsupported_sandboxing</code> flag to
+ Bazel.
+</p>
+
+<p>
+ On some platforms such as <a href="https://cloud.google.com/container-engine/">Google Container
+ Engine</a> cluster nodes or Debian, user namespaces are deactivated by default due to security
+ concerns. This can be checked by looking at the file
+ <code>/proc/sys/kernel/unprivileged_userns_clone</code>: if it exists and contains a 0, then
+ user namespaces can be activated with <code>sudo sysctl kernel.unprivileged_userns_clone=1</code>.
+</p>
+<p>
+ In some cases, the Bazel sandbox fails to execute rules because of the system setup. The symptom
+ is generally a failure that output a message similar to
+ <code>namespace-sandbox.c:633: execvp(argv[0], argv): No such file or directory</code>. In that
+ case, try to deactivate the sandbox for genrules with <code>--genrule_strategy=standalone</code>
+ and for other rules with <code>--spawn_strategy=standalone</code>. Also please report a bug on our
+ issue tracker and mention which Linux distribution you're using so that we can investigate and
+ provide a fix in a subsequent release.
+</p>
+
+<p>
+ <sup>1</sup>: Hermeticity means that the action only uses its declared input files and no other
+ files in the filesystem, and it only produces its declared output files.
+</p>
+
+<h3 id='clean'>Deleting the outputs of a build</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>
+
+<h3 id='phases'>Phases of a build</h3>
+
+<p>
+ In Bazel, a build occurs in three distinct phases; as a user,
+ understanding the difference between them provides insight into the
+ options which control a build (see below).
+</p>
+
+<h4 id='loading-phase'>Loading phase</h4>
+<p>
+ The first is <b>loading</b> during which all the necessary BUILD
+ files for the initial targets, and their transitive closure of
+ dependencies, are loaded, parsed, evaluated and cached.
+</p>
+<p>
+ For the first build after a Bazel server is started, the loading
+ phase typically takes many seconds as many BUILD files are loaded
+ from the file system. In subsequent builds, especially if no BUILD
+ files have changed, loading occurs very quickly.
+</p>
+<p>
+ Errors reported during this phase include: package not found, target
+ not found, lexical and grammatical errors in a BUILD file,
+ and evaluation errors.
+</p>
+
+<h4 id='analysis-phase'>Analysis phase</h4>
+<p>
+ The second phase, <b>analysis</b>, involves the semantic analysis
+ and validation of each build rule, the construction of a build
+ dependency graph, and the determination of exactly what work is to
+ be done in each step of the build.
+</p>
+<p>
+ Like loading, analysis also takes several seconds when computed in
+ its entirety. However, Bazel caches the dependency graph from
+ one build to the next and only reanalyzes what it has to, which can
+ make incremental builds extremely fast in the case where the
+ packages haven't changed since the previous build.
+</p>
+<p>
+ Errors reported at this stage include: inappropriate dependencies,
+ invalid inputs to a rule, and all rule-specific error messages.
+</p>
+<p>
+ The loading and analysis phases are fast because
+ Bazel avoids unnecessary file I/O at this stage, reading only BUILD
+ files in order to determine the work to be done. This is by design,
+ and makes Bazel a good foundation for analysis tools, such as
+ Bazel's <a href='#query'>query</a> command, which is implemented
+ atop the loading phase.
+</p>
+
+<h4 id='execution-phase'>Execution phase</h4>
+<p>
+ The third and final phase of the build is <b>execution</b>. This
+ phase ensures that the outputs of each step in the build are
+ consistent with its inputs, re-running compilation/linking/etc. tools as
+ necessary. This step is where the build spends the majority of
+ its time, ranging from a few seconds to over an hour for a large
+ build. Errors reported during this phase include: missing source
+ files, errors in a tool executed by some build action, or failure of a tool to
+ produce the expected set of outputs.
+</p>
+
+
+<h2>Options</h2>
+
+<p>
+ The following sections describe the options available during a
+ build. When <code class='flag'>--long</code> is used on a help command, the on-line
+ help messages provide summary information about the meaning, type and
+ default value for each option.
+</p>
+
+<p>
+ Most options can only be specified once. When specified multiple times, the
+ last instance wins. Options that can be specified multiple times are
+ identified in the on-line help with the text 'may be used multiple times'.
+</p>
+
+<h3>Options that affect how packages are located</h3>
+
+<p>
+ See also the <a href='#flag--show_package_location'><code class='flag'>--show_package_location</code></a>
+ option.
+</p>
+
+<h4 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>
+
+<h4 id='flag--deleted_packages'><code class='flag'>--deleted_packages</code></h4>
+<p>
+ This option specifies a comma-separated list of packages which Bazel
+ should consider deleted, and not attempt to load from any directory
+ on the package path. This can be used to simulate the deletion of packages without
+ actually deleting them.
+</p>
+
+<h3 id='checking-options'>Error checking options</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--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_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--output_filter'><code class='flag'>--output_filter <var>regex</var></code></h4>
+<p>
+ The <code class='flag'>--output_filter</code> option will only show build and compilation
+ warnings for targets that match the regular expression. If a target does not
+ match the given regular expression and its execution succeeds, its standard
+ output and standard error are thrown away. This option is intended to be used
+ to help focus efforts on fixing warnings in packages under development. Here
+ are some typical values for this option:
+</p>
+<table>
+ <tr>
+ <td><code class='flag'>--output_filter=</code></td>
+ <td>Show all output.</td>
+ </tr>
+ <tr>
+ <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td>
+ <td>Show the output for the specified packages.</td>
+ </tr>
+ <tr>
+ <td><code class='flag'>--output_filter='^//((?!(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=DONT_MATCH_ANYTHING</code></td>
+ <td>Don't show output.</td>
+ </tr>
+</table>
+
+<h4 id='flag--analysis_warnings_as_errors'><code>--[no]analysis_warnings_as_errors</code></h4>
+<p>
+ When this option is enabled, visible analysis warnings (as specified by
+ the output filter) are treated as errors, effectively preventing the build
+ phase from starting. This feature can be used to enable strict builds that
+ do not allow new warnings to creep into a project.
+</p>
+
+<h3 id='flags-options'>Flags options</h3>
+<p>
+ These options control which options Bazel will pass to other tools.
+</p>
+
+<h4 id='flag--copt'><code class='flag'>--copt <var>gcc-option</var></code></h4>
+<p>
+ This option takes an argument which is to be passed to gcc.
+ The argument will be passed to gcc whenever gcc 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 gcc 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, gcc 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>gcc-option</var></code></h4>
+<p>
+ This option takes an argument which is to be passed to gcc 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--conlyopt'><code class='flag'>--conlyopt <var>gcc-option</var></code></h4>
+<p>
+ This option takes an argument which is to be passed to gcc 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 gcc command line <em>after</em> these options.
+</p>
+
+<h4 id='flag--cxxopt'><code class='flag'>--cxxopt <var>gcc-option</var></code></h4>
+<p>
+ This option takes an argument which is to be passed to gcc 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 gcc 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 gcc 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 gcc 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 iff 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.
+</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--lipo'><code class='flag'>--lipo (off|binary)</code></h4>
+<p>
+ The <code class='flag'>--lipo=binary</code> option enables
+
+ LIPO
+ (Lightweight Inter-Procedural Optimization). LIPO is an extended C/C++ optimization technique
+ that optimizes code across different object files. It involves compiling each C/C++ source
+ file differently for every binary. This is in contrast to normal compilation where compilation
+ outputs are reused. This means that LIPO is more expensive than normal compilation.
+</p>
+<p>
+ This option only has an effect when FDO is also enabled (see the
+ <a href="#flag--fdo_instrument">--fdo_instrument</a> and
+ <a href="#flag--fdo_optimize">--fdo_options</a>).
+ Currently LIPO is only supported when building a single <code>cc_binary</code> rule.
+</p>
+<p>Setting <code>--lipo=binary</code> implicitly sets
+ <code><a href="#flag--dynamic_mode">--dynamic_mode</a>=off</code>.
+</p>
+
+<h4 id='flag--lipo_context'><code class='flag'>--lipo_context
+ <var>context-binary</var></code></h4>
+<p>
+ Specifies the label of a <code>cc_binary</code> rule that was used to generate
+ the profile information for LIPO that was given to
+ the <a href='#flag--fdo_optimize'><code class='flag'>--fdo_optimize</code></a> option.
+</p>
+<p>
+ Specifying the context is mandatory when <code>--lipo=binary</code> is set.
+ Using this option implicitly also sets
+ <code><a href="#flag--linkopt">--linkopt</a>=-Wl,--warn-unresolved-symbols</code>.
+</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 also output
+ a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold
+ option) that logs the number of symbols from each .o input that were used in
+ the binary. This 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>
+
+<h4 id='flag--javawarn'><code class='flag'>--javawarn (all|cast|deprecation|empty|unchecked|fallthrough|path|rawtypes|serial|finally|overrides)</code></h4>
+<p>
+ This option is used to enable Java warnings across an entire build. It takes
+ an argument which is a javac warning to be enabled, overriding any other Java
+ options that disable the given warning. The arguments to this option are
+ appended to the "-Xlint:" flag to javac, and must be exactly one of
+ the listed warnings.
+</p>
+<p>
+ For example:
+</p>
+<pre>
+ % bazel build --javawarn="deprecation" --javawarn="unchecked" //java/...
+</pre>
+<p>
+ Note that changing <code class='flag'>--javawarn</code> settings will force a recompilation
+ of all affected classes.
+</p>
+
+<h3 id='semantics-options'>Semantics options</h3>
+<p>
+ These options affect the build commands and/or the output file contents.
+</p>
+
+<h4 id='flag--compilation_mode'><code class='flag'>--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4>
+<p>
+ This option 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,
+ libc version, and target CPU is allowed only if it has been specified
+ in the currently used CROSSTOOL file.
+</p>
+
+<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--experimental_skip_static_outputs'><code class='flag'>--experimental_skip_static_outputs</code></h4>
+<p>
+ The <code class='flag'>--experimental_skip_static_outputs</code> option causes all
+ statically-linked C++ binaries to <b>not</b> be output in any meaningful
+ way.
+
+</p>
+<p>
+ If you set this flag, you must also
+ set <a href="#flag--distinct_host_configuration"><code class='flag'>--distinct_host_configuration</code></a>.
+ It is also inherently incompatible with running tests — don't use it for
+ that. This option is experimental and may go away at any time.
+</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--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--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,
+ libc version, and target CPU are allowed.
+</p>
+
+<h4 id='flag--glibc'><code class='flag'>--glibc <var>version</var></code></h4>
+<p>
+ This option specifies the version of glibc that the target should be linked
+ against. If you want to build with a custom crosstool, you should use a
+ CROSSTOOL file instead of specifying this flag. In that case, Bazel will use
+ the CROSSTOOL file and the following options where appropriate:
+ <ul>
+ <li><a href="#flag--cpu"><code class='flag'>--cpu</code></a></li>
+
+ </ul>
+</p>
+<p>
+ Note that only certain combinations of crosstool version, compiler version,
+ glibc version, and target CPU are allowed.
+</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--javabase'><code class='flag'>--javabase (<var>path</var>|<var>label</var>)</code></h4>
+<p>
+ This options set the label or the path of the base Java installation to use
+ for running JavaBuilder, SingleJar, and is also used for bazel run and inside
+ Java binaries built by <code>java_binary</code> rules. The various
+ <a href='be/make-variables.html'>"Make" variables</a> for
+ Java (<code>JAVABASE</code>, <code>JAVA</code>, <code>JAVAC</code> and
+ <code>JAR</code>) are derived from this option.
+</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'>Build strategy options</h3>
+<p>
+ These options affect how Bazel will execute the build.
+ They should not have any significant effect on the output files
+ generated by the build. Typically their main effect is on the
+ speed on the build.
+</p>
+
+<h4 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.
+ </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>
+
+</ul>
+
+<h4 id='flag--genrule_strategy'><code class='flag'>--genrule_strategy <var>strategy</var></code></h4>
+<p>
+ This option controls where and how genrules are executed.
+</p>
+<ul>
+
+ <li>
+ <code>standalone</code> causes genrules to run as local subprocesses.
+ </li>
+ <li>
+ <code>sandboxed</code> causes genrules to run inside a sandbox on the local machine.
+ This requires that all input files are listed as direct dependencies in
+ the <code>srcs</code> attribute, and the program(s) executed are listed
+ in the <code>tools</code> attribute.
+ This is the default for Bazel on systems that support sandboxed execution.
+ </li>
+
+</ul>
+
+<h4 id='flag--local_genrule_timeout_seconds'><code class='flag'>--local_genrule_timeout_seconds <var>seconds</var></code></h4>
+<p>Sets a timeout value for local genrules with the given number of seconds.</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. The default is 200.
+</p>
+<p>
+ Note that the number of concurrent jobs that Bazel will run
+ is determined not only by the <code class='flag'>--jobs</code> setting, but also
+ by Bazel's scheduler, which tries to avoid running concurrent jobs
+ that will use up more resources (RAM or CPU) than are available,
+ based on some (very crude) estimates of the resource consumption
+ of each job. The behavior of the scheduler can be controlled by
+ the <code class='flag'>--ram_utilization_factor</code> option.
+</p>
+
+<h4 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--ram_utilization_factor'><code class='flag'>--ram_utilization_factor</code> <var>percentage</var></h4>
+<p>
+ This option, which takes an integer argument, specifies what percentage
+ of the system's RAM Bazel should try to use for its subprocesses.
+ This option affects how many processes Bazel will try to run
+ in parallel. The default value is 67.
+ If you run several Bazel builds in parallel, using a lower
+ value for this option may avoid thrashing and thus improve overall
+ throughput. Using a value higher than the default is NOT recommended. Note
+ that Bazel's estimates are very coarse, so the actual RAM usage may be much
+ higher or much lower than specified. Note also that this option does not
+ affect the amount of memory that the Bazel server itself will use.
+</p>
+
+<h4 id='flag--local_resources'><code class='flag'>--local_resources</code> <var>availableRAM,availableCPU,availableIO</var></h4>
+<p>
+ This option, which takes three comma-separated floating point arguments,
+specifies the amount of local resources that Bazel can take into
+consideration when scheduling build and test activities. Option expects amount of
+available RAM (in MB), number of CPU cores (with 1.0 representing single full
+core) and workstation I/O capability (with 1.0 representing average
+workstation). By default Bazel will estimate amount of RAM and number of CPU
+cores directly from system configuration and will assume 1.0 I/O resource.
+</p>
+<p>
+ If this option is used, Bazel will ignore --ram_utilization_factor.
+</p>
+
+<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4>
+<p>
+ This option, which is currently enabled by default, specifies
+ whether the runfiles symlinks for tests and
+ <code>cc_binary</code> targets 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.
+
+ Within Bazel's output tree, the
+ runfiles symlink tree is typically rooted as a sibling of the corresponding
+ binary or test.
+</p>
+
+<p>
+ When tests (or applications) are executed, their
+ run-time data dependencies are gathered together in one place, and
+ may be accessed by the test using paths of the form
+ <code>$TEST_SRCDIR/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>
+<p>
+ The <code class='flag'>--build_runfile_links</code> flag controls the
+ construction of the tree of symbolic links (for C++ applications and
+ tests only). The reasons only C++ non-test rules are affected are numerous
+ and subtle: C++ builds are more likely to be slower due to runfiles;
+ no C++ host tools (tools that run during the build) need their runfiles,
+ so this option can be used by the host configuration; and other rules
+ (notably Python) need their runfiles for other purposes besides test
+ execution.
+</p>
+
+<h4 id='flag--discard_analysis_cache'>
+ <code class='flag'>--[no]discard_analysis_cache</code></h4>
+<p>
+ When this option is enabled, Bazel will discard the analysis cache
+ right before execution starts, thus freeing up additional memory
+ (around 10%) for the <a href="#execution-phase">execution phase</a>.
+ The drawback is that further incremental builds will be slower.
+</p>
+
+<h4 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--thin_archives'><code class='flag'>--[no]thin_archives</code></h4>
+<p>
+ This option enables use of <i>thin archives</i>, an optimization which avoids
+ duplicating the content of object files when they are placed in archive
+ libraries; the archive library references the object file by name, and the
+ linker follows this reference as needed. This may give a speedup for C++
+ builds, especially when building a single large executable from clean.
+</p>
+
+<p>
+ This option is enabled by default;
+ use <code class='flag'>--nothin_archives</code> to disable.
+</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 options</h3>
+<p>
+ These options determine what to build or test.
+</p>
+
+<h4 id="nobuild"><code class='flag'>--[no]build</code></h4>
+<p>
+ This option causes the execution phase of the build to occur; it is
+ on by default. When it is switched off, the execution phase is
+ skipped, and only the first two phases, loading and analysis, occur.
+</p>
+<p>
+ This option can be useful for validating BUILD files and detecting
+ errors in the inputs, without actually building anything.
+</p>
+
+<h4 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 gcc 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 gcc'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--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>Verbosity options: options that control what Bazel prints</h3>
+
+These options control the verbosity of Bazel's output,
+either to the terminal, or to additional log files.
+
+<h4 id='flag--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='#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>
+ >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
+ (cd /home/jrluser/.cache/bazel/_bazel_jrluser/4c084335afceb392cfbe7c31afee3a9f/bazel && \
+ exec env - \
+ /usr/bin/gcc -o bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes '-Wl,--build-id=md5' '-Wl,--hash-style=gnu' -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>
+ 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>
+
+<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='misc_build_options'>Miscellaneous options</h3>
+
+<h4 id='flag--symlink_prefix'><code class='flag'>--symlink_prefix <var>string</var></code></h4>
+<p>
+ Changes the prefix of the generated convenience symlinks. The
+ default value for the symlink prefix is <code>bazel-</code> which
+ will create the symlinks <code>bazel-bin</code>, <code>bazel-testlogs</code>, and
+ <code>bazel-genfiles</code>.
+</p>
+<p>
+ If the symbolic links cannot be created for any reason, a warning is
+ issued but the build is still considered a success. In particular,
+ this allows you to build in 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-<workspace></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>
+
+<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='#scripting'>scripting</a> section of this manual.
+ In particular, the following options are strongly recommended:
+</p>
+<ul>
+ <li><a href='#bazelrc'><code class='flag'>--bazelrc=/dev/null</code></a></li>
+ <li><a href='#flag--batch'><code class='flag'>--batch</code></a></li>
+</ul>
+
+<p>
+ These options (q.v.) 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 with Bazel</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 then the test's actual execution time. While a test's
+timeout should be set such that it is not flaky, a test that has a highly
+over-generous timeout can hide real problems that crop up unexpectedly.
+</p>
+<p>
+For instance, a test that normally executes in a minute or two should not have
+a timeout of ETERNAL or LONG as these are much, much too generous.
+
+ 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
+ "default"), 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 the test (not to the test runner). This
+ option can be used multiple times to pass several arguments, e.g.
+ <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>.
+</p>
+
+<h4 id='flag--test_env'><code class='flag'>--test_env <var>variable</var>=<i>value</i></code>
+ OR
+ <code class='flag'>--test_env <var>variable</var></code></h4>
+<p>
+ Specifies additional variables that must be injected into the test
+ environment for each test. If <var>value</var> is not specified it will be
+ inherited from the shell environment used to start the <code>bazel test</code>
+ command.
+</p>
+<p>
+ The environment can be accessed from within a test by using
+ <code>System.getenv("var")</code> (Java),
+ <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/valgrind
+ --run_under=/usr/bin/strace
+ --run_under='/usr/bin/strace -c'
+ --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_blaze_test">Other options for <code>bazel test</code></h4>
+<p>
+ The syntax and the remaining options are exactly like
+ <a href='#build'>bazel build</a>.
+</p>
+
+
+
+<h2 id='run'>Running executables with Bazel</h2>
+<p>
+ The <code>bazel run</code> command is similar to <code>bazel build</code>, except
+ it is used to build and run a single target. Here is a typical session:
+</p>
+<pre>
+ % bazel run -- java/myapp:myapp --arg1 --arg2
+ Welcome to Bazel
+ INFO: Loading package: java/myapp
+ INFO: Loading package: foo/bar
+ INFO: Loading complete. Analyzing...
+ INFO: 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>
+ Bazel closes stdin, so you can't use <code>bazel run</code>
+ if you want to start an interactive program or pipe data to it.
+</p>
+
+<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>
+
+<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, but without the setup documented on the page
+<a href='test-encyclopedia.html'>Writing Tests</a>, so that the test runs
+in an environment closer to the current shell environment. Note that none of the
+--test_* arguments have an effect when running a test in this manner.
+</p>
+
+<h2 id='query'>Querying the dependency graph with Bazel</h2>
+
+<p>
+ Bazel includes a query language for asking questions about the
+ dependency graph used during the build. The query tool is an
+ invaluable aid to many software engineering tasks.
+</p>
+<p>
+ The query language is based on the idea of
+ algebraic operations over graphs; it is documented in detail in
+
+ <a href="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]host_deps</code> option,
+ enabled by default, causes dependencies on "host
+ configuration" targets 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='misc'>Miscellaneous Bazel commands and options</h2>
+
+<h3 id='help'>The <code>help</code> command</h3>
+
+<p>
+ The <code>help</code> command provides on-line help. By default, it
+ shows a summary of available commands and help topics, as shown in
+ the <a href='#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'>The <code>shutdown</code> command</h3>
+
+<p>
+ Bazel server processes (see <a href='#client/server'>Client/server
+ implementation</a>) may be stopped by using the <code>shutdown</code>
+ command. This command causes the Bazel server to exit as soon as it
+ becomes idle (i.e. after the completion of any builds or other
+ commands that are currently in progress).
+
+ Bazel servers stop themselves after an idle timeout, so this command
+ is rarely necessary; however, it can be useful in scripts when it is
+ known that no further builds will occur in a given workspace.
+</p>
+<p>
+ <code>shutdown</code> accepts one
+ option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which
+ requires an integer argument (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'>The <code>info</code> command</h3>
+
+<p>
+ The <code>info</code> command prints various values associated with
+ the Bazel server instance, or with a specific build configuration.
+ (These may be used by scripts that drive a build.)
+</p>
+
+<p>
+ The <code>info</code> command also permits a single (optional)
+ argument, which is the name of one of the keys in the list below.
+ In this case, <code>bazel info <var>key</var></code> will print only
+ the value for that one key. (This is especially convenient when
+ scripting Bazel, as it avoids the need to pipe the result
+ through <code>sed -ne /key:/s/key://p</code>:
+</p>
+
+<h4>Configuration-independent data</h4>
+<ul>
+ <li><code>release</code>: the release label for this Bazel
+ instance, or "development version" if this is not a released
+ binary.
+ </li>
+ <li><code>workspace</code> the absolute path to 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-<workspace></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>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-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 BINMODE
+ -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>
+
+<h3 id='version'>The <code>version</code> command</h3>
+
+<p>
+ The version command prints version details about the built Bazel
+ binary, including the changelist at which it was built and the date.
+ These are particularly useful in determining if you have the latest
+ Bazel, 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>
+
+<h3 id='mobile-install'>The <code>mobile-install</code> command</h3>
+<p>
+ The <code>mobile-install</code> command installs apps to mobile devices.
+ Currently only Android devices running ART are supported.
+</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. We are working to come up with a better
+ solution.
+</p>
+<h4 id='flag--adb'><code class='flag'>--adb</code></h4>
+<p>
+ Indicates the <code>adb</code> binary to be used. When unspecified, the binary
+ in the repository is used.
+</p>
+<h4 id='flag--adb_arg'><code class='flag'>--adb_arg</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.
+ Example:
+<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
+</pre>
+will invoke <code>adb</code> as
+<pre>
+adb -s deadbeef install ...
+</pre>
+
+</p>
+
+<h3 id='analyze-profile'>The <code>analyze-profile</code> command</h3>
+
+<p>
+ The <code>analyze-profile</code> command analyzes data previously gathered
+ during the build using <code class='flag'>--profile</code> option. It provides several
+ options to either perform analysis of the build execution or export data in
+ the specified format.
+
+</p>
+<p>
+ The following options are supported:
+</p>
+<ul>
+ <li><code id='flag--dump'>--dump=text</code> displays all gathered data in a
+ <a href='#dump-text-format'>human-readable format</a></li>
+ <li><code>--dump=raw</code> displays all gathered data in a
+ <a href='#dump-raw-format'>script-friendly format</a></li>
+ <li><code id='flag--html'>--html</code> generates an <a href='#dump-html-format'>HTML file</a> visualizing the
+ actions and rules executed in the build, as well as summary statistics for the build
+ <ul>
+ <li><code id='flag--html_details'>--html_details</code> adds more fine-grained
+ information on actions and rules to the HTML visualization</li>
+ </ul>
+ </li>
+</ul>
+
+<p>
+ See the section on <a href='#profiling'>Troubleshooting performance by profiling</a> for
+ format details and usage help.
+
+</p>
+
+<h3 id='canonicalize'>The <code>canonicalize-flags</code> command</h3>
+
+<p>
+ The <code>canonicalize-flags</code> command, which takes a list of options for
+ a Bazel command and returns a list of options that has the same effect. The
+ new list of options is canonical, i.e., two lists of options with the same
+ effect are canonicalized to the same new list.
+</p>
+<p>
+ The <code class='flag'>--for_command</code> option can be used to select between different
+ commands. At this time, only <code>build</code> and <code>test</code> are
+ supported. Options that the given command does not support cause an error.
+</p>
+<p>
+ Note that a small number of options cannot be reordered, because Bazel cannot
+ ensure that the effect is identical.
+</p>
+
+<h3 id='startup_options'>Bazel startup options</h3>
+
+<p>
+ The options described in this section affect the startup of the Java
+ virtual machine used by Bazel server process, and they apply to all
+ subsequent commands handled by that server. If there is an already
+ running Bazel server and the startup options do not match, it will
+ be restarted.
+</p>
+<p>
+ All of the options described in this section must be specified using the
+ <code class='flag'>--key=value</code> or <code class='flag'>--key value</code>
+ syntax. Also, these options must appear <i>before</i> the name of the Bazel
+ command.
+</p>
+
+<h4 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_jrluser/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>
+ % bazel --output_base /tmp/1 build //foo & bazel --output_base /tmp/2 build //bar
+</pre>
+<p>
+ In this command, the two Bazel commands run concurrently (because of
+ the shell <code>&</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>
+ By default, the <code>output_base</code> value is chosen to as to
+ avoid conflicts between multiple users building in the same workspace directory.
+ In some situations, though, it is desirable to build from a directory
+ shared between multiple users; release engineers often do this. In
+ those cases it may be useful to deliberately override the default so
+ as to ensure "conflicts" (i.e., sharing) between multiple users.
+ Use the <code class='flag'>--output_user_root</code> option to achieve this: the
+ output base is placed in a subdirectory of the output user root,
+ with a unique name based on the workspace, so the result of using an
+ output user root that is not a function of <code>$USER</code> is
+ sharing. Of course, it is important to ensure (via umask and group
+ membership) that all the cooperating users can read/write each
+ others files.
+</p>
+<p>
+ If the <code class='flag'>--output_base</code> option is specified, it overrides
+ using <code class='flag'>--output_user_root</code> to calculate the output base.
+</p>
+<p>
+ The install base location is also calculated based on
+ <code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded
+ binaries.
+</p>
+<p>
+ You can also use the <code class='flag'>--output_user_root</code> option to choose an
+ alternate base location for all of Bazel's output (install base and output
+ base) if there is a better location in your filesystem layout.
+</p>
+
+<h4 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, etc. To pass
+ JVM options to executable Java programs, whether run by <code>bazel
+ run</code> or on the command-line, you should use
+ the <code>--jvm_flags</code> argument which
+ all <code>java_binary</code> and <code>java_test</code> programs
+ support. Alternatively for tests, use <code>bazel
+ test --test_arg=--jvm_flags=foo ...</code>.
+</p>
+
+<h4 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--batch'><code class='flag'>--batch</code></h4>
+<p>
+ This switch will cause bazel to be run in batch mode, instead of the
+ standard client/server mode described <a href='#client/server'>above</a>.
+ Doing so provides more predictable semantics with respect to signal handling,
+ job control, and environment variable inheritance, 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, compared to client/server mode.
+ Among other things, the build file cache is memory-resident, so it is not
+ preserved between sequential batch invocations.
+ Therefore, using batch mode often makes more sense in cases where performance
+ is less critical, such as continuous builds.
+</p>
+
+<h4 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).
+</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--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. Note that it is currently
+ only possible to provide these options on the command line, not in the rc
+ files. Can be specified multiple times to add flags from several
+ config sections.
+</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>
+
+<h2 id='scripting'>Calling Bazel from scripts</h2>
+
+<p>
+ Bazel can be called from scripts in order to perform a build, run
+ tests or query the dependency graph. Bazel has been designed to
+ enable effective scripting, but this section lists some details to
+ bear in mind to make your scripts more robust.
+</p>
+
+<h3>Choosing the output base</h3>
+
+<p>
+ The <code class='flag'>--output_base</code> option controls where the Bazel process should
+ write the outputs of a build to, as well as various working files used
+ internally by Bazel, one of which is a lock that guards against
+ concurrent mutation of the output base by multiple Bazel processes.
+</p>
+<p>
+ Choosing the correct output base directory for your script depends
+ on several factors. If you need to put the build outputs in a
+ specific location, this will dictate the output base you need to
+ use. If you are making a "read only" call to Bazel
+ (e.g. <code>bazel query</code>), the locking factors will be more important.
+ In particular, if you need to run multiple instances of your script
+ concurrently, you will need to give each one a different (or random) output
+ base.
+</p>
+<p>
+ If you use the default output base value, you will be contending for
+ the same lock used by the user's interactive Bazel commands. If the
+ user issues long-running commands such as builds, your script will
+ have to wait for those commands to complete before it can continue.
+</p>
+
+<h3>Server or no server?</h3>
+
+<p>
+ By default, Bazel uses a long-running <a
+ href='#client/server'>server process</a> as an optimization; this
+ behavior can be disabled using the <a
+ href='#flag--batch'><code class='flag'>--batch</code></a> option. There's no hard and
+ fast rule about whether or not your script should use a server, but
+ in general, the trade-off is between performance and reliability.
+ The server mode makes a sequence of builds, especially incremental
+ builds, faster, but its behavior is more complex and prone to
+ failure. We recommend in most cases that you use batch mode unless
+ the performance advantage is critical.
+</p>
+<p>
+ If you do use the server, don't forget to call <code>shutdown</code>
+ when you're finished with it, or, specify
+ <code class='flag'>--max_idle_secs=5</code> so that idle servers shut themselves
+ down promptly.
+</p>
+
+<h3>What exit code will I get?</h3>
+
+<p>
+ Bazel attempts to differentiate failures due to the source code under
+consideration from external errors that prevent Bazel from executing properly.
+Bazel execution can result in following exit codes:
+</p>
+
+<b>Exit Codes common to all commands:</b>
+<ul>
+ <li><code>0</code> - Success</li>
+ <li><code>2</code> - Command Line Problem, Bad or Illegal flags or command
+ combination, or Bad Environment Variables. Your command line must be
+ modified.</li>
+ <li><code>8</code> - Build Interrupted but we terminated with an orderly shutdown.</li>
+ <li><code>32</code> - External Environment Failure not on this machine.</li>
+ <li><code>33</code> - OOM failure. You need to modify your command line.</li>
+
+ <li><code>34</code> - Reserved for Google-internal use.</li>
+ <li><code>35</code> - Reserved for Google-internal use.</li>
+ <li><code>36</code> - Local Environmental Issue, suspected permanent.</li>
+ <li><code>37</code> - Unhandled Exception / Internal Bazel Error.</li>
+ <li><code>38</code> - Reserved for Google-internal use.</li>
+ <li><code>40-44</code> - Reserved for errors in Bazel's command line launcher,
+ <code>bazel.cc</code> that are not command line
+ related. Typically these are related to bazel server
+ being unable to launch itself.</li>
+</ul>
+
+<b>Return codes for commands <code>bazel build</code>, <code>bazel test</code>.</b>
+<ul>
+ <li><code>1</code> - Build failed.</li>
+ <li><code>3</code> - Build OK, but some tests failed or timed out.</li>
+ <li><code>4</code> - Build successful but no tests were found even though
+ testing was requested.</li>
+</ul>
+
+<b>For <code>bazel run</code>:</b>
+<ul>
+ <li><code>1</code> - Build failed.</li>
+ <li><code>6</code> - Run command failure. The executed subprocess returned a
+ non-zero exit code. The actual subprocess exit code is
+ given in stderr.</li>
+</ul>
+
+
+<b>For
+
+ <code>bazel query</code>:</b>
+<ul>
+ <li><code>3</code> - Partial success, but the query encountered 1 or more
+ errors in the input BUILD file set and therefore the
+ results of the operation are not 100% reliable.
+ This is likely due to a <code class='flag'>--keep_going</code> option
+ on the command line.</li>
+ <li><code>7</code> - Command failure.</li>
+</ul>
+
+<p>
+ Future Bazel versions may add additional exit codes, replacing generic failure
+ exit code <code>1</code> with a different non-zero value with a particular
+ meaning. However, all non-zero exit values will always constitute an error.
+</p>
+
+<h3>Reading the .bazelrc file</h3>
+
+<p>
+ By default, Bazel will read the <a
+ href='#bazelrc'><code>.bazelrc</code> file</a> from the base workspace
+ directory or the user's home directory. Whether or not this is
+ desirable is a choice for your script; if your script needs to be
+ perfectly hermetic (e.g. when doing release builds), you should
+ disable reading the .bazelrc file by using the option
+ <code class='flag'>--bazelrc=/dev/null</code>. If you want to perform a build
+ using the user's preferred settings, the default behavior is better.
+</p>
+
+<h3>Command log</h3>
+
+<p>
+ The Bazel output is also available in a command log file which you can
+ find with the following command:
+</p>
+
+<pre>
+% bazel info command_log
+</pre>
+
+<p>
+ The command log file contains the interleaved stdout and stderr streams
+ of the most recent Bazel command. Note that running <code>bazel info</code>
+ will overwrite the contents of this file, since it then becomes the most
+ recent Bazel command. However, the location of the command log file will
+ not change unless you change the setting of the <code class='flag'>--output_base</code>
+ or <code class='flag'>--output_user_root</code> options.
+</p>
+
+<h3>Parsing output</h3>
+
+<p>
+ The Bazel output is quite easy to parse for many purposes. Two
+ options that may be helpful for your script are
+ <code class='flag'>--noshow_progress</code> which suppresses progress messages,
+ and <code class='flag'>--show_result <var>n</var></code>, which controls whether
+ or not "build up-to-date" messages are printed; these messages may
+ be parsed to discover which targets were successfully built, and the
+ location of the output files they created. Be sure to specify a
+ very large value of <i>n</i> if you rely on these messages.
+</p>
+
+<h2 id='profiling'>Troubleshooting performance by profiling</h2>
+
+<p>
+ The first step in analyzing the performance of your build is to profile your build with the
+ <a href='#flag--profile'><code class='flag'>--profile</code></a> option.
+</p>
+
+<p>
+ The file generated by the <a href='#flag--profile'><code class='flag'>--profile</code></a>
+ command is a binary file. Once you have generated this binary profile, you can analyze it using
+ Bazel's <a href='#analyze-profile'><code>analyze-profile</code></a> command. By default, it will
+ print out summary analysis information for each of the specified profile datafiles. This includes
+ cumulative statistics for different task types for each build phase and an analysis of the
+ critical execution path.
+</p>
+
+<p>
+ The first section of the default output describes an overview of the time spent on the different
+ build phases:
+</p>
+<pre>
+=== PHASE SUMMARY INFORMATION ===
+
+Total launch phase time 6.00 ms 0.01%
+Total init phase time 864 ms 1.11%
+Total loading phase time 21.841 s 28.05%
+Total analysis phase time 5.444 s 6.99%
+Total preparation phase time 155 ms 0.20%
+Total execution phase time 49.473 s 63.54%
+Total finish phase time 83.9 ms 0.11%
+Total run time 77.866 s 100.00%
+</pre>
+
+<p>
+ The following sections show the execution time of different tasks happening during a particular
+ phase:
+</p>
+<pre>
+=== INIT PHASE INFORMATION ===
+
+Total init phase time 864 ms
+
+Total time (across all threads) spent on:
+ Type Total Count Average
+ VFS_STAT 2.72% 1 23.5 ms
+ VFS_READLINK 32.19% 1 278 ms
+
+=== LOADING PHASE INFORMATION ===
+
+Total loading phase time 21.841 s
+
+Total time (across all threads) spent on:
+ Type Total Count Average
+ SPAWN 3.26% 154 475 ms
+ VFS_STAT 10.81% 65416 3.71 ms
+[...]
+SKYLARK_BUILTIN_FN 13.12% 45138 6.52 ms
+
+=== ANALYSIS PHASE INFORMATION ===
+
+Total analysis phase time 5.444 s
+
+Total time (across all threads) spent on:
+ Type Total Count Average
+ SKYFRAME_EVAL 9.35% 1 4.782 s
+ SKYFUNCTION 89.36% 43332 1.06 ms
+
+=== EXECUTION PHASE INFORMATION ===
+
+Total preparation time 155 ms
+Total execution phase time 49.473 s
+Total time finalizing build 83.9 ms
+
+Action dependency map creation 0.00 ms
+Actual execution time 49.473 s
+
+Total time (across all threads) spent on:
+ Type Total Count Average
+ ACTION 2.25% 12229 10.2 ms
+[...]
+ SKYFUNCTION 1.87% 236131 0.44 ms
+</pre>
+
+<p>
+ The last section shows the critical path:
+</p>
+<pre>
+Critical path (32.078 s):
+ Id Time Percentage Description
+1109746 5.171 s 16.12% Building [...]
+1109745 164 ms 0.51% Extracting interface [...]
+1109744 4.615 s 14.39% Building [...]
+[...]
+1109639 2.202 s 6.86% Executing genrule [...]
+1109637 2.00 ms 0.01% Symlinking [...]
+1109636 163 ms 0.51% Executing genrule [...]
+ 4.00 ms 0.01% [3 middleman actions]
+</pre>
+
+<p>
+ You can use the following options to display more detailed information:
+</p>
+
+<ul>
+ <li id='dump-text-format'><a href='#flag--dump'><code>--dump=text</code></a>
+ <p>
+ This option prints all recorded tasks in the order they occurred. Nested tasks are indented
+ relative to the parent. For each task, output includes the following information:
+ </p>
+<pre>
+[task type] [task description]
+Thread: [thread id] Id: [task id] Parent: [parent task id or 0 for top-level tasks]
+Start time: [time elapsed from the profiling session start] Duration: [task duration]
+[aggregated statistic for nested tasks, including count and total duration for each nested task]
+</pre>
+ </li>
+ <li id='dump-raw-format'><a href='#flag--dump'><code>--dump=raw</code></a>
+ <p>
+ This option is most useful for automated analysis with scripts. It outputs each task record on
+ a single line using '|' delimiter between fields. Fields are printed in the following order:
+ </p>
+ <ol>
+ <li>thread id - integer positive number, identifies owner thread for the task</li>
+ <li>task id - integer positive number, identifies specific task</li>
+ <li>parent task id for nested tasks or 0 for root tasks</li>
+ <li>task start time in ns, relative to the start of the profiling session</li>
+ <li>task duration in ns. Please note that this will include duration of all subtasks.</li>
+ <li>aggregated statistic for immediate subtasks per type. This will include type name (lower
+ case), number of subtasks for that type and their cumulative duration. Types are
+ space-delimited and information for single type is comma-delimited.</li>
+ <li>task type (upper case)</li>
+ <li>task description</li>
+ </ol>
+
+ Example:
+<pre>
+1|1|0|0|0||PHASE|Launch Bazel
+1|2|0|6000000|0||PHASE|Initialize command
+1|3|0|168963053|278111411||VFS_READLINK|/[...]
+1|4|0|571055781|23495512||VFS_STAT|/[...]
+1|5|0|869955040|0||PHASE|Load packages
+[...]
+</pre>
+ </li>
+ <li id='dump-html-format'><a href='#flag--html'><code>--html</code></a>
+ <p>
+ This option writes a file called <code><profile-file>.html</code> in the directory of the
+ profile file. Open it in your browser to see the visualization of the actions in your build.
+ Note that the file can be quite large and may push the capabilities of your browser –
+ please wait for the file to load.
+ </p>
+ <p>
+ In most cases, the HTML output from <a href='#flag--html'><code>--html</code></a> is easier to
+ read than the <a href='#flag--dump'><code>--dump</code></a> output.
+ It includes a Gantt chart that displays time on the horizontal axis and
+ threads of execution along the vertical axis. If you click on the Statistics link in the top
+ right corner of the page, you will jump to a section that lists summary analysis information
+ from your build.
+ </p>
+ <ul>
+ <li><a href='#flag--html_details'><code>--html_details</code></a>
+ <p>
+ Additionally passing this option will render a more detailed execution chart and additional
+ tables on the performance of built-in and user-defined Skylark functions. Beware that this
+ increases the file size and the load on the browser considerably.
+ </p>
+ </li>
+ </ul></li>
+</ul>
+
+<p>If Bazel appears to be hung, you can hit <kbd><kbd>ctrl</kbd> + <kbd>\</kbd></kbd> or send
+ Bazel a <code>SIGQUIT</code> signal (<code>kill -3 $(bazel info server_pid)</code>) to get a
+ thread dump in the file <code>$(bazel info output_base)/server/jvm.out</code>.
+</p>
+
+<p>
+ Since you may not be able to run <code>bazel info</code> if bazel is hung, the
+ <code>output_base</code> directory is usually the parent of the <code>bazel-<workspace></code>
+ symlink in your workspace directory.
+</p>
