site/docs/user-manual.html

---
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="build-ref.html#workspaces">workspace</a> directory
  or any of its subdirectories and type <code>bazel</code>.
</p>

<pre>
  % bazel help
                             [Bazel release bazel-&lt;<i>version</i>&gt;]
  Usage: bazel &lt;command&gt; &lt;options&gt; ...

  Available commands:
    <a href='#analyze-profile'>analyze-profile</a>     Analyzes build profile data.
    <a href='#build'>build</a>               Builds the specified targets.

    <a href='#canonicalize'>canonicalize-flags</a>  Canonicalize Bazel flags.
    <a href='#clean'>clean</a>               Removes output files and optionally stops the server.

    <a href='#dump'>dump</a>                Dumps the internal state of the Bazel server process.

    <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 &lt;command&gt;
                     Prints help and options for &lt;command&gt;.
    bazel help <a href='#startup_options'>startup_options</a>
                     Options for the JVM hosting Bazel.
    bazel help <a href='#target-patterns'>target-syntax</a>
                     Explains the syntax for specifying targets.
    bazel help info-keys
                     Displays a list of keys used by the info command.

</pre>
<p>
  The <code>bazel</code> tool performs many functions, called
  commands; users of 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-johndoe2) -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 unchanged options for every build (and other commands)
  Bazel allows you to specify options in a configuration file.
</p>

<h4>Where are <code>.bazelrc</code> files?</h4>
<p>
  Bazel looks for an optional configuration file in the following locations,
  in order. It will stop searching once it has successfully found a file.
</p>
<ol>
  <li>
    The path specified by the <code class='flag'>--bazelrc=<var>file</var></code>
    startup option. If specified, this option must appear <em>before</em> the
    command name (e.g. <code>build</code>)
  </li>
  <li>
    A file named <code>.bazelrc</code> in your base workspace directory
  </li>
  <li>
    A file named <code>.bazelrc</code> in your home directory
  </li>
</ol>
<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 optional configuration file described above, Bazel also looks
  for a master rc file named <code>bazel.bazelrc</code> 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. These files do not
  override one another; if all of these files exist, all of them will be loaded.
  Reading of these files can be disabled using the
  <code class='flag'>--nomaster_bazelrc</code> option.
</p>
<h4><code>.bazelrc</code> syntax and semantics</h4>
<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.
</p>

<h5>Imports</h5>
<p>
  Lines that start with <code>import</code> are 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 options specified before the import statement. Options
  specified after the import statement take precedence over the options in the
  imported file. Options in files imported later take precedence over files
  imported earlier. To specify a path that is relative to the workspace root,
  write <code>import %workspace%/path/to/bazelrc</code>.
</p>

<h5>Option defaults</h5>
<p>
  Most lines of a bazelrc define default option values. The first word on each
  line specifies when these defaults are applied:
</p>
<ol>
  <li>
    <code>startup</code>: startup options, which go before the command, and
    are described in <code>bazel help startup_options</code>.
  </li>
  <li>
    <code>common</code>: options that apply to all Bazel commands.
  </li>
  <li>
    <code><i>command</i></code>: Bazel command, such as <code>build</code>
    or <code>query</code> to which the options apply. These options also apply
    to all commands that inherit from the specified command. (For example,
    <code>test</code> inherits from <code>build</code>.)
  </li>
</ol>
<p>
  Each of these lines may be used more than once and the arguments that follow
  the first word 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>
  Options specified in the command line always take precedence over those from
  a configuration file. Within the configuration file, precedence is
  given by specificity. This means that lines for a more specific command take
  precedence over lines for a less specific command, with <code>common</code>
  getting lowest precedence (for example, the <code>test</code> command inherits
  all the options from the <code>build</code> command, so the line
  <code>test --foo=bar</code> takes precedence over the line
  <code>build --foo=baz</code> line, regardless of which rc file or what order
  these two lines are in). Two lines specifying options for the same command at
  equal specificity are parsed in the order in which they appear within the file.
  The user-specific configuration file takes precedence over the master file.
</p>
<p>
  Because this precedence rule does not match the file order, we recommend
  that the file follows the same order, with <code>common</code> options at the
  top, and most-specific commands near the bottom. This way, the order in which
  the options are read is the same as the order in which they are applied,
  which is more intuitive.
</p>
<p>
  The arguments specified on line of an rc file may include arguments that are
  not options, such as the names of build targets, and so on. These, like the
  options specified in the same files, have lower precedence than their siblings
  on the command line, and are always prepended to the explicit list of non-
  option arguments.
</p>
<h5><code>--config</code></h5>
<p>
  In addition to setting option defaults, the rc file can be used to group
  options and provide a shorthand for common groupings. This is done by adding
  a <code>:name</code> suffix to the command. These options are ignored by
  default, but will be included when the option
  <code>--config=<var>name</var></code> is present, either on the command line
  or in a <code>.bazelrc</code> file, recursively, even inside of another
  config definition. Only the options specified by <code>command:name</code>
  for applicable commands will be expanded, in the precedence order described
  above.
</p>
<p>
  Note that configs can be defined in any <code>.bazelrc</code> file, and that
  all lines of the form <code>command:name</code> (for applicable commands)
  will be expanded, across the different rc files. In order to avoid name
  conflicts, we suggest that configs defined in personal rc files start
  with an underscore ('_') to avoid unintentional name sharing.
</p>
<p>
  The expansion behavior for these <code>--config=foo</code> options has
  changed. The legacy behavior, still the default, is to expand these in a
  fixed point expansion after all default rc options are loaded. This is
  unintuitive and has caused debugging difficulties in the past. The new
  behavior is to expand <code>--config=foo</code> to the options it expands to
  "in-place" so that the options specified for the config have the same
  precedence that the <code>--config=foo</code> option had. This is more
  intuitive, and can be enabled using the startup flag
  <code>--expand_configs_in_place</code>, which can be included in a bazelrc
  file on a <code>startup</code> line.
</p>

<h5>Example</h5>
<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

  # Definition of --config=memcheck
  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
  % touch WORKSPACE
  % 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.

  When running the test command, test suite expansion is applied to each target
  pattern in sequence as the set of targets is evaluated. This means that
  individual tests from a test suite can be excluded by a later target pattern.
  It also means that an exclusion target pattern which matches a test suite will
  exclude all tests which that test suite references. (Targets that would be
  matched by the list of target patterns without any test suite expansion are
  also built unless --build_tests_only is set.)
</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 Bazel
  will automatically 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&mdash;for example
  tools that are built from source, then subsequently used in, say, a
  genrule&mdash;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>,
    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 the value of <code class="flag">--host_javabase</code> for
    <code class='flag'>--javabase</code>
  </li>
  <li>
    Use the value of <code class="flag">--host_java_toolchain</code> for
    <code class='flag'>--java_toolchain</code>
  </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 macOS 10.11 or 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/kubernetes-engine/">Google Kubernetes
  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--output_filter'><code class='flag'>--output_filter <var>regex</var></code></h4>
<p>
  The <code class='flag'>--output_filter</code> option will only show build and compilation
  warnings for targets that match the regular expression. If a target does not
  match the given regular expression and its execution succeeds, its standard
  output and standard error are thrown away.
</p>
<p>
  Here are some typical values for this option:
</p>
<table>
  <tr>
    <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td>
    <td>Show the output for the specified packages.</td>
  </tr>
  <tr>
    <td><code class='flag'>--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'</code></td>
    <td>Don't show output for the specified packages.</td>
  </tr>
  <tr>
    <td><code class='flag'>--output_filter=</code></td>
    <td>Show everything.
    </td>
  </tr>
  <tr>
    <td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td>
    <td>Show nothing.
    </td>
  </tr>
</table>

<h3 id='flags-options'>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>

<h5 id='-extra_checks'><code>-extra_checks[:(off|on)]</code></h5>

<p>
  This javac option enables extra correctness checks. Any problems found will
  be presented as errors.
  Either <code>-extra_checks</code> or <code>-extra_checks:on</code> may be used
  to force the checks to be turned on. <code>-extra_checks:off</code> completely
  disables the analysis.
  When this option is not specified, the default behavior is used.
</p>

<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps
    (default|strict|off|warn|error)</code></h4>
<p>
  This option controls whether javac checks for missing direct dependencies.
  Java targets must explicitly declare all directly used targets as
  dependencies. This flag instructs javac to determine the jars actually used
  for type checking each java file, and warn/error if they are not the output
  of a direct dependency of the current target.
</p>

<ul>
  <li> <code>off</code> means checking is disabled.
  </li>
  <li> <code>warn</code> means javac will generate standard java warnings of
    type <code>[strict]</code> for each missing direct dependency.
  </li>
  <li> <code>default</code>, <code>strict</code> and <code>error</code> all
    mean javac will generate errors instead of warnings, causing the current
    target to fail to build if any missing direct dependencies are found.
    This is also the default behavior when the flag is unspecified.
  </li>
</ul>

<h3 id='semantics-options'>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>

<h4 id='flag--experimental_action_listener'>
  <code class='flag'>--experimental_action_listener=<var>label</var></code>
</h4>
<p>
  The <code>experimental_action_listener</code> option instructs Bazel to use
  details from the <a href="be/extra-actions.html#action_listener"
  ><code>action_listener</code></a> rule specified by <var>label</var> to
  insert <a href="be/extra-actions.html#extra_action"
  ><code>extra_actions</code></a> into the build graph.
</p>

<h4 id='flag--experimental_extra_action_top_level_only'>
  <code class='flag'>--[no]experimental_extra_action_top_level_only</code>
</h4>
<p>
  If this option is set to true, extra actions specified by the
  <a href='#flag--experimental_action_listener'> <code>
  --experimental_action_listener</code></a> command line option will only be
  scheduled for top level targets.
</p>

<h4 id='flag--experimental_extra_action_filter'>
  <code class='flag'>--experimental_extra_action_filter=<var>regex</var></code>
</h4>
<p>
  The <code>experimental_extra_action_filter</code> option instructs Bazel to
  filter the set of targets to schedule <code>extra_actions</code> for.
</p>
<p>
  This flag is only applicable in combination with the
  <a href='#flag--experimental_action_listener'
  ><code>--experimental_action_listener</code></a> flag.
</p>
<p>
  By default all <code>extra_actions</code> in the transitive closure of the
  requested targets-to-build get scheduled for execution.
  <code>--experimental_extra_action_filter</code> will restrict scheduling to
  <code>extra_actions</code> of which the owner's label matches the specified
  regular expression.
</p>
<p>
  The following example will limit scheduling of <code>extra_actions</code>
  to only apply to actions of which the owner's label contains '/bar/':
</p>
<pre>% bazel build --experimental_action_listener=//test:al //foo/... \
  --experimental_extra_action_filter=.*/bar/.*
</pre>

<h3 id='strategy-options'>Build strategy options</h3>
<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--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--host_java_toolchain'><code class='flag'>--host_java_toolchain <var>label</var></code></h4>
<p>
  If not specified, bazel uses the value of <code class='flag'>--java_toolchain</code> to compile
  code in the host configuration, i.e., tools run during the build. The main purpose of this flag
  is to enable cross-compilation.
</p>

<h4 id='flag--javabase'><code class='flag'>--javabase (<var>label</var>)</code></h4>
<p>
  This option sets the <i>label</i> of the base Java installation to
  use for 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.
  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>

<h4 id='flag--host_javabase'><code class='flag'>--host_javabase <var>label</var></code></h4>
<p>
  If not specified, bazel uses the value of <code class='flag'>--javabase</code>
  in the host configuration, i.e., for Java-based tools that run during the build.
  The main purpose of this flag is to enable cross-compilation.
</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>
<p>
  This option should not be confused with the startup option
  <a href='#startup_flag--host_javabase'>--host_javabase</a>.
</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--jobs'><code class='flag'>--jobs <var>n</var></code> (-j)</h4>
<p>
  This option, which takes an integer argument, specifies a limit on
  the number of jobs that should be executed concurrently during the
  execution phase of the build.
</p>
<p>
  Note that the number of concurrent jobs that Bazel will run
  is determined not only by the <code class='flag'>--jobs</code> setting, but also
  by Bazel's scheduler, which tries to avoid running concurrent jobs
  that will use up more resources (RAM or CPU) than are available,
  based on some (very crude) estimates of the resource consumption
  of each job.  The behavior of the scheduler can be controlled by
  the <code class='flag'>--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 enabled by default, specifies whether the runfiles
  symlinks for tests and binaries should be built in the output directory.
  Using <code class='flag'>--nobuild_runfile_links</code> can be useful
  to validate if all targets compile without incurring the overhead
  for building the runfiles trees.

</p>

<p>
  When tests (or applications) are executed, their run-time data
  dependencies are gathered together in one place.  Within Bazel's
  output tree, this "runfiles" tree is typically rooted as a sibling of
  the corresponding binary or test.
  During test execution, runfiles may be accessed using paths of the form
  <code>$TEST_SRCDIR/workspace/<var>packagename</var>/<var>filename</var></code>.
  The runfiles tree ensures that tests have access to all the files
  upon which they have a declared dependence, and nothing more.  By
  default, the runfiles tree is implemented by constructing a set of
  symbolic links to the required files.  As the set of links grows, so
  does the cost of this operation, and for some large builds it can
  contribute significantly to overall build time, particularly because
  each individual test (or application) requires its own runfiles tree.
</p>

<h4 id='flag--build_runfile_manifests'><code class='flag'>--[no]build_runfile_manifests</code></h4>
<p>
  This option, which is enabled by default, specifies whether runfiles manifests
  should be written to the output tree.
  Disabling it implies <code class='flag'>--nobuild_runfile_links</code>.

  It can be disabled when executing tests on Forge, as runfiles trees will
  be created remotely from in-memory manifests.

<h4 id='flag--discard_analysis_cache'>
  <code class='flag'>--[no]discard_analysis_cache</code></h4>
<p>
  When this option is enabled, Bazel will discard the analysis cache
  right before execution starts, thus freeing up additional memory
  (around 10%) for the <a href="#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>
  &gt;&gt;&gt;&gt;&gt; # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
  (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
    exec env - \
    /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)
</pre>
<p>
  Where possible, commands are printed in a Bourne shell compatible syntax,
  so that they can be easily copied and pasted to a shell command prompt.
  (The surrounding parentheses are provided to protect your shell from the
  <code>cd</code> and <code>exec</code> calls; be sure to copy them!)
  However some commands are implemented internally within Bazel, such as
  creating symlink trees. For these there's no command line to display.

</p>

<p>
  See also <a href="#flag--verbose_failures">--verbose_failures</a>, below.
</p>

<h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4>
<p>
  This option causes Bazel's execution phase to print the full command line
  for commands that failed.  This can be invaluable for debugging a
  failing build.
</p>
<p>
  Failing commands are printed in a Bourne shell compatible syntax, suitable
  for copying and pasting to a shell prompt.
</p>

<h3 id='workspace_status'>Options that control how Bazel embeds workspace status information
into binaries ("stamping")</h3>

<p>
  Use these options to "stamp" Bazel-built binaries: to embed additional information into the
  binaries, such as the source control revision or other workspace-related information. You can use
  this mechanism with rules that support the <code>stamp</code> attribute, such as
  <code>genrule</code>, <code>cc_binary</code>, and more.
</p>

<h4 id='flag--workspace_status_command'><code class='flag'>--workspace_status_command <var>program</var></code></h4>
<p>
  This flag lets you specify a binary that Bazel runs before each build. The program can report
  information about the status of the workspace, such as the current source control revision.
</p>
<p>
  The flag's value must be a path to a native program. On Linux/macOS this may be any executable.
  On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file.
</p>

<p>
  The program should print zero or more key/value pairs to standard output, one entry on each line,
  then exit with zero (otherwise the build fails). The key names can be anything but they may only
  use upper case letters and underscores. The first space after the key name separates it from the
  value. The value is the rest of the line (including additional whitespaces).
</p>
<p>
  Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and
  "volatile" are a bit counter-intuitive, so don't think much about them.)
</p>

<p>Bazel then writes the key-value pairs into two files:</p>
<ul>
  <li>
    <code>bazel-out/stable-status.txt</code> contains all keys and values where the key's name
    starts with <code>STABLE_</code>
  </li>
  <li><code>bazel-out/volatile-status.txt</code> contains the rest of the keys and their values</li>
</ul>

<p>The contract is:</p>
<ul>
  <li>
    <p>
      "stable" keys' values should change rarely, if possible. If the contents of
      <code>stable-status.txt</code> change, it invalidates the actions that depend on them. In
      other words, if a stable key's value changes, it'll make Bazel rebuild stamped actions.
      Therefore the stable status should not contain things like timestamps, because they change all
      the time, and would make Bazel rebuild the stamped actions with each build.
    </p>
    <p>Bazel always outputs the following stable keys:</p>
    <ul>
      <li><code>BUILD_EMBED_LABEL</code>: value of <code class='flag'>--embed_label</code></li>
      <li><code>BUILD_HOST</code>: the name of the host machine that Bazel is running on</li>
      <li><code>BUILD_USER</code>: the name of the user that Bazel is running as</li>
    </ul>
  </li>
  <li>
    <p>
      "volatile" keys' values may change often. Bazel expects them to change all the time, like
      timestamps do, and duly updates the <code>volatile-status.txt</code> file. In order to avoid
      rebuilding stamped actions all the time though, <b>Bazel pretends that the volatile file never
      changes</b>. In other words, if the volatile status file is the only one whose contents
      changed, that will not invalidate actions that depend on it. If other inputs of the actions
      have changed, then Bazel rebuilds that action, and the action will use the updated volatile
      status, but just the volatile status changing alone will not invalidate the action.
    </p>
    <p>Bazel always outputs the following volatile keys:</p>
    <ul>
      <li>
        <code>BUILD_TIMESTAMP</code>: time of the build in milliseconds since the Unix Epoch (the
        value of <code>System.currentTimeMillis()</code>)
      </li>
    </ul>
  </li>
</ul>

<p>
  On Linux/macOS you can pass <code class='flag'>--workspace_status_command=/bin/true</code> to
  disable retrieving workspace status, because <code>true</code> does nothing successfully (exits
  with zero) and prints no output. On Windows you can pass the path of MSYS's <code>true.exe</code>
  for the same effect.
</p>

<p>If the workspace status command fails (exits non-zero) for any reason, the build will fail.</p>

<p>Example program on Linux using Git:</p>

<pre>
#!/bin/bash
echo "CURRENT_TIME $(date +%s)"
echo "RANDOM_HASH $(cat /dev/urandom | head -c16 | md5sum 2>/dev/null | cut -f1 -d' ')"
echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
echo "STABLE_USER_NAME $USER"
</pre>

<p>
  Pass this program's path with <code>--workspace_status_command</code>, and the stable status file
  will include the STABLE lines and the volatile status file will include the rest of the lines.
</p>

<h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4>
<p>
  This option controls whether stamping is enabled for
  rule types that support it. For most of the supported rule types stamping is
  enabled by default (e.g. <code>cc_binary</code>).

  By default, stamping is disabled for all tests. Specifying
  <code class='flag'>--stamp</code> does not force affected targets to be rebuilt,
  if their dependencies have not changed.
</p>

<p>
  Stamping can be enabled or disabled explicitly in BUILD using
  the <code>stamp</code> attribute of certain rule types, please refer to
  the <a href="be/overview.html">build encyclopedia</a> for details. For
  rules that are neither explicitly or implicitly configured as <code>stamp =
  0</code> or <code>stamp = 1</code>, the <code class='flag'>--[no]stamp</code> option
  selects whether stamping is enabled. Bazel never stamps binaries that are
  built for the host configuration, regardless of the stamp attribute.
</p>

<h3 id='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-&lt;workspace&gt;</code>
      symlinks.  Use this option to suppress symlink creation entirely.
    </p>
  </li>
  <li>
    <p><b>Reduce clutter:</b>
      <code class='flag'>--symlink_prefix=.bazel/</code> will cause Bazel to create
      symlinks called <code>bin</code> (etc) inside a hidden directory <code>.bazel</code>.
    </p>
  </li>
</ul>

<h4 id='flag--platform_suffix'><code class='flag'>--platform_suffix <var>string</var></code></h4>
<p>
  Adds a suffix to the configuration short name, which is used to determine the
  output directory. Setting this option to different values puts the files into
  different directories, for example to improve cache hit rates for builds that
  otherwise clobber each others output files, or to keep the output files around
  for comparisons.
</p>

<h4 id='flag--default_visibility'><code class='flag'>--default_visibility=<var>(private|public)</var></code></h4>
<p>
  Temporary flag for testing bazel default visibility changes.  Not intended for general use
  but documented for completeness' sake.
</p>

<h4 id='flag--use_action_cache'><code class='flag'>--[no]use_action_cache</code></h4>
<p>
    This option is enabled by default.  If disabled, Bazel will not use its local action cache.
    Disabling the local action cache saves memory and disk space for clean builds, but will make
    incremental builds slower.
</p>

<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
  &quot;default&quot;), only a single attempt is allowed for regular tests, and
  3 for test rules with the <code>flaky</code> attribute set. You can specify
  an integer value to override the maximum limit of test attempts. Bazel allows
  a maximum of 10 test attempts in order to prevent abuse of the system.
</p>

<h4 id='flag--runs_per_test'><code class='flag'>--runs_per_test <var>[regex@]number</var></code></h4>
<p>
  This option specifies the number of times each test should be executed. All
  test executions are treated as separate tests (e.g. fallback functionality
  will apply to each of them independently).
</p>
<p>
  The status of a target with failing runs depends on the value of the
  <code>--runs_per_test_detects_flakes</code> flag:
</p>
<ul>
  <li>If absent, any failing run causes the entire test to fail.</li>
  <li>If present and two runs from the same shard return PASS and FAIL, the test
  will receive a status of flaky (unless other failing runs cause it to
  fail).</li>
</ul>

<p>
  If a single number is specified, all tests will run that many times.
  Alternatively, a regular expression may be specified using the syntax
  regex@number. This constrains the effect of --runs_per_test to targets
  which match the regex (e.g. "--runs_per_test=^//pizza:.*@4" runs all tests
  under //pizza/ 4 times).
  This form of --runs_per_test may be specified more than once.
</p>

<h4 id='flag--runs_per_test_detects_flakes'><code
    class='flag'>--[no]runs_per_test_detects_flakes</code></h4>
<p>
  If this option is specified (by default it is not), Bazel will detect flaky
  test shards through --runs_per_test. If one or more runs for a single shard
  fail and one or more runs for the same shard pass, the target will be
  considered flaky with the flag. If unspecified, the target will report a
  failing status.
</p>

<h4 id='flag--test_summary'><code class='flag'>--test_summary <var>output_style</var></code></h4>
<p>
  Specifies how the test result summary should be displayed.
</p>
<ul>
  <li><code>short</code> prints the results of each test along with the name of
    the file containing the test output if the test failed. This is the default
    value.
  </li>
  <li><code>terse</code> like <code>short</code>, but even shorter: only print
    information about tests which did not pass.
  </li>
  <li><code>detailed</code> prints each individual test case that failed, not
    only each test. The names of test output files are omitted.
  </li>
  <li><code>none</code> does not print test summary.
  </li>
</ul>

<h4 id='flag--test_output'><code class='flag'>--test_output <var>output_style</var></code></h4>
<p>
  Specifies how test output should be displayed:
</p>
<ul>
  <li><code>summary</code> shows a summary of whether each test passed or
    failed. Also shows the output log file name for failed tests. The summary
    will be printed at the end of the build (during the build, one would see
    just simple progress messages when tests start, pass or fail).
    This is the default behavior.
  </li>
  <li><code>errors</code> sends combined stdout/stderr output from failed tests
    only into the stdout immediately after test is completed, ensuring that
    test output from simultaneous tests is not interleaved with each other.
    Prints a summary at the build as per summary output above.
  </li>
  <li><code>all</code> is similar to <code>errors</code> but prints output for
    all tests, including those which passed.
  </li>
  <li><code>streamed</code> streams stdout/stderr output from each test in
  real-time.

  </li>
</ul>

<h4 id='flag--java_debug'><code class='flag'>--java_debug</code></h4>
<p>
  This option causes the Java virtual machine of a java test to wait for a connection from a
  JDWP-compliant debugger before starting the test. This option implies --test_output=streamed.
</p>

<h4 id='flag--verbose_test_summary'><code class='flag'>--[no]verbose_test_summary</code></h4>
<p>
  By default this option is enabled, causing test times and other additional
  information (such as test attempts) to be printed to the test summary. If
  <code class='flag'>--noverbose_test_summary</code> is specified, test summary will
  include only test name, test status and cached test indicator and will
  be formatted to stay within 80 characters when possible.
</p>

<h4 id='flag--test_tmpdir'><code class='flag'>--test_tmpdir <var>path</var></code></h4>
<p>
  Specifies temporary directory for tests executed locally. Each test will be
  executed in a separate subdirectory inside this directory. The directory will
  be cleaned at the beginning of the each <code>bazel test</code> command.
  By default, bazel will place this directory under Bazel output base directory.
  Note that this is a directory for running tests, not storing test results
  (those are always stored under the <code>bazel-out</code> directory).
</p>

<h4 id='flag--test_timeout'>
    <code class='flag'>--test_timeout
    <var>seconds</var></code>
    OR
    <code class='flag'>--test_timeout
    <var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var>
    </code>
</h4>
<p>
  Overrides the timeout value for all tests by using specified number of
  seconds as a new timeout value. If only one value is provided, then it will
  be used for all test timeout categories.
 </p>
 <p>
  Alternatively, four comma-separated values may be provided, specifying
  individual timeouts for short, moderate, long and eternal tests (in that
  order).
  In either form, zero or a negative value for any of the test sizes will
  be substituted by the default timeout for the given timeout categories as
  defined by the page
  <a href="test-encyclopedia.html">Writing Tests</a>.
  By default, Bazel will use these timeouts for all tests by
  inferring the timeout limit from the test's size whether the size is
  implicitly or explicitly set.
</p>
<p>
  Tests which explicitly state their timeout category as distinct from their
  size will receive the same value as if that timeout had been implicitly set by
  the size tag.  So a test of size 'small' which declares a 'long' timeout will
  have the same effective timeout that a 'large' tests has with no explicit
  timeout.
</p>

<h4 id='flag--test_arg'><code class='flag'>--test_arg <var>arg</var></code></h4>
<p>
  Passes command-line options/flags/arguments to each test process. This
  option can be used multiple times to pass several arguments, e.g.
  <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>.
</p>

<h4 id='flag--test_env'><code class='flag'>--test_env <var>variable</var>=<i>value</i></code>
    OR
    <code class='flag'>--test_env <var>variable</var></code></h4>
<p>
  Specifies additional variables that must be injected into the test
  environment for each test. If <var>value</var> is not specified it will be
  inherited from the shell environment used to start the <code>bazel test</code>
  command.
</p>
<p>
  The environment can be accessed from within a test by using
  <code>System.getenv("var")</code> (Java),
  <code>getenv("var")</code> (C or C++),

</p>

<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
<p>
  This specifies a prefix that the test runner will insert in front
  of the test command before running it.  The
  <var>command-prefix</var> is split into words using Bourne shell
  tokenization rules, and then the list of words is prepended to the
  command that will be executed.
</p>
<p>
  If the first word is a fully qualified label (i.e. starts with
  <code>//</code>) it is built. Then the label is substituted by the
  corresponding executable location that is prepended to the command
  that will be executed along with the other words.
</p>

<p>
Some caveats apply:
</p>
<ul>
  <li>
    The PATH used for running tests may be different than the PATH in your environment,
    so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code>
    command (the first word in <var>command-prefix</var>).
  </li>
  <li>
    <b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code>
    can't be used for interactive commands.
  </li>

</ul>
<p>
Examples:
</p>
<pre>
        --run_under=/usr/bin/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-&lt;workspace&gt;</code>
    is placed there pointing to this directory.
  </li>
  <li><code>output_path</code>: the absolute path to the output
    directory beneath the execution root used for all files actually
    generated as a result of build commands. If the workspace directory is
    writable, a symlink named <code>bazel-out</code> is placed there pointing
    to this directory.
    </li>
  <li><code>server_pid</code>: the process ID of the Bazel server
     process. </li>
  <li><code>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--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>

<p>
  By default, command will just print help message outlining possible
  options to dump specific areas of the Bazel state. In order to dump
  internal state, at least one of the options must be specified.
</p>
<p>
  Following options are supported:
</p>
<ul>
  <li><code class='flag'>--action_cache</code> dumps action cache content.</li>
  <li><code class='flag'>--packages</code> dumps package cache content.</li>
  <li><code class='flag'>--vfs</code> dumps VFS state.</li>
  <li><code class='flag'>--skyframe</code> dumps state of internal Bazel dependency graph.</li>
  <li><code class='flag'>--rules</code> dumps rule summary for each rule and aspect class,
    including counts and action counts. This includes both native and Skylark rules.
    If memory tracking is enabled, then the rules' memory consumption is also printed.</li>
  <li><code class='flag'>--skylark_memory</code> dumps a
    <href a=https://github.com/google/pprof>pprof</href> compatible .gz file to the specified path.
    You must enable memory tracking for this to work.</li>
  <li><code class='flag'>--action_graph=/path/to/file</code> dumps the state of
    the internal Bazel action graph in proto format to
    <code>/path/to/file</code>. You have to run (at least) the analysis phase
    for the targets you are interested in (for example, <code>bazel build --nobuild
    //foo:bar</code>). Note that this feature is still experimental, subject to
    change and will probably be integrated into <code>cquery</code> in the
    future.
  <li><code class='flag'>--action_graph:targets=target1,target2,...</code>
    filters the actions to the comma-separated list of targets when dumping the
    action graph.</li>
</ul>

  <h4 id='memory-tracking'>Memory tracking</h4>
  <p>
    Some <code>dump</code> commands require memory tracking. To turn this on, you have to pass
    startup flags to Bazel:
  </p>
  <ul>
    <li><code>--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar</code></li>
    <li><code>--host_jvm_args=-DRULE_MEMORY_TRACKER=1</code></li>
  </ul>
  <p>
    The java-agent is checked into bazel at
    third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar, so make
    sure you adjust <code>$BAZEL</code> for where you keep your bazel repository.

    Do not forget to keep passing these options to Bazel for every command or the server will
    restart.
  </p>
  <p>Example:</p>
  <pre>
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    build --nobuild &lt;targets&gt;

    # Dump rules
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --rules

    # Dump Skylark heap and analyze it with pprof
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --skylark_memory=$HOME/prof.gz
    % pprof -flame $HOME/prof.gz
  </pre>
<h3 id='analyze-profile'>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_johndoe/d41d8cd98f00b204e9800998ecf8427e</code>.
  Note that the client uses the output base to find the Bazel server
  instance, so if you specify a different output base in a Bazel
  command, a different server will be found (or started) to handle the
  request.  It's possible to perform two concurrent builds in the same
  workspace directory by varying the output base.
</p>

<p>For example:</p>
<pre>
  % bazel --output_base /tmp/1 build //foo  &amp;  bazel --output_base /tmp/2 build //bar
</pre>
<p>
  In this command, the two Bazel commands run concurrently (because of
  the shell <code>&amp;</code> operator), each using a different Bazel
  server instance (because of the different output bases).
  In contrast, if the default output base was used in both commands,
  then both requests would be sent to the same server, which would
  handle them sequentially: 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='startup_flag--host_javabase'><code class='flag'>--host_javabase=<var>dir</var></code></h4>
<p>
  Specifies the Java virtual machine in which <i>Bazel itself</i> runs. The value must be a path to
  the directory containing a JDK or JRE. It should not be a label.
  This option should appear before any bazel command, and not be confused with the build option
  <a href='#flag--host_javabase'>--host_javabase</a>, for example:
</p>
<pre>
  % bazel --host_javabase=/usr/local/buildtools/java/jdk9 build //foo
</pre>
<p>
  This flag does <i>not</i> affect the JVMs used by Bazel subprocesses such as applications, tests,
  tools, and so on. Use build options <a href='#flag--javabase'>--javabase</a> or
  <a href='#flag--host_javabase'>--host_javabase</a> instead.
</p>

<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 more likely to
  fail.  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>&lt;profile-file&gt;.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 &ndash;
    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-&lt;workspace&gt;</code>
  symlink in your workspace directory.
</p>