Fix some links to query and user manual
PiperOrigin-RevId: 167859496
diff --git a/site/docs/query.html b/site/docs/query.html
index c4c3359..f46ae0c 100644
--- a/site/docs/query.html
+++ b/site/docs/query.html
@@ -158,7 +158,7 @@
that this graph is somewhat abstract, and does not constitute a
complete description of how to perform all the steps of a build. In
order to perform a build, a <em>configuration</em> is required too;
- see the <a href='bazel-user-manual.html#configurations'>configurations</a>
+ see the <a href='user-manual.html#configurations'>configurations</a>
section of the User's Guide for more detail.
</p>
diff --git a/site/versions/master/docs/blaze-user-manual.html b/site/versions/master/docs/blaze-user-manual.html
deleted file mode 100644
index b3a93af..0000000
--- a/site/versions/master/docs/blaze-user-manual.html
+++ /dev/null
@@ -1,3836 +0,0 @@
----
-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 output base, which by default is
- determined by the path of the base workspace directory and your
- userid, so if you build in multiple workspaces, you'll have multiple
- output bases and thus multiple Bazel server processes. Multiple
- users on the same workstation can build concurrently in the same
- workspace because their output bases will differ (different userids).
- 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'>--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, and also on Mac OS 10.11 for newer.
-</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--host_cxxopt'><code class='flag'>--host_cxxopt <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--cxxopt'><code class='flag'>--cxxopt</code></a> option, but applies only to the
- host configuration.
-</p>
-
-<h4 id='flag--conlyopt'><code class='flag'>--conlyopt <var>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 output
- a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold
- option). For each linker input, the file logs the number of symbols that were
- defined and the number of symbols that were used in the binary.
- This information can be used to track unnecessary link dependencies.
- The symbol counts file is written to the binary's output path with the name
- <code>[targetname].sc</code>.
-</p>
-<p>
- This option is disabled by default.
-</p>
-
-<h4 id='flag--jvmopt'><code class='flag'>--jvmopt <var>jvm-option</var></code></h4>
-<p>
- This option allows option arguments to be passed to the Java VM. It can be used
- with one big argument, or multiple times with individual arguments. For example:
-</p>
-<pre>
- % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all
-</pre>
-<p>
- will use the server VM for launching all Java binaries and set the
- startup heap size for the VM to 256 MB.
-</p>
-
-<h4 id='flag--javacopt'><code class='flag'>--javacopt <var>javac-option</var></code></h4>
-<p>
- This option allows option arguments to be passed to javac. It can be used
- with one big argument, or multiple times with individual arguments. For example:
-</p>
-<pre>
- % bazel build --javacopt="-g:source,lines" //myprojects:prog
-</pre>
-<p>
- will rebuild a java_binary with the javac default debug info
- (instead of the bazel default).
-</p>
-<p>
- The option is passed to javac after the Bazel built-in default options for
- javac and before the per-rule options. The last specification of
- any option to javac wins. The default options for javac are:
-</p>
-
-<pre>
- -source 8 -target 8 -encoding UTF-8
-</pre>
-<p>
- Note that changing <code class='flag'>--javacopt</code> settings will force a recompilation
- of all affected classes. Also note that javacopts parameters listed in
- specific java_library or java_binary build rules will be placed on the javac
- command line <em>after</em> these options.
-</p>
-
-<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps
- (default|strict|off|warn|error)</code></h4>
-<p>
- This option controls whether javac checks for missing direct dependencies.
- Java targets must explicitly declare all directly used targets as
- dependencies. This flag instructs javac to determine the jars actually used
- for type checking each java file, and warn/error if they are not the output
- of a direct dependency of the current target.
-</p>
-
-<ul>
- <li> <code>off</code> means checking is disabled.
- </li>
- <li> <code>warn</code> means javac will generate standard java warnings of
- type <code>[strict]</code> for each missing direct dependency.
- </li>
- <li> <code>default</code>, <code>strict</code> and <code>error</code> all
- mean javac will generate errors instead of warnings, causing the current
- target to fail to build if any missing direct dependencies are found.
- This is also the default behavior when the flag is unspecified.
- </li>
-</ul>
-
-<h3 id='semantics-options'>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--fat_apk_cpu'><code class='flag'>--fat_apk_cpu <var>cpu[,cpu]*</var></code></h4>
-<p>
- The CPUs to build C/C++ libraries for in the transitive <code>deps</code> of
- <code>android_binary</code>
-
- rules. Other C/C++ rules are not affected. For example, if a <code>cc_library</code>
- appears in the transitive <code>deps</code> of an <code>android_binary</code> rule and a
- <code>cc_binary</code> rule, the <code>cc_library</code> will be built at least twice:
- once for each CPU specified with <code class='flag'>--fat_apk_cpu</code> for the
- <code>android_binary</code> rule, and once for the CPU specified with
- <code class='flag'>--cpu</code> for the <code>cc_binary</code> rule.
-
-<p>
-The default is <code>armeabi-v7a</code>.
-</p>
- <p>
- One <code>.so</code> file will be created and packaged in the APK for
- each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The name of the <code>.so</code>
- file will be the name of the <code>android_binary</code> rule prefixed with "lib", e.g., if the name
- of the <code>android_binary</code> is "foo", then the file will be <code>libfoo.so</code>.
- </p>
-
- <p>
- Note that an Android-compatible crosstool must be selected.
- If an <code>android_ndk_repository</code> rule is defined in the
- WORKSPACE file, an Android-compatible crosstool is automatically selected.
- Otherwise, the crostool can be selected using the
- <a href='#flag--android_crosstool_top'><code class='flag'>--android_crosstool_top</code></a>
- or <a href='#flag--crosstool_top'><code class='flag'>--crosstool_top</code></a> flags.
- </p>
-</p>
-
-<h4 id='flag--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--android_resource_shrinking'><code class='flag'>--android_resource_shrinking</code></h4>
-<p>
- Selects whether to perform resource shrinking for android_binary rules. Sets the default for the
- <a href='be/android.html#android_binary.shrink_resources'>shrink_resources attribute</a> on
- android_binary rules; see the documentation for that rule for further details. Defaults to off.
-</p>
-
-<h4 id='flag--custom_malloc'><code class='flag'>--custom_malloc <var>malloc-library-target</var></code></h4>
-<p>
- When specified, always use the given malloc implementation, overriding all
- <code>malloc="target"</code> attributes, including in those targets that use the
- default (by not specifying any <code>malloc</code>).
-</p>
-
-<h4 id='flag--crosstool_top'><code class='flag'>--crosstool_top <var>label</var></code></h4>
-<p>
- This option specifies the location of the crosstool compiler suite
- to be used for all C++ compilation during a build. Bazel will look in that
- location for a CROSSTOOL file and uses that to automatically determine
- settings for
-
- <code class='flag'>--compiler</code>.
-</p>
-
-<h4 id='flag--host_crosstool_top'><code class='flag'>--host_crosstool_top <var>label</var></code></h4>
-<p>
- If not specified, bazel uses the value of <code class='flag'>--crosstool_top</code> to compile
- code in the host configuration, i.e., tools run during the build. The main purpose of this flag
- is to enable cross-compilation.
-</p>
-
-<h4 id='flag--apple_crosstool_top'><code class='flag'>--apple_crosstool_top <var>label</var></code></h4>
-<p>
- The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
- objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites
- <code class='flag'>--crosstool_top</code>.
-</p>
-
-<h4 id='flag--android_crosstool_top'><code class='flag'>--android_crosstool_top <var>label</var></code></h4>
-<p>
- The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
- <code>android_binary</code> rules. This is useful if other targets in the
- build require a different crosstool. The default is to use the crosstool
- generated by the <code>android_ndk_repository</code> rule in the WORKSPACE file.
- See also <a href='#flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu</code></a>.
-</p>
-<h4 id='flag--compiler'><code class='flag'>--compiler <var>version</var></code></h4>
-<p>
- This option specifies the C/C++ compiler version (e.g. <code>gcc-4.1.0</code>)
- to be used for the compilation of binaries during the build. If you want to
- build with a custom crosstool, you should use a CROSSTOOL file instead of
- specifying this flag.
-</p>
-<p>
- Note that only certain combinations of crosstool version, compiler version,
- 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--android_sdk'><code class='flag'>--android_sdk <var>label</var></code></h4>
-<p>
- This option specifies the Android SDK/platform toolchain
- and Android runtime library that will be used to build any Android-related
- rule.
-
- The Android SDK will be automatically selected if an <code>android_sdk_repository</code>
- rule is defined in the WORKSPACE file.
-</p>
-
-<h4 id='flag--java_toolchain'><code class='flag'>--java_toolchain <var>label</var></code></h4>
-<p>
- This option specifies the label of the java_toolchain used to compile Java
- source files.
-</p>
-
-<h4 id='flag--javabase'><code class='flag'>--javabase (<var>path</var>|<var>label</var>)</code></h4>
-<p>
- This option sets the <i>label</i> or the <i>path</i> of the base Java installation to
- use for running JavaBuilder, SingleJar, for <i>bazel run</i> and <i>bazel
- test</i>, and for Java binaries built by <code>java_binary</code> and <code>java_test</code>
- rules. A path must be to a JDK or JRE directory that contains <code>bin/java</code>.
- 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--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--build_tag_filters'><code class='flag'>--build_tag_filters <var>tag[,tag]*</var></code></h4>
-<p>
- If specified, Bazel will build only targets that have at least one required tag
- (if any of them are specified) and does not have any excluded tags. Build tag
- filter is specified as comma delimited list of tag keywords, optionally
- preceded with '-' sign used to denote excluded tags. Required tags may also
- have a preceding '+' sign.
-</p>
-
-<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,-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 each test process. This
- option can be used multiple times to pass several arguments, e.g.
- <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>.
-</p>
-
-<h4 id='flag--test_env'><code class='flag'>--test_env <var>variable</var>=<i>value</i></code>
- OR
- <code class='flag'>--test_env <var>variable</var></code></h4>
-<p>
- Specifies additional variables that must be injected into the test
- environment for each test. If <var>value</var> is not specified it will be
- inherited from the shell environment used to start the <code>bazel test</code>
- command.
-</p>
-<p>
- The environment can be accessed from within a test by using
- <code>System.getenv("var")</code> (Java),
- <code>getenv("var")</code> (C or C++),
-
-</p>
-
-<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
-<p>
- This specifies a prefix that the test runner will insert in front
- of the test command before running it. The
- <var>command-prefix</var> is split into words using Bourne shell
- tokenization rules, and then the list of words is prepended to the
- command that will be executed.
-</p>
-<p>
- If the first word is a fully qualified label (i.e. starts with
- <code>//</code>) it is built. Then the label is substituted by the
- corresponding executable location that is prepended to the command
- that will be executed along with the other words.
-</p>
-
-<p>
-Some caveats apply:
-</p>
-<ul>
- <li>
- The PATH used for running tests may be different than the PATH in your environment,
- so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code>
- command (the first word in <var>command-prefix</var>).
- </li>
- <li>
- <b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code>
- can't be used for interactive commands.
- </li>
-
-</ul>
-<p>
-Examples:
-</p>
-<pre>
- --run_under=/usr/bin/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_bazel_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 COMPILATION_MODE
- opt
-</pre>
-
-<p>
- Example: the <code>bazel-bin</code> output directory for the current
- configuration. This is guaranteed to be correct even in cases where
- the <code>bazel-bin</code> symlink cannot be created for some reason
- (e.g. you are building from a read-only directory).
-</p>
-
-<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.
-
- See <a href="mobile-install.html">bazel mobile-install</a>
- for more information.
-</p>
-<p>
- Note that this command does not install the same thing that
- <code>bazel build</code> produces: Bazel tweaks the app so that it can be
- built, installed and re-installed quickly. This should, however, be mostly
- transparent to the app.
-</p>
-<p>
- The following options are supported:
-</p>
-<h4 id='flag--incremental'><code class='flag'>--incremental</code></h4>
-<p>
- If set, Bazel tries to install the app incrementally, that is, only those
- parts that have changed since the last build. This cannot update resources
- referenced from <code>AndroidManifest.xml</code>, native code or Java
- resources (i.e. ones referenced by <code>Class.getResource()</code>). If these
- things change, this option must be omitted. Contrary to the spirit of Bazel
- and due to limitations of the Android platform, it is the
- <b>responsibility of the user</b> to know when this command is good enough and
- when a full install is needed.
-
- If you are using a device with Marshmallow or later, consider the
- <a href='#flag--split_apks'><code class='flag'>--split_apks</code></a> flag.
-</p>
-<h4 id='flag--split_apks'><code class='flag'>--split_apks</code></h4>
-<p>
- Whether to use split apks to install and update the application on the device.
- Works only with devices with Marshmallow or later. Note that the
- <a href='#flag--incremental'><code class='flag'>--incremental</code></a> flag
- is not necessary when using <code class='flag'>--split_apks</code>.
-</p>
-<h4 id='flag--start_app'><code class='flag'>--start_app</code></h4>
-<p>
- Starts the app in a clean state after installing. Equivalent to
- <code>--start=COLD</code>.
-</p>
-<h4 id='flag--debug_app'><code class='flag'>--debug_app</code></h4>
-<p>
- Waits for debugger to be attached before starting the app in a clean state after installing.
- Equivalent to <code>--start=DEBUG</code>.
-</p>
-<h4 id='flag--start'><code class='flag'>--start=<i>start_type</i></code></h4>
-<p>
- How the app should be started after installing it. Supported <i>start_type</i>s are:
- <ul>
- <li><code>NO</code> Does not start the app. This is the default.</li>
- <li><code>COLD</code> Starts the app from a clean state after install.</li>
- <li><code>WARM</code> Preserves and restores the application state on incremental installs.</li>
- <li><code>DEBUG</code> Waits for the debugger before starting the app in a clean state after install.</li>
- </ul>
- Note that if more than one of <code class='flag'>--start=<i>start_type</i></code>,
- <code class='flag'>--start_app</code> or
- <code class='flag'>--debug_app</code> is set, the last value will be used.
-</p>
-<h4 id='flag--adb'><code class='flag'>--adb <var>path</var></code></h4>
-<p>
- Indicates the <code>adb</code> binary to be used.
-
- The default is to use the adb in the Android SDK specified by
- <a href='#flag--android_sdk'><code class='flag'>--android_sdk</code></a>.
-
-</p>
-<h4 id='flag--adb_arg'><code class='flag'>--adb_arg <var>arg</var></code></h4>
-<p>
- Extra arguments to <code>adb</code>. These come before the subcommand in the
- command line and are typically used to specify which device to install to.
- For example, to select the Android device or emulator to use:
-<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
-</pre>
-will invoke <code>adb</code> as
-<pre>
-adb -s deadbeef install ...
-</pre>
-</p>
-<h4 id='flag--adb_jobs'><code class='flag'>--adb_jobs <var>number</var></code></h4>
-<p>
- The number of instances of adb to use in parallel to update files on the
- device.
-</p>
-<h4 id='flag--incremental_install_verbosity'><code class='flag'>--incremental_install_verbosity <var>number</var></code></h4>
-<p>
- The verbosity for incremental install. Set to 1 for debug logging to be
- printed to the console.
-</p>
-
-<h3 id='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><code id='flag--html_histograms'>--html_histograms</code> adds histograms for Skylark
- functions clicked in the statistics table. This will increase file size massively</li>
- <li><code id='flag--nochart'>--nochart</code> hides the task chart from generated HTML
- </li>
- </ul>
- </ul>
- </li>
- <li><code id='flag--combine'>--combine</code> combines multiple profile data files into a single
- report. Does not generate HTML task charts</li>
- <li><code id='flag--task_tree'>--task_tree</code> prints the tree of tasks matching the given
- regular expression
- <ul>
- <li><code id='flag--task_tree_threshold'>--task_tree_threshold</code> skip tasks with duration
- less than threshhold, in milliseconds. Default is 50ms</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. Can be specified multiple
- times to add flags from several config sections. Expansions can refer to other
- definitions (i.e. expansions can be chained).
-</p>
-
-<h4 id='flag--curses'><code class='flag'>--curses (yes|no|auto)</code></h4>
-<p>
- This option determines whether Bazel will use cursor controls
- in its screen output. This results in less scrolling data, and a more
- compact, easy-to-read stream of output from Bazel. This works well with
- <code class='flag'>--color</code>.
-</p>
-<p>
- If this option is set to <code>yes</code>, use of cursor controls is enabled.
- If this option is set to <code>no</code>, use of cursor controls is disabled.
- If this option is set to <code>auto</code>, use of cursor controls will be
- enabled under the same conditions as for <code class='flag'>--color=auto</code>.
-</p>
-
-<h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4>
-<p>
- If specified, a timestamp is added to each message generated by
- Bazel specifying the time at which the message was displayed.
-</p>
-
-<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>
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCppRuleClasses.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCppRuleClasses.java
index 12737d9..99abec3 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCppRuleClasses.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/cpp/BazelCppRuleClasses.java
@@ -528,7 +528,7 @@
<li><code>stamp = 0</code>: Always replace build information by constant
values. This gives good build result caching.</li>
<li><code>stamp = -1</code>: Embedding of build information is controlled
- by the <a href="../blaze-user-manual.html#flag--stamp">--[no]stamp</a> flag.</li>
+ by the <a href="../user-manual.html#flag--stamp">--[no]stamp</a> flag.</li>
</ul>
<!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
.add(attr("stamp", TRISTATE).value(TriState.AUTO))
