diff options
6 files changed, 3913 insertions, 36 deletions
diff --git a/site/blog/_posts/2015-06-25-ErrorProne.md b/site/blog/_posts/2015-06-25-ErrorProne.md new file mode 100644 index 0000000000..d79d87accb --- /dev/null +++ b/site/blog/_posts/2015-06-25-ErrorProne.md @@ -0,0 +1,17 @@ +--- +layout: posts +title: Checking your Java errors with Error Prone. +--- + +We recently open-sourced our support for [Error Prone](http://errorprone.info). +[Error Prone](http://errorprone.info) checks for common mistakes in Java code +that will not be caught by the compiler. + +We turned [Error Prone](http://errorprone.info) on by default but you can easily +turn it off by using the Javac option `-XepDisableAllChecks`. To do so, simply +specify `--javacopt='XepDisableAllChecks` to the list of Bazel's options. You +can also tune the checks error-prone will perform by using the [`-Xep:` +flags](http://errorprone.info/docs/flags). + +See the [documentation of Error Prone](http://errorprone.info/docs/installation) for more +on Error Prone. diff --git a/site/blog/_posts/2015-07-08-Java-Configuration.md b/site/blog/_posts/2015-07-08-Java-Configuration.md new file mode 100644 index 0000000000..2d0a3c70c5 --- /dev/null +++ b/site/blog/_posts/2015-07-08-Java-Configuration.md @@ -0,0 +1,43 @@ +--- +layout: posts +title: Configuring your Java builds +--- + +Let say that you want to build for Java 8 and Error Prone checks off but keep +the tools directory provided with Bazel in the package path, you could do that +by having the following rc file: + +``` +build --javacopt=-XepDisableAllChecks +build --javacopt="-source 8 -target 8" +``` + +However, the file would becomes quickly overloaded, especially if you take +all languages and options into account. Instead, you can tweak the +[java_toolchain](https://github.com/bazelbuild/bazel/tree/0e1680e58f01f3d443f7e68865b5a56b76c9dadf/tools/jdk/BUILD#L73) +rule that specifies the various options for the java compiler. So in a +BUILD file: + +```python +java_toolchain( + name = "my_toolchain", + encoding = "UTF-8", + source_version = "8", + target_version = "8", + misc = [ + "-Xep:CollectionIncompatibleType:ERROR", # http://errorprone.info/bugpattern/CollectionIncompatibleType + ], +) +``` + +And to keep it out of the tools directory (or you need to copy the rest +of the package), you can redirect the default one in a bazelrc: + +``` +build --java_toolchain=//package:my_toolchain +``` + +In the future, toolchain rules should be the configuration points for all +the languages but it is a long road. We also want to make it easier to +rebind the toolchain using the `bind` rule in the WORKSPACE file. + diff --git a/site/versions/master/docs/blaze-user-manual.html b/site/versions/master/docs/blaze-user-manual.html new file mode 100644 index 0000000000..b3a93af3ea --- /dev/null +++ b/site/versions/master/docs/blaze-user-manual.html @@ -0,0 +1,3836 @@ +--- +layout: documentation +title: User Manual +--- +<h1>A User's Guide to Bazel</h1> + +<h2 id='overview'>Bazel overview</h2> + +<p> + To run Bazel, go to + + your base <a href="/docs/build-ref.html#workspaces">workspace</a> directory + or any of its subdirectories and type <code>bazel</code>. +</p> + +<pre> + % bazel help + [Bazel release bazel-<<i>version</i>>] + Usage: bazel <command> <options> ... + + Available commands: + <a href='#analyze-profile'>analyze-profile</a> Analyzes build profile data. + <a href='#build'>build</a> Builds the specified targets. + + <a href='#canonicalize'>canonicalize-flags</a> Canonicalize Bazel flags. + <a href='#clean'>clean</a> Removes output files and optionally stops the server. + + <a href='#help'>help</a> Prints help for commands, or the index. + + <a href='#info'>info</a> Displays runtime info about the bazel server. + + <a href='#fetch'>fetch</a> Fetches all external dependencies of a target. + <a href='#mobile-install'>mobile-install</a> Installs apps on mobile devices. + + <a href='#query'>query</a> Executes a dependency graph query. + + <a href='#run'>run</a> Runs the specified target. + <a href='#shutdown'>shutdown</a> Stops the Bazel server. + <a href='#test'>test</a> Builds and runs the specified test targets. + <a href='#version'>version</a> Prints version information for Bazel. + + Getting more help: + bazel help <command> + Prints help and options for <command>. + bazel help <a href='#startup_options'>startup_options</a> + Options for the JVM hosting Bazel. + bazel help <a href='#target-patterns'>target-syntax</a> + Explains the syntax for specifying targets. + bazel help info-keys + Displays a list of keys used by the info command. + +</pre> +<p> + The <code>bazel</code> tool performs many functions, called + commands; users of CVS and Subversion will be familiar + with this "Swiss army knife" arrangement. The most commonly used one is of + course <code>bazel build</code>. You can browse the online help + messages using <code>bazel help</code>. +</p> + +<h3 id='client/server'>Client/server implementation</h3> + +<p> + The Bazel system is implemented as a long-lived server process. + This allows it to perform many optimizations not possible with a + batch-oriented implementation, such as caching of BUILD files, + dependency graphs, and other metadata from one build to the + next. This improves the speed of incremental builds, and allows + different commands, such as <code>build</code> + and <code>query</code> to share the same cache of loaded packages, + making queries very fast. +</p> +<p> + When you run <code>bazel</code>, you're running the client. The + client finds the server based on the output base, which by default is + determined by the path of the base workspace directory and your + userid, so if you build in multiple workspaces, you'll have multiple + output bases and thus multiple Bazel server processes. Multiple + users on the same workstation can build concurrently in the same + workspace because their output bases will differ (different userids). + If the client cannot find a running server instance, it starts a new + one. The server process will stop after a period of inactivity (3 hours, + by default). +</p> +<p> + For the most part, the fact that there is a server running is + invisible to the user, but sometimes it helps to bear this in mind. + For example, if you're running scripts that perform a lot of + automated builds in different directories, it's important to ensure + that you don't accumulate a lot of idle servers; you can do this by + explicitly shutting them down when you're finished with them, or by + specifying a short timeout period. +</p> +<p> + The name of a Bazel server process appears in the output of <code>ps + x</code> or <code>ps -e f</code> as + <code>bazel(<i>dirname</i>)</code>, where <i>dirname</i> is the + basename of the directory enclosing the root your workspace directory. + For example: +</p> +<pre> + % ps -e f + 16143 ? Sl 3:00 bazel(src-jrluser2) -server -Djava.library.path=... +</pre> +<p> + This makes it easier to find out which server process belongs to a + given workspace. (Beware that with certain other options + to <code>ps</code>, Bazel server processes may be named just + <code>java</code>.) Bazel servers can be stopped using + the <a href='#shutdown'>shutdown</a> command. +</p> +<p> + You can also run Bazel in batch mode using the <code>--batch</code> + startup flag. This will immediately shut down the process after the + command (build, test, etc.) has finished and not keep a server process + around. +</p> + +<p> + When running <code>bazel</code>, the client first checks that the + server is the appropriate version; if not, the server is stopped and + a new one started. This ensures that the use of a long-running + server process doesn't interfere with proper versioning. +</p> + +<h3 id='bazelrc'><code>.bazelrc</code>, the Bazel configuration file, +the <code class='flag'>--bazelrc=<var>file</var></code> option, and the +<code class='flag'>--config=<var>value</var></code> option</h3> + +<p> + Bazel accepts many options. Typically, some of these are varied + frequently (e.g. <code class='flag'>--subcommands</code>) while others stay the + same across several builds (e.g. <code class='flag'>--package_path</code>). + To avoid having to specify these constant options every time you do + a build or run some other Bazel command, Bazel allows you to + specify options in a configuration file. +</p> +<p> + Bazel looks for an optional configuration file in the location + specified by the <code class='flag'>--bazelrc=<var>file</var></code> option. If + this option is not specified then, by default, Bazel looks for the + file called <code>.bazelrc</code> in one of two directories: first, + in your base workspace directory, then in your home directory. If + it finds a file in the first (workspace-specific) location, it will + not look at the second (global) location. +</p> +<p> + The <code class='flag'>--bazelrc=<var>file</var></code> option must + appear <em>before</em> the command name (e.g. <code>build</code>). +</p> +<p> + The option <code class='flag'>--bazelrc=/dev/null</code> effectively disables the + use of a configuration file. We strongly recommend that you use + this option when performing release builds, or automated tests that + invoke Bazel. +</p> + +<p> + Aside from the configuration file described above, Bazel also looks + for a master configuration file next to the binary, in the workspace + at <code>tools/bazel.rc</code> or system-wide at + <code>/etc/bazel.bazelrc</code>. These files are here to support + installation-wide options or options shared between users. +</p> +<p> + Like all UNIX "rc" files, the <code>.bazelrc</code> file is a text + file with a line-based grammar. Lines starting <code>#</code> are + considered comments and are ignored, as are blank lines. Each line + contains a sequence of words, which are tokenized according to the + same rules as the Bourne shell. + The first word on each line is the name of a Bazel command, such + as <code>build</code> or <code>query</code>. The remaining words + are the default options that apply to that command. + More than one line may be used for a command; the options are combined + as if they had appeared on a single line. + (Users of CVS, another tool with a "Swiss army knife" command-line + interface, will find the syntax familiar to that of <code>.cvsrc</code>.) +</p> +<p> + Startup options may be specified in the + <code>.bazelrc</code> file using the command <code>startup</code>. + These options are described in the interactive help + at <code>bazel help startup_options</code>. +</p> +<p> + Options specified in the command line always take precedence over + those from a configuration file. In configuration files, lines for a more specific command take + precedence over lines for a less specific command (e.g. the 'test' command inherits all the + options from the 'build' command, so a 'test --foo=bar' line takes precedence over a + 'build --foo=baz' line, regardless of which configuration files these two lines are in) and lines + equally specific for which command they apply have precedence based on the configuration file they + are in, with the user-specific configuration file taking precedence over the master one. +</p> +<p> + Options may include words other than flags, such as the names of + build targets, etc; these are always prepended to the explicit + argument list provided on the command-line, if any. +</p> +<p> + Common command options may be specified in the + <code>.bazelrc</code> file using the command <code>common</code>. +</p> +<p> + In addition, commands may have <code>:name</code> suffixes. These + options are ignored by default, but can be pulled in through the + <code>--config=<var>name</var></code> option, either on the command line or in + a <code>.bazelrc</code> file. The intention is that these bundle command line + options that are commonly used together, for example + <code>--config=memcheck</code>. +</p> +<p> + Note that some config sections are defined in the master bazelrc file. + To avoid conflicts, user-defined sections + should start with the '_' (underscore) character. +</p> +<p> + The command named <code>import</code> is special: if Bazel encounters such + a line in a <code>.bazelrc</code> file, it parses the contents of the file + referenced by the import statement, too. Options specified in an imported file + take precedence over ones specified before the import statement, options + specified after the import statement take precedence over the ones in the + imported file, and options in files imported later take precedence over files + imported earlier. +</p> +<p> + Here's an example <code>~/.bazelrc</code> file: +</p> +<pre> + # Bob's Bazel option defaults + + startup --batch --host_jvm_args=-XX:-UseParallelGC + import /home/bobs_project/bazelrc + build --show_timestamps --keep_going --jobs 600 + build --color=yes + query --keep_going + + build:memcheck --strip=never --test_timeout=3600 +</pre> + +<h2 id='build'>Building programs with Bazel</h2> +<h3>The <code>build</code> command</h3> + +<p> + The most important function of Bazel is, of course, building code. Type + <code>bazel build</code> followed by the name of the + <a href="#target-patterns">target</a> you wish to build. Here's a typical + session: +</p> +<pre> + % bazel build //foo + ____Loading package: foo + ____Loading package: bar + ____Loading package: baz + ____Loading complete. Analyzing... + ____Building 1 target... + ____[0 / 3] Executing Genrule //bar:helper_rule + ____[1 / 3] Executing Genrule //baz:another_helper_rule + ____[2 / 3] Building foo/foo.bin + Target //foo:foo up-to-date: + bazel-bin/foo/foo.bin + bazel-bin/foo/foo + ____Elapsed time: 9.905s +</pre> +<p> + Bazel prints the progress messages as it loads all the + packages in the transitive closure of dependencies of the requested + target, then analyzes them for correctness and to create the build actions, + finally executing the compilers and other tools of the build. +</p> +<p> + Bazel prints progress messages during + the <a href='#execution-phase'>execution phase</a> of the build, showing the + current build step (compiler, linker, etc.) that is being started, + and the number of completed over total number of build actions. As the + build starts the number of total actions will often increase as Bazel + discovers the entire action graph, but the number will usually stabilize + within a few seconds. +</p> +<p> + At the end of the build Bazel + prints which targets were requested, whether or not they were + successfully built, and if so, where the output files can be found. + Scripts that run builds can reliably parse this output; see <a + href='#flag--show_result'><code class='flag'>--show_result</code></a> for more + details. +</p> +<p> + Typing the same command again: +</p> +<pre> + % bazel build //foo + ____Loading... + ____Found 1 target... + ____Building complete. + Target //foo:foo up-to-date: + bazel-bin/foo/foo.bin + bazel-bin/foo/foo + ____Elapsed time: 0.280s +</pre> +<p> + we see a "null" build: in this case, there are no packages to + re-load, since nothing has changed, and no build steps to execute. + (If something had changed in "foo" or some of its dependencies, resulting in the + reexecution of some build actions, we would call it an "incremental" build, not a + "null" build.) +</p> + +<p> + Before you can start a build, you will need a Bazel workspace. This is + simply a directory tree that contains all the source files needed to build + your application. + Bazel allows you to perform a build from a completely read-only volume. +</p> + +<h4 id='flag--package_path'>Setting up a <code class='flag'>--package_path</code></h4> +<p> + Bazel finds its packages by searching the package path. This is a colon + separated ordered list of bazel directories, each being the root of a + partial source tree. +</p> + +<p> + <i>To specify a custom package path</i> using the + <code class='flag'>--package_path</code> option: +</p> +<pre> + % bazel build --package_path %workspace%:/some/other/root +</pre> +<p> +Package path elements may be specified in three formats: +</p> +<ol> + <li> + If the first character is <code>/</code>, the path is absolute. + </li> + <li> + If the path starts with <code>%workspace%</code>, the path is taken relative + to the nearest enclosing bazel directory.<br> + For instance, if your working directory + is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the + string <code>%workspace%</code> in the package-path is expanded + to <code>/home/bob/clients/bob_client/bazel</code>. + </li> + <li> + Anything else is taken relative to the working directory.<br> This is usually not what you mean to do, + and may behave unexpectedly if you use Bazel from directories below the bazel workspace. + For instance, if you use the package-path element <code>.</code>, + and then cd into the directory + <code>/home/bob/clients/bob_client/bazel/foo</code>, packages + will be resolved from the + <code>/home/bob/clients/bob_client/bazel/foo</code> directory. + </li> +</ol> +<p> + If you use a non-default package path, we recommend that you specify + it in your <a href='#bazelrc'>Bazel configuration file</a> for + convenience. +</p> +<p> + <i>Bazel doesn't require any packages to be in the + current directory</i>, so you can do a build from an empty bazel + workspace if all the necessary packages can be found somewhere else + on the package path. +</p> +<p> + <i>Example</i>: Building from an empty client +</p> +<pre> + % mkdir -p foo/bazel + % cd foo/bazel + % bazel build --package_path /some/other/path //foo +</pre> +<h3 id='target-patterns'>Specifying targets to build</h3> +<p> + Bazel allows a number of ways to specify the targets to be built. + Collectively, these are known as <i>target patterns</i>. + The on-line help displays a summary of supported patterns: +</p> +<pre> +% bazel help target-syntax + +Target pattern syntax +===================== + +The BUILD file label syntax is used to specify a single target. Target +patterns generalize this syntax to sets of targets, and also support +working-directory-relative forms, recursion, subtraction and filtering. +Examples: + +Specifying a single target: + + //foo/bar:wiz The single target '//foo/bar:wiz'. + foo/bar/wiz Equivalent to: + '//foo/bar/wiz:wiz' if foo/bar/wiz is a package, + '//foo/bar:wiz' if foo/bar is a package, + '//foo:bar/wiz' otherwise. + //foo/bar Equivalent to '//foo/bar:bar'. + +Specifying all rules in a package: + + //foo/bar:all Matches all rules in package 'foo/bar'. + +Specifying all rules recursively beneath a package: + + //foo/...:all Matches all rules in all packages beneath directory 'foo'. + //foo/... (ditto) + + By default, directory symlinks are followed when performing this recursive traversal, except + those that point to under the output base (for example, the convenience symlinks that are created + in the root directory of the workspace) But we understand that your workspace may intentionally + contain directories with unusual symlink structures that you don't want consumed. As such, if a + directory has a file named + 'DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN' then symlinks + in that directory won't be followed when evaluating recursive target patterns. + +Working-directory relative forms: (assume cwd = 'workspace/foo') + + Target patterns which do not begin with '//' are taken relative to + the working directory. Patterns which begin with '//' are always + absolute. + + ...:all Equivalent to '//foo/...:all'. + ... (ditto) + + bar/...:all Equivalent to '//foo/bar/...:all'. + bar/... (ditto) + + bar:wiz Equivalent to '//foo/bar:wiz'. + :foo Equivalent to '//foo:foo'. + + bar Equivalent to '//foo/bar:bar'. + foo/bar Equivalent to '//foo/foo/bar:bar'. + + bar:all Equivalent to '//foo/bar:all'. + :all Equivalent to '//foo:all'. + +Summary of target wildcards: + + :all, Match all rules in the specified packages. + :*, :all-targets Match all targets (rules and files) in the specified + packages, including ones not built by default, such + as _deploy.jar files. + +Subtractive patterns: + + Target patterns may be preceded by '-', meaning they should be + subtracted from the set of targets accumulated by preceding + patterns. (Note that this means order matters.) For example: + + % bazel build -- foo/... -foo/contrib/... + + builds everything in 'foo', except 'contrib'. In case a target not + under 'contrib' depends on something under 'contrib' though, in order to + build the former bazel has to build the latter too. As usual, the '--' is + required to prevent '-f' from being interpreted as an option. +</pre> +<p> + Whereas <a href="build-ref.html#labels">labels</a> are used + to specify individual targets, e.g. for declaring dependencies in + BUILD files, Bazel's target patterns are a syntax for specifying + multiple targets: they are a generalization of the label syntax + for <i>sets</i> of targets, using wildcards. In the simplest case, + any valid label is also a valid target pattern, identifying a set of + exactly one target. +</p> +<p> + <code>foo/...</code> is a wildcard over <em>packages</em>, + indicating all packages recursively beneath + directory <code>foo</code> (for all roots of the package + path). <code>:all</code> is a wildcard + over <em>targets</em>, matching all rules within a package. These two may be + combined, as in <code>foo/...:all</code>, and when both wildcards + are used, this may be abbreviated to <code>foo/...</code>. +</p> +<p> + In addition, <code>:*</code> (or <code>:all-targets</code>) is a + wildcard that matches <em>every target</em> in the matched packages, + including files that aren't normally built by any rule, such + as <code>_deploy.jar</code> files associated + with <code>java_binary</code> rules. +</p> +<p> + This implies that <code>:*</code> denotes a <em>superset</em> + of <code>:all</code>; while potentially confusing, this syntax does + allow the familiar <code>:all</code> wildcard to be used for + typical builds, where building targets like the <code>_deploy.jar</code> + is not desired. +</p> +<p> + In addition, Bazel allows a slash to be used instead of the colon + required by the label syntax; this is often convenient when using + Bash filename expansion. For example, <code>foo/bar/wiz</code> is + equivalent to <code>//foo/bar:wiz</code> (if there is a + package <code>foo/bar</code>) or to <code>//foo:bar/wiz</code> (if + there is a package <code>foo</code>). +</p> +<p> + Many Bazel commands accept a list of target patterns as arguments, + and they all honor the prefix negation operator `<code>-</code>'. + This can be used to subtract a set of targets from the set specified + by the preceding arguments. (Note that this means order matters.) + For example, +</p> +<pre> + bazel build foo/... bar/... +</pre> +<p> + means "build all + targets beneath <code>foo</code> <i>and</i> all targets + beneath <code>bar</code>", whereas +</p> +<pre> + bazel build -- foo/... -foo/bar/... +</pre> +<p> + means "build all targets beneath <code>foo</code> <i>except</i> + those beneath <code>foo/bar</code>". + + (The <code>--</code> argument is required to prevent the subsequent + arguments starting with <code>-</code> from being interpreted as + additional options.) +</p> +<p> + It's important to point out though that subtracting targets this way will not + guarantee that they are not built, since they may be dependencies of targets + that weren't subtracted. For example, if there were a target + <code>//foo:all-apis</code> that among others depended on + <code>//foo/bar:api</code>, then the latter would be built as part of + building the former. +</p> +<p> + Targets with <code>tags=["manual"]</code> will not be included in wildcard target patterns (..., + :*, :all, etc). You should specify such test targets with explicit target patterns on the command + line if you want Bazel to build/test them. +</p> + +<h3 id='fetch'>Fetching external dependencies</h3> + +<p> + By default, Bazel will download and symlink external dependencies during the + build. However, this can be undesirable, either because you'd like to know + when new external dependendencies are added or because you'd like to + "prefetch" dependencies (say, before a flight where you'll be offline). If you + would like to prevent new dependencies from being added during builds, you + can specify the <code>--fetch=false</code> flag. Note that this flag only + applies to repository rules that do not point to a directory in the local + file system. Changes, for example, to <code>local_repository</code>, + <code>new_local_repository</code> and Android SDK and NDK repository rules + will always take effect regardless of the value <code>--fetch</code> . +</p> + +<p> + If you disallow fetching during builds and Bazel finds new external + dependencies, your build will fail. +</p> + +<p> + You can manually fetch dependencies by running <code>bazel fetch</code>. If + you disallow during-build fetching, you'll need to run <code>bazel + fetch</code>: + <ol> + <li>Before you build for the first time. + <li>After you add a new external dependency. + </ol> + Once it has been run, you should not need to run it again until the WORKSPACE + file changes. +</p> + +<p> + <code>fetch</code> takes a list of targets to fetch dependencies for. For + example, this would fetch dependencies needed to build <code>//foo:bar</code> + and <code>//bar:baz</code>: +<pre> +$ bazel fetch //foo:bar //bar:baz +</pre> +</p> + +<p> + To fetch all external dependencies for a workspace, run: +<pre> +$ bazel fetch //... +</pre> +</p> + +<p> + You do not need to run bazel fetch at all if you have all of the tools you are + using (from library jars to the JDK itself) under your workspace root. + However, if you're using anything outside of the workspace directory then you + will need to run <code>bazel fetch</code> before running + <code>bazel build</code>. +</p> + +<h3 id='configurations'>Build configurations and cross-compilation</h3> + +<p> + All the inputs that specify the behavior and result of a given + build can be divided into two distinct categories. + The first kind is the intrinsic information stored in the BUILD + files of your project: the build rule, the values of its attributes, + and the complete set of its transitive dependencies. + The second kind is the external or environmental data, supplied by + the user or by the build tool: the choice of target architecture, + compilation and linking options, and other toolchain configuration + options. We refer to a complete set of environmental data as + a <b>configuration</b>. +</p> +<p> + In any given build, there may be more than one configuration. + Consider a cross-compile, in which you build + a <code>//foo:bin</code> executable for a 64-bit architecture, + but your workstation is a 32-bit machine. Clearly, the build + will require building <code>//foo:bin</code> using a toolchain + capable of creating 64-bit executables, but the build system must + also build various tools used during the build itself—for example + tools that are built from source, then subsequently used in, say, a + genrule—and these must be built to run on your workstation. + Thus we can identify two configurations: the <b>host + configuration</b>, which is used for building tools that run during + the build, and the <b>target configuration</b> (or <i>request + configuration</i>, but we say "target configuration" more often even + though that word already has many meanings), which is + used for building the binary you ultimately requested. +</p> +<p> + Typically, there are many libraries that are prerequisites of both + the requested build target (<code>//foo:bin</code>) and one or more of + the host tools, for example some base libraries. Such libraries must be built + twice, once for the host configuration, and once for the target + configuration.<br/> + Bazel takes care of ensuring that both variants are built, and that + the derived files are kept separate to avoid interference; usually + such targets can be built concurrently, since they are independent + of each other. If you see progress messages indicating that a given + target is being built twice, this is most likely the explanation. +</p> +<p> + Bazel uses one of two ways to select the host configuration, based + on the <code class='flag'>--distinct_host_configuration</code> option. This + boolean option is somewhat subtle, and the setting may improve (or + worsen) the speed of your builds. +</p> + +<h4><code class='flag'>--distinct_host_configuration=false</code></h4> +<p> + When this option is false, the host and + request configurations are identical: all tools required during the + build will be built in exactly the same way as target programs. + This setting means that no libraries need to be built twice during a + single build, so it keeps builds short. + However, it does mean that any change to your request configuration + also affects your host configuration, causing all the tools to be + rebuilt, and then anything that depends on the tool output to be + rebuilt too. Thus, for example, simply changing a linker option + between builds might cause all tools to be re-linked, and then all + actions using them reexecuted, and so on, resulting in a very large rebuild. + Also, please note: if your host architecture is not capable of + running your target binaries, your build will not work. +</p> +<p> + If you frequently make changes to your request configuration, such + as alternating between <code>-c opt</code> and <code>-c dbg</code> + builds, or between simple- and cross-compilation, we do not + recommend this option, as you will typically rebuild the majority of + your codebase each time you switch. +</p> + +<h4><code class='flag'>--distinct_host_configuration=true</code> <i>(default)</i></h4> +<p> + If this option is true, then instead of using the same configuration + for the host and request, a completely distinct host configuration + is used. The host configuration is derived from the target + configuration as follows: +</p> +<ul> + <li>Use the same version of Crosstool + (<code class='flag'>--crosstool_top</code>) as specified in the request + configuration, unless <code class='flag'>--host_crosstool_top</code> is + specified. + </li> + <li> + Use the value of <code class="flag">--host_cpu</code> for + <code class='flag'>--cpu</code> + + (default: <code>k8</code>). + </li> + <li>Use the same values of these options as specified in the request + configuration: + <code class='flag'>--compiler</code>, + <code class='flag'>--use_ijars</code>, + <code class='flag'>--java_toolchain</code>, + If <code class='flag'>--host_crosstool_top</code> is used, then the value of + <code class='flag'>--host_cpu</code> is used to look up a + <code>default_toolchain</code> in the Crosstool + (ignoring <code class='flag'>--compiler</code>) for the host configuration. + </li> + <li>Use optimized builds for C++ code (<code>-c opt</code>). + </li> + <li>Generate no debugging information (<code class='flag'>--copt=-g0</code>). + </li> + <li>Strip debug information from executables and shared libraries + (<code class='flag'>--strip=always</code>). + </li> + <li>Place all derived files in a special location, distinct from + that used by any possible request configuration. + </li> + <li>Suppress stamping of binaries with build data + (see <code class='flag'>--embed_*</code> options). + </li> + <li>All other values remain at their defaults. + </li> +</ul> +<p> + There are many reasons why it might be preferable to select a + distinct host configuration from the request configuration. + Some are too esoteric to mention here, but two of them are worth + pointing out. +</p> +<p> + Firstly, by using stripped, optimized binaries, you reduce the time + spent linking and executing the tools, the disk space occupied by + the tools, and the network I/O time in distributed builds. +</p> +<p> + Secondly, by decoupling the host and request configurations in all + builds, you avoid very expensive rebuilds that would result from + minor changes to the request configuration (such as changing a linker options + does), as described earlier. +</p> +<p> + That said, for certain builds, this option may be a hindrance. In + particular, builds in which changes of configuration are infrequent + (especially certain Java builds), and builds where the amount of code that + must be built in both host and target configurations is large, may + not benefit. +</p> + +<h3 id='correctness'>Correct incremental rebuilds</h3> + +<p> + One of the primary goals of the Bazel project is to ensure correct + incremental rebuilds. Previous build tools, especially those based + on Make, make several unsound assumptions in their implementation of + incremental builds. +</p> +<p> + Firstly, that timestamps of files increase monotonically. While + this is the typical case, it is very easy to fall afoul of this + assumption; syncing to an earlier revision of a file causes that file's + modification time to decrease; Make-based systems will not rebuild. +</p> +<p> + More generally, while Make detects changes to files, it does + not detect changes to commands. If you alter the options passed to + the compiler in a given build step, Make will not re-run the + compiler, and it is necessary to manually discard the invalid + outputs of the previous build using <code>make clean</code>. +</p> +<p> + Also, Make is not robust against the unsuccessful termination of one + of its subprocesses after that subprocess has started writing to + its output file. While the current execution of Make will fail, the + subsequent invocation of Make will blindly assume that the truncated + output file is valid (because it is newer than its inputs), and it + will not be rebuilt. Similarly, if the Make process is killed, a + similar situation can occur. +</p> +<p> + Bazel avoids these assumptions, and others. Bazel maintains a database + of all work previously done, and will only omit a build step if it + finds that the set of input files (and their timestamps) to that + build step, and the compilation command for that build step, exactly + match one in the database, and, that the set of output files (and + their timestamps) for the database entry exactly match the + timestamps of the files on disk. Any change to the input files or + output files, or to the command itself, will cause re-execution of + the build step. +</p> +<p> + The benefit to users of correct incremental builds is: less time + wasted due to confusion. (Also, less time spent waiting for + rebuilds caused by use of <code>make clean</code>, whether necessary + or pre-emptive.) +</p> + +<h4>Build consistency and incremental builds</h4> +<p> + Formally, we define the state of a build as <i>consistent</i> when + all the expected output files exist, and their contents are correct, + as specified by the steps or rules required to create them. When + you edit a source file, the state of the build is said to + be <i>inconsistent</i>, and remains inconsistent until you next run + the build tool to successful completion. We describe this situation + as <i>unstable inconsistency</i>, because it is only temporary, and + consistency is restored by running the build tool. +</p> +<p> + There is another kind of inconsistency that is pernicious: <i>stable + inconsistency</i>. If the build reaches a stable inconsistent + state, then repeated successful invocation of the build tool does + not restore consistency: the build has gotten "stuck", and the + outputs remain incorrect. Stable inconsistent states are the main + reason why users of Make (and other build tools) type <code>make + clean</code>. Discovering that the build tool has failed in this + manner (and then recovering from it) can be time consuming and very + frustrating. +</p> +<p> + Conceptually, the simplest way to achieve a consistent build is to + throw away all the previous build outputs and start again: make + every build a clean build. This approach is obviously too + time-consuming to be practical (except perhaps for release + engineers), and therefore to be useful, the build tool must be able + to perform incremental builds without compromising consistency. +</p> +<p> + Correct incremental dependency analysis is hard, and as described + above, many other build tools do a poor job of avoiding stable + inconsistent states during incremental builds. In contrast, Bazel + offers the following guarantee: after a successful invocation of the + build tool during which you made no edits, the build will be in a + consistent state. (If you edit your source files during a build, + Bazel makes no guarantee about the consistency of the result of the + current build. But it does guarantee that the results of + the <i>next</i> build will restore consistency.) +</p> +<p> + As with all guarantees, there comes some fine print: there are some + known ways of getting into a stable inconsistent state with Bazel. + We won't guarantee to investigate such problems arising from deliberate + attempts to find bugs in the incremental dependency analysis, but we + will investigate and do our best to fix all stable inconsistent + states arising from normal or "reasonable" use of the build tool. +</p> +<p> + If you ever detect a stable inconsistent state with Bazel, please report a bug. + +</p> + +<h4 id='sandboxing'>Sandboxed execution</h4> +<p> + Bazel uses sandboxes to guarantee that actions run hermetically<sup>1</sup> and correctly. + Bazel runs <i>Spawn</i>s (loosely speaking: actions) in sandboxes that only contain the minimal + set of files the tool requires to do its job. Currently sandboxing works on Linux 3.12 or newer + with the <code>CONFIG_USER_NS</code> option enabled, and also on Mac OS 10.11 for newer. +</p> +<p> + Bazel will print a warning if your system does not support sandboxing to alert you to the fact + that builds are not guaranteed to be hermetic and might affect the host system in unknown ways. + To disable this warning you can pass the <code>--ignore_unsupported_sandboxing</code> flag to + Bazel. +</p> + +<p> + On some platforms such as <a href="https://cloud.google.com/container-engine/">Google Container + Engine</a> cluster nodes or Debian, user namespaces are deactivated by default due to security + concerns. This can be checked by looking at the file + <code>/proc/sys/kernel/unprivileged_userns_clone</code>: if it exists and contains a 0, then + user namespaces can be activated with <code>sudo sysctl kernel.unprivileged_userns_clone=1</code>. +</p> +<p> + In some cases, the Bazel sandbox fails to execute rules because of the system setup. The symptom + is generally a failure that output a message similar to + <code>namespace-sandbox.c:633: execvp(argv[0], argv): No such file or directory</code>. In that + case, try to deactivate the sandbox for genrules with <code>--genrule_strategy=standalone</code> + and for other rules with <code>--spawn_strategy=standalone</code>. Also please report a bug on our + issue tracker and mention which Linux distribution you're using so that we can investigate and + provide a fix in a subsequent release. +</p> + +<p> + <sup>1</sup>: Hermeticity means that the action only uses its declared input files and no other + files in the filesystem, and it only produces its declared output files. +</p> + +<h3 id='clean'>Deleting the outputs of a build</h3> + +<h4>The <code>clean</code> command</h4> + +<p> + Bazel has a <code>clean</code> command, analogous to that of Make. + It deletes the output directories for all build configurations performed + by this Bazel instance, or the entire working tree created by this + Bazel instance, and resets internal caches. If executed without any + command-line options, then the output directory for all configurations + will be cleaned. +</p> + +<p>Recall that each Bazel instance is associated with a single workspace, thus the + <code>clean</code> command will delete all outputs from all builds you've done + with that Bazel instance in that workspace. +</p> +<p> + To completely remove the entire working tree created by a Bazel + instance, you can specify the <code class='flag'>--expunge</code> option. When + executed with <code class='flag'>--expunge</code>, the clean command simply + removes the entire output base tree which, in addition to the build + output, contains all temp files created by Bazel. It also + stops the Bazel server after the clean, equivalent to the <a + href='#shutdown'><code>shutdown</code></a> command. For example, to + clean up all disk and memory traces of a Bazel instance, you could + specify: +</p> +<pre> + % bazel clean --expunge +</pre> +<p> + Alternatively, you can expunge in the background by using + <code class='flag'>--expunge_async</code>. It is safe to invoke a Bazel command + in the same client while the asynchronous expunge continues to run. + Note, however, that this may introduce IO contention. +</p> + +<p> + The <code>clean</code> command is provided primarily as a means of + reclaiming disk space for workspaces that are no longer needed. + However, we recognize that Bazel's incremental rebuilds might not be + perfect; <code>clean</code> may be used to recover a consistent + state when problems arise. +</p> +<p> + Bazel's design is such that these problems are fixable; we consider + such bugs a high priority, and will do our best fix them. If you + ever find an incorrect incremental build, please file a bug report. + We encourage developers to get out of the habit of + using <code>clean</code> and into that of reporting bugs in the + tools. +</p> + +<h3 id='phases'>Phases of a build</h3> + +<p> + In Bazel, a build occurs in three distinct phases; as a user, + understanding the difference between them provides insight into the + options which control a build (see below). +</p> + +<h4 id='loading-phase'>Loading phase</h4> +<p> + The first is <b>loading</b> during which all the necessary BUILD + files for the initial targets, and their transitive closure of + dependencies, are loaded, parsed, evaluated and cached. +</p> +<p> + For the first build after a Bazel server is started, the loading + phase typically takes many seconds as many BUILD files are loaded + from the file system. In subsequent builds, especially if no BUILD + files have changed, loading occurs very quickly. +</p> +<p> + Errors reported during this phase include: package not found, target + not found, lexical and grammatical errors in a BUILD file, + and evaluation errors. +</p> + +<h4 id='analysis-phase'>Analysis phase</h4> +<p> + The second phase, <b>analysis</b>, involves the semantic analysis + and validation of each build rule, the construction of a build + dependency graph, and the determination of exactly what work is to + be done in each step of the build. +</p> +<p> + Like loading, analysis also takes several seconds when computed in + its entirety. However, Bazel caches the dependency graph from + one build to the next and only reanalyzes what it has to, which can + make incremental builds extremely fast in the case where the + packages haven't changed since the previous build. +</p> +<p> + Errors reported at this stage include: inappropriate dependencies, + invalid inputs to a rule, and all rule-specific error messages. +</p> +<p> + The loading and analysis phases are fast because + Bazel avoids unnecessary file I/O at this stage, reading only BUILD + files in order to determine the work to be done. This is by design, + and makes Bazel a good foundation for analysis tools, such as + Bazel's <a href='#query'>query</a> command, which is implemented + atop the loading phase. +</p> + +<h4 id='execution-phase'>Execution phase</h4> +<p> + The third and final phase of the build is <b>execution</b>. This + phase ensures that the outputs of each step in the build are + consistent with its inputs, re-running compilation/linking/etc. tools as + necessary. This step is where the build spends the majority of + its time, ranging from a few seconds to over an hour for a large + build. Errors reported during this phase include: missing source + files, errors in a tool executed by some build action, or failure of a tool to + produce the expected set of outputs. +</p> + + +<h2>Options</h2> + +<p> + The following sections describe the options available during a + build. When <code class='flag'>--long</code> is used on a help command, the on-line + help messages provide summary information about the meaning, type and + default value for each option. +</p> + +<p> + Most options can only be specified once. When specified multiple times, the + last instance wins. Options that can be specified multiple times are + identified in the on-line help with the text 'may be used multiple times'. +</p> + +<h3>Options that affect how packages are located</h3> + +<p> + See also the <a href='#flag--show_package_location'><code class='flag'>--show_package_location</code></a> + option. +</p> + +<h4 id='flag--package_path'><code class='flag'>--package_path</code></h4> +<p> + This option specifies the set of directories that are searched to + find the BUILD file for a given package. + +</p> + +<h4 id='flag--deleted_packages'><code class='flag'>--deleted_packages</code></h4> +<p> + This option specifies a comma-separated list of packages which Bazel + should consider deleted, and not attempt to load from any directory + on the package path. This can be used to simulate the deletion of packages without + actually deleting them. +</p> + +<h3 id='checking-options'>Error checking options</h3> +<p> + These options control Bazel's error-checking and/or warnings. +</p> + +<h4 id='flag--check_constraint'><code class='flag'>--check_constraint <var>constraint</var></code></h4> +<p> + This option takes an argument that specifies which constraint + should be checked. +</p> +<p> + Bazel performs special checks on each rule that is annotated with the + given constraint. +</p> +<p> + The supported constraints and their checks are as follows: +</p> +<ul> + + <li><code>public</code>: Verify that all java_libraries marked with + <code>constraints = ['public']</code> only depend on java_libraries + that are marked as <code>constraints = ['public']</code> too. If bazel + finds a dependency that does not conform to this rule, bazel will issue + an error. + </li> +</ul> + +<h4 id='flag--check_visibility'><code class='flag'>--[no]check_visibility</code></h4> +<p> + If this option is set to false, visibility checks are demoted to warnings. + The default value of this option is true, so that by default, visibility + checking is done. + +</p> + +<h4 id='flag--experimental_action_listener'> + <code class='flag'>--experimental_action_listener=<var>label</var></code> +</h4> +<p> + The <code>experimental_action_listener</code> option instructs Bazel to use + details from the <a href="be/extra-actions.html#action_listener" + ><code>action_listener</code></a> rule specified by <var>label</var> to + insert <a href="be/extra-actions.html#extra_action" + ><code>extra_actions</code></a> into the build graph. +</p> + +<h4 id='flag--experimental_extra_action_filter'> + <code class='flag'>--experimental_extra_action_filter=<var>regex</var></code> +</h4> +<p> + The <code>experimental_extra_action_filter</code> option instructs Bazel to + filter the set of targets to schedule <code>extra_actions</code> for. +</p> +<p> + This flag is only applicable in combination with the + <a href='#flag--experimental_action_listener' + ><code>--experimental_action_listener</code></a> flag. +</p> +<p> + By default all <code>extra_actions</code> in the transitive closure of the + requested targets-to-build get scheduled for execution. + <code>--experimental_extra_action_filter</code> will restrict scheduling to + <code>extra_actions</code> of which the owner's label matches the specified + regular expression. +</p> +<p> + The following example will limit scheduling of <code>extra_actions</code> + to only apply to actions of which the owner's label contains '/bar/': +</p> +<pre>% bazel build --experimental_action_listener=//test:al //foo/... \ + --experimental_extra_action_filter=.*/bar/.* +</pre> + +<h4 id='flag--output_filter'><code class='flag'>--output_filter <var>regex</var></code></h4> +<p> + The <code class='flag'>--output_filter</code> option will only show build and compilation + warnings for targets that match the regular expression. If a target does not + match the given regular expression and its execution succeeds, its standard + output and standard error are thrown away. This option is intended to be used + to help focus efforts on fixing warnings in packages under development. Here + are some typical values for this option: +</p> +<table> + <tr> + <td><code class='flag'>--output_filter=</code></td> + <td>Show all output.</td> + </tr> + <tr> + <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td> + <td>Show the output for the specified packages.</td> + </tr> + <tr> + <td><code class='flag'>--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'</code></td> + <td>Don't show output for the specified packages.</td> + </tr> + <tr> + <td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td> + <td>Don't show output.</td> + </tr> +</table> + +<h4 id='flag--analysis_warnings_as_errors'><code>--[no]analysis_warnings_as_errors</code></h4> +<p> + When this option is enabled, visible analysis warnings (as specified by + the output filter) are treated as errors, effectively preventing the build + phase from starting. This feature can be used to enable strict builds that + do not allow new warnings to creep into a project. +</p> + +<h3 id='flags-options'>Flags options</h3> +<p> + These options control which options Bazel will pass to other tools. +</p> + +<h4 id='flag--copt'><code class='flag'>--copt <var>gcc-option</var></code></h4> +<p> + This option takes an argument which is to be passed to gcc. + The argument will be passed to gcc whenever gcc is invoked + for preprocessing, compiling, and/or assembling C, C++, or + assembler code. It will not be passed when linking. +</p> +<p> + This option can be used multiple times. + For example: +</p> +<pre> + % bazel build --copt="-g0" --copt="-fpic" //foo +</pre> +<p> + will compile the <code>foo</code> library without debug tables, generating + position-independent code. +</p> +<p> + Note that changing <code class='flag'>--copt</code> settings will force a recompilation + of all affected object files. Also note that copts values listed in specific + cc_library or cc_binary build rules will be placed on the gcc command line + <em>after</em> these options. +</p> +<p> + Warning: C++-specific options (such as <code>-fno-implicit-templates</code>) + should be specified in <code class='flag'>--cxxopt</code>, not in + <code class='flag'>--copt</code>. Likewise, C-specific options (such as -Wstrict-prototypes) + should be specified in <code class='flag'>--conlyopt</code>, not in <code>copt</code>. + Similarly, gcc options that only have an + effect at link time (such as <code>-l</code>) should be specified in + <code class='flag'>--linkopt</code>, not in <code class='flag'>--copt</code>. +</p> + +<h4 id='flag--host_copt'><code class='flag'>--host_copt <var>gcc-option</var></code></h4> +<p> + This option takes an argument which is to be passed to gcc for source files + that are compiled in the host configuration. This is analogous to + the <a href='#flag--copt'><code class='flag'>--copt</code></a> option, but applies only to the + host configuration. +</p> + +<h4 id='flag--host_cxxopt'><code class='flag'>--host_cxxopt <var>gcc-option</var></code></h4> +<p> + This option takes an argument which is to be passed to gcc for source files + that are compiled in the host configuration. This is analogous to + the <a href='#flag--cxxopt'><code class='flag'>--cxxopt</code></a> option, but applies only to the + host configuration. +</p> + +<h4 id='flag--conlyopt'><code class='flag'>--conlyopt <var>gcc-option</var></code></h4> +<p> + This option takes an argument which is to be passed to gcc when compiling C source files. +</p> +<p> + This is similar to <code class='flag'>--copt</code>, but only applies to C compilation, + not to C++ compilation or linking. So you can pass C-specific options + (such as <code>-Wno-pointer-sign</code>) using <code class='flag'>--conlyopt</code>. +</p> +<p> + Note that copts parameters listed in specific cc_library or cc_binary build rules + will be placed on the gcc command line <em>after</em> these options. +</p> + +<h4 id='flag--cxxopt'><code class='flag'>--cxxopt <var>gcc-option</var></code></h4> +<p> + This option takes an argument which is to be passed to gcc when compiling C++ source files. +</p> +<p> + This is similar to <code class='flag'>--copt</code>, but only applies to C++ compilation, + not to C compilation or linking. So you can pass C++-specific options + (such as <code>-fpermissive</code> or <code>-fno-implicit-templates</code>) using <code class='flag'>--cxxopt</code>. + For example: +</p> +<pre> + % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code +</pre> +<p> + Note that copts parameters listed in specific cc_library or cc_binary build rules + will be placed on the gcc command line <em>after</em> these options. +</p> + +<h4 id='flag--linkopt'><code class='flag'>--linkopt <var>linker-option</var></code></h4> +<p> + This option takes an argument which is to be passed to gcc when linking. +</p> +<p> + This is similar to <code class='flag'>--copt</code>, but only applies to linking, + not to compilation. So you can pass gcc options that only make sense + at link time (such as <code>-lssp</code> or <code>-Wl,--wrap,abort</code>) + using <code class='flag'>--linkopt</code>. For example: +</p> +<pre> + % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code +</pre> +<p> + Build rules can also specify link options in their attributes. This option's + settings always take precedence. Also see + <a href="be/c-cpp.html#cc_library.linkopts">cc_library.linkopts</a>. +</p> + +<h4 id='flag--strip'><code class='flag'>--strip (always|never|sometimes)</code></h4> +<p> + This option determines whether Bazel will strip debugging information from + all binaries and shared libraries, by invoking the linker with the <code>-Wl,--strip-debug</code> option. + <code class='flag'>--strip=always</code> means always strip debugging information. + <code class='flag'>--strip=never</code> means never strip debugging information. + The default value of <code class='flag'>--strip=sometimes</code> means strip iff the <code class='flag'>--compilation_mode</code> + is <code>fastbuild</code>. +</p> +<pre> + % bazel build --strip=always //foo:bar +</pre> +<p> + will compile the target while stripping debugging information from all generated + binaries. +</p> +<p> + Note that if you want debugging information, it's not enough to disable stripping; you also need to make + sure that the debugging information was generated by the compiler, which you can do by using either + <code>-c dbg</code> or <code class='flag'>--copt -g</code>. +</p> +<p> + Note also that Bazel's <code class='flag'>--strip</code> option corresponds with ld's <code>--strip-debug</code> option: + it only strips debugging information. If for some reason you want to strip <em>all</em> symbols, + not just <em>debug</em> symbols, you would need to use ld's <code>--strip-all</code> option, + which you can do by passing <code class='flag'>--linkopt=-Wl,--strip-all</code> to Bazel. +</p> + +<h4 id='flag--stripopt'><code class='flag'>--stripopt <var>strip-option</var></code></h4> +<p> + An additional option to pass to the <code>strip</code> command when generating + a <a href="be/c-cpp.html#cc_binary_implicit_outputs"><code>*.stripped</code> + binary</a>. The default is <code>-S -p</code>. This option can be used + multiple times. +</p> +<p> + Note that <code class='flag'>--stripopt</code> does not apply to the stripping of the main + binary with <code><a href='#flag--strip'>--strip</a>=(always|sometimes)</code>. +</p> + +<h4 id='flag--fdo_instrument'><code class='flag'>--fdo_instrument <var>profile-output-dir</var></code></h4> +<p> + The <code class='flag'>--fdo_instrument</code> option enables the generation of + FDO (feedback directed optimization) profile output when the + built C/C++ binary is executed. For GCC, the argument provided is used as a + directory prefix for a per-object file directory tree of .gcda files + containing profile information for each .o file. +</p> +<p> + Once the profile data tree has been generated, the profile tree + should be zipped up, and provided to the + <code class='flag'>--fdo_optimize=<var>profile-zip</var></code> + Bazel option to enable the FDO optimized compilation. + +</p> +<p> + For the LLVM compiler the argument is also the directory under which the raw LLVM profile + data file(s) is dumped, e.g. + <code class='flag'>--fdo_instrument=<var>/path/to/rawprof/dir/</var></code>. +</p> +<p> + The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>--fdo_optimize</code> + cannot be used at the same time. +</p> + +<h4 id='flag--fdo_optimize'><code class='flag'>--fdo_optimize <var>profile-zip</var></code></h4> +<p> + The <code class='flag'>--fdo_optimize</code> option enables the use of the + per-object file profile information to perform FDO (feedback + directed optimization) optimizations when compiling. For GCC, the argument + provided is the zip file containing the previously-generated file tree + of .gcda files containing profile information for each .o file. +</p> +<p> + Alternatively, the argument provided can point to an auto profile + identified by the extension .afdo. + +</p> +<p> + Note that this option also accepts labels that resolve to source files. You + may need to add an <code>exports_files</code> directive to the corresponding package to + make the file visible to Bazel. +</p> +<p> + For the LLVM compiler the argument provided should point to the indexed LLVM + profile output file prepared by the llvm-profdata tool, and should have a .profdata + extension. +</p> +<p> + The options <code class='flag'>--fdo_instrument</code> and <code class='flag'> + --fdo_optimize</code> cannot be used at the same time. +</p> + +<h4 id='flag--lipo'><code class='flag'>--lipo (off|binary)</code></h4> +<p> + The <code class='flag'>--lipo=binary</code> option enables + + LIPO + (Lightweight Inter-Procedural Optimization). LIPO is an extended C/C++ optimization technique + that optimizes code across different object files. It involves compiling each C/C++ source + file differently for every binary. This is in contrast to normal compilation where compilation + outputs are reused. This means that LIPO is more expensive than normal compilation. +</p> +<p> + This option only has an effect when FDO is also enabled (see the + <a href="#flag--fdo_instrument">--fdo_instrument</a> and + <a href="#flag--fdo_optimize">--fdo_options</a>). + Currently LIPO is only supported when building a single <code>cc_binary</code> rule. +</p> +<p>Setting <code>--lipo=binary</code> implicitly sets + <code><a href="#flag--dynamic_mode">--dynamic_mode</a>=off</code>. +</p> + +<h4 id='flag--lipo_context'><code class='flag'>--lipo_context + <var>context-binary</var></code></h4> +<p> + Specifies the label of a <code>cc_binary</code> rule that was used to generate + the profile information for LIPO that was given to + the <a href='#flag--fdo_optimize'><code class='flag'>--fdo_optimize</code></a> option. +</p> +<p> + Specifying the context is mandatory when <code>--lipo=binary</code> is set. + Using this option implicitly also sets + <code><a href="#flag--linkopt">--linkopt</a>=-Wl,--warn-unresolved-symbols</code>. +</p> + +<h4 id='flag--output_symbol_counts'><code class='flag'>--[no]output_symbol_counts</code></h4> +<p> + If enabled, each gold-invoked link of a C++ executable binary will output + a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold + option). For each linker input, the file logs the number of symbols that were + defined and the number of symbols that were used in the binary. + This information can be used to track unnecessary link dependencies. + The symbol counts file is written to the binary's output path with the name + <code>[targetname].sc</code>. +</p> +<p> + This option is disabled by default. +</p> + +<h4 id='flag--jvmopt'><code class='flag'>--jvmopt <var>jvm-option</var></code></h4> +<p> + This option allows option arguments to be passed to the Java VM. It can be used + with one big argument, or multiple times with individual arguments. For example: +</p> +<pre> + % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all +</pre> +<p> + will use the server VM for launching all Java binaries and set the + startup heap size for the VM to 256 MB. +</p> + +<h4 id='flag--javacopt'><code class='flag'>--javacopt <var>javac-option</var></code></h4> +<p> + This option allows option arguments to be passed to javac. It can be used + with one big argument, or multiple times with individual arguments. For example: +</p> +<pre> + % bazel build --javacopt="-g:source,lines" //myprojects:prog +</pre> +<p> + will rebuild a java_binary with the javac default debug info + (instead of the bazel default). +</p> +<p> + The option is passed to javac after the Bazel built-in default options for + javac and before the per-rule options. The last specification of + any option to javac wins. The default options for javac are: +</p> + +<pre> + -source 8 -target 8 -encoding UTF-8 +</pre> +<p> + Note that changing <code class='flag'>--javacopt</code> settings will force a recompilation + of all affected classes. Also note that javacopts parameters listed in + specific java_library or java_binary build rules will be placed on the javac + command line <em>after</em> these options. +</p> + +<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps + (default|strict|off|warn|error)</code></h4> +<p> + This option controls whether javac checks for missing direct dependencies. + Java targets must explicitly declare all directly used targets as + dependencies. This flag instructs javac to determine the jars actually used + for type checking each java file, and warn/error if they are not the output + of a direct dependency of the current target. +</p> + +<ul> + <li> <code>off</code> means checking is disabled. + </li> + <li> <code>warn</code> means javac will generate standard java warnings of + type <code>[strict]</code> for each missing direct dependency. + </li> + <li> <code>default</code>, <code>strict</code> and <code>error</code> all + mean javac will generate errors instead of warnings, causing the current + target to fail to build if any missing direct dependencies are found. + This is also the default behavior when the flag is unspecified. + </li> +</ul> + +<h3 id='semantics-options'>Semantics options</h3> +<p> + These options affect the build commands and/or the output file contents. +</p> + +<h4 id='flag--compilation_mode'><code class='flag'>--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4> +<p> + This option takes an argument of <code>fastbuild</code>, <code>dbg</code> + or <code>opt</code>, and affects various C/C++ code-generation + options, such as the level of optimization and the completeness of + debug tables. Bazel uses a different output directory for each + different compilation mode, so you can switch between modes without + needing to do a full rebuild <i>every</i> time. +</p> +<ul> + <li> <code>fastbuild</code> means build as fast as possible: + generate minimal debugging information (<code>-gmlt + -Wl,-S</code>), and don't optimize. This is the + default. Note: <code>-DNDEBUG</code> will <b>not</b> be set. + </li> + <li> <code>dbg</code> means build with debugging enabled (<code>-g</code>), + so that you can use gdb (or another debugger). + </li> + <li> <code>opt</code> means build with optimization enabled and + with <code>assert()</code> calls disabled (<code>-O2 -DNDEBUG</code>). + Debugging information will not be generated in <code>opt</code> mode + unless you also pass <code class='flag'>--copt -g</code>. + </li> +</ul> + +<h4 id='flag--cpu'><code class='flag'>--cpu <var>cpu</var></code></h4> +<p> +This option specifies the target CPU architecture to be used for +the compilation of binaries during the build. +</p> +<p> + +</p> + +<p> + Note that a particular combination of crosstool version, compiler version, + libc version, and target CPU is allowed only if it has been specified + in the currently used CROSSTOOL file. +</p> + +<h4 id='flag--host_cpu'><code class='flag'>--host_cpu <var>cpu</var></code></h4> +<p> + This option specifies the name of the CPU architecture that should be + used to build host tools. +</p> + +<h4 id='flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu <var>cpu[,cpu]*</var></code></h4> +<p> + The CPUs to build C/C++ libraries for in the transitive <code>deps</code> of + <code>android_binary</code> + + rules. Other C/C++ rules are not affected. For example, if a <code>cc_library</code> + appears in the transitive <code>deps</code> of an <code>android_binary</code> rule and a + <code>cc_binary</code> rule, the <code>cc_library</code> will be built at least twice: + once for each CPU specified with <code class='flag'>--fat_apk_cpu</code> for the + <code>android_binary</code> rule, and once for the CPU specified with + <code class='flag'>--cpu</code> for the <code>cc_binary</code> rule. + +<p> +The default is <code>armeabi-v7a</code>. +</p> + <p> + One <code>.so</code> file will be created and packaged in the APK for + each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The name of the <code>.so</code> + file will be the name of the <code>android_binary</code> rule prefixed with "lib", e.g., if the name + of the <code>android_binary</code> is "foo", then the file will be <code>libfoo.so</code>. + </p> + + <p> + Note that an Android-compatible crosstool must be selected. + If an <code>android_ndk_repository</code> rule is defined in the + WORKSPACE file, an Android-compatible crosstool is automatically selected. + Otherwise, the crostool can be selected using the + <a href='#flag--android_crosstool_top'><code class='flag'>--android_crosstool_top</code></a> + or <a href='#flag--crosstool_top'><code class='flag'>--crosstool_top</code></a> flags. + </p> +</p> + +<h4 id='flag--experimental_skip_static_outputs'><code class='flag'>--experimental_skip_static_outputs</code></h4> +<p> + The <code class='flag'>--experimental_skip_static_outputs</code> option causes all + statically-linked C++ binaries to <b>not</b> be output in any meaningful + way. + +</p> +<p> + If you set this flag, you must also + set <a href="#flag--distinct_host_configuration"><code class='flag'>--distinct_host_configuration</code></a>. + It is also inherently incompatible with running tests — don't use it for + that. This option is experimental and may go away at any time. +</p> + +<h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt + <var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4> +<p> + When present, any C++ file with a label or an execution path matching one of the inclusion regex + expressions and not matching any of the exclusion expressions will be built + with the given options. The label matching uses the canonical form of the label + (i.e //<code>package</code>:<code>label_name</code>). + + The execution path is the relative path to your workspace directory including the base name + (including extension) of the C++ file. It also includes any platform dependent prefixes. + Note, that if only one of the label or the execution path matches the options will be used. +</p> +<p> + <b>Notes</b>: + To match the generated files (e.g. genrule outputs) + Bazel can only use the execution path. In this case the regexp shouldn't start with '//' + since that doesn't match any execution paths. Package names can be used like this: + <code class='flag'>--per_file_copt=base/.*\.pb\.cc@-g0</code>. This will match every + <code>.pb.cc</code> file under a directory called <code>base</code>. +</p> +<p> + This option can be used multiple times. +</p> +<p> + The option is applied regardless of the compilation mode used. I.e. it is possible + to compile with <code class='flag'>--compilation_mode=opt</code> and selectively compile some + files with stronger optimization turned on, or with optimization disabled. +</p> +<p> + <b>Caveat</b>: If some files are selectively compiled with debug symbols the symbols + might be stripped during linking. This can be prevented by setting + <code class='flag'>--strip=never</code>. +</p> +<p> + <b>Syntax</b>: <code>[+-]regex[,[+-]regex]...@option[,option]...</code> Where + <code>regex</code> stands for a regular expression that can be prefixed with + a <code>+</code> to identify include patterns and with <code>-</code> to identify + exclude patterns. <code>option</code> stands for an arbitrary option that is passed + to the C++ compiler. If an option contains a <code>,</code> it has to be quoted like so + <code>\,</code>. Options can also contain <code>@</code>, since only the first + <code>@</code> is used to separate regular expressions from options. +</p> +<p> + <b>Example</b>: + <code class='flag'>--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs</code> + adds the <code>-O0</code> and the <code>-fprofile-arcs</code> options to the command + line of the C++ compiler for all <code>.cc</code> files in <code>//foo/</code> except + <code>file.cc</code>. +</p> +<h4 id='flag--dynamic_mode'><code class='flag'>--dynamic_mode <var>mode</var></code></h4> +<p> + Determines whether C++ binaries will be linked dynamically, interacting with + the <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic + attribute</a> on build rules. +</p> + +<p> + Modes: +</p> +<ul> + <li><code>auto</code>: Translates to a platform-dependent mode; + <code>default</code> for linux and <code>off</code> for cygwin.</li> + <li><code>default</code>: Allows bazel to choose whether to link dynamically. + See <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic</a> for more + information.</li> + <li><code>fully</code>: Links all targets dynamically. This will speed up + linking time, and reduce the size of the resulting binaries. + + </li> + <li><code>off</code>: Links all targets in + <a href='be/c-cpp.html#cc_binary.linkstatic'>mostly static</a> mode. + If <code>-static</code> is set in linkopts, targets will change to fully + static.</li> +</ul> + +<h4 id='flag--fission'><code class='flag'>--fission (yes|no|[dbg][,opt][,fastbuild])</code></h4> +<p> + Enables + + <a href='https://gcc.gnu.org/wiki/DebugFission'>Fission</a>, + which writes C++ debug information to dedicated .dwo files instead of .o files, where it would + otherwise go. This substantially reduces the input size to links and can reduce link times. + +</p> +<p> + When set to <code class='flag'>[dbg][,opt][,fastbuild]</code> (example: + <code class='flag'>--fission=dbg,fastbuild</code>), Fission is enabled + only for the specified set of compilation modes. This is useful for bazelrc + settings. When set to <code class='flag'>yes</code>, Fission is enabled + universally. When set to <code class='flag'>no</code>, Fission is disabled + universally. Default is <code class='flag'>dbg</code>. +</p> + +<h4 id='flag--force_ignore_dash_static'><code class='flag'>--force_ignore_dash_static</code></h4> +<p> + If this flag is set, any <code>-static</code> options in linkopts of + <code>cc_*</code> rules BUILD files are ignored. This is only intended as a + workaround for C++ hardening builds. +</p> + +<h4 id='flag--force_pic'><code class='flag'>--[no]force_pic</code></h4> +<p> + If enabled, all C++ compilations produce position-independent code ("-fPIC"), + links prefer PIC pre-built libraries over non-PIC libraries, and links produce + position-independent executables ("-pie"). Default is disabled. +</p> +<p> + Note that dynamically linked binaries (i.e. <code>--dynamic_mode fully</code>) + generate PIC code regardless of this flag's setting. So this flag is for cases + where users want PIC code explicitly generated for static links. +</p> + +<h4 id='flag--android_resource_shrinking'><code class='flag'>--android_resource_shrinking</code></h4> +<p> + Selects whether to perform resource shrinking for android_binary rules. Sets the default for the + <a href='be/android.html#android_binary.shrink_resources'>shrink_resources attribute</a> on + android_binary rules; see the documentation for that rule for further details. Defaults to off. +</p> + +<h4 id='flag--custom_malloc'><code class='flag'>--custom_malloc <var>malloc-library-target</var></code></h4> +<p> + When specified, always use the given malloc implementation, overriding all + <code>malloc="target"</code> attributes, including in those targets that use the + default (by not specifying any <code>malloc</code>). +</p> + +<h4 id='flag--crosstool_top'><code class='flag'>--crosstool_top <var>label</var></code></h4> +<p> + This option specifies the location of the crosstool compiler suite + to be used for all C++ compilation during a build. Bazel will look in that + location for a CROSSTOOL file and uses that to automatically determine + settings for + + <code class='flag'>--compiler</code>. +</p> + +<h4 id='flag--host_crosstool_top'><code class='flag'>--host_crosstool_top <var>label</var></code></h4> +<p> + If not specified, bazel uses the value of <code class='flag'>--crosstool_top</code> to compile + code in the host configuration, i.e., tools run during the build. The main purpose of this flag + is to enable cross-compilation. +</p> + +<h4 id='flag--apple_crosstool_top'><code class='flag'>--apple_crosstool_top <var>label</var></code></h4> +<p> + The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of + objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites + <code class='flag'>--crosstool_top</code>. +</p> + +<h4 id='flag--android_crosstool_top'><code class='flag'>--android_crosstool_top <var>label</var></code></h4> +<p> + The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of + <code>android_binary</code> rules. This is useful if other targets in the + build require a different crosstool. The default is to use the crosstool + generated by the <code>android_ndk_repository</code> rule in the WORKSPACE file. + See also <a href='#flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu</code></a>. +</p> +<h4 id='flag--compiler'><code class='flag'>--compiler <var>version</var></code></h4> +<p> + This option specifies the C/C++ compiler version (e.g. <code>gcc-4.1.0</code>) + to be used for the compilation of binaries during the build. If you want to + build with a custom crosstool, you should use a CROSSTOOL file instead of + specifying this flag. +</p> +<p> + Note that only certain combinations of crosstool version, compiler version, + libc version, and target CPU are allowed. +</p> + +<h4 id='flag--glibc'><code class='flag'>--glibc <var>version</var></code></h4> +<p> + This option specifies the version of glibc that the target should be linked + against. If you want to build with a custom crosstool, you should use a + CROSSTOOL file instead of specifying this flag. In that case, Bazel will use + the CROSSTOOL file and the following options where appropriate: + <ul> + <li><a href="#flag--cpu"><code class='flag'>--cpu</code></a></li> + + </ul> +</p> +<p> + Note that only certain combinations of crosstool version, compiler version, + glibc version, and target CPU are allowed. +</p> + +<h4 id='flag--android_sdk'><code class='flag'>--android_sdk <var>label</var></code></h4> +<p> + This option specifies the Android SDK/platform toolchain + and Android runtime library that will be used to build any Android-related + rule. + + The Android SDK will be automatically selected if an <code>android_sdk_repository</code> + rule is defined in the WORKSPACE file. +</p> + +<h4 id='flag--java_toolchain'><code class='flag'>--java_toolchain <var>label</var></code></h4> +<p> + This option specifies the label of the java_toolchain used to compile Java + source files. +</p> + +<h4 id='flag--javabase'><code class='flag'>--javabase (<var>path</var>|<var>label</var>)</code></h4> +<p> + This option sets the <i>label</i> or the <i>path</i> of the base Java installation to + use for running JavaBuilder, SingleJar, for <i>bazel run</i> and <i>bazel + test</i>, and for Java binaries built by <code>java_binary</code> and <code>java_test</code> + rules. A path must be to a JDK or JRE directory that contains <code>bin/java</code>. + The various <a href='be/make-variables.html'>"Make" variables</a> for + Java (<code>JAVABASE</code>, <code>JAVA</code>, <code>JAVAC</code> and + <code>JAR</code>) are derived from this option. +</p> + +<p> + This does not select the Java compiler that is used to compile Java + source files. The compiler can be selected by settings the + <a href="#flag--java_toolchain"><code class='flag'>--java_toolchain</code></a> + option. +</p> + +<h3 id='strategy-options'>Build strategy options</h3> +<p> + These options affect how Bazel will execute the build. + They should not have any significant effect on the output files + generated by the build. Typically their main effect is on the + speed on the build. +</p> + +<h4 id='flag--spawn_strategy'><code class='flag'>--spawn_strategy <var>strategy</var></code></h4> +<p> + This option controls where and how commands are executed. +</p> +<ul> + + <li> + <code>standalone</code> causes commands to be executed as local subprocesses. + </li> + <li> + <code>sandboxed</code> causes commands to be executed inside a sandbox on the local machine. + This requires that all input files, data dependencies and tools are listed as direct + dependencies in the <code>srcs</code>, <code>data</code> and <code>tools</code> attributes. + This is the default on systems that support sandboxed execution. + </li> + +</ul> + +<h4 id='flag--genrule_strategy'><code class='flag'>--genrule_strategy <var>strategy</var></code></h4> +<p> + This option controls where and how genrules are executed. +</p> +<ul> + + <li> + <code>standalone</code> causes genrules to run as local subprocesses. + </li> + <li> + <code>sandboxed</code> causes genrules to run inside a sandbox on the local machine. + This requires that all input files are listed as direct dependencies in + the <code>srcs</code> attribute, and the program(s) executed are listed + in the <code>tools</code> attribute. + This is the default for Bazel on systems that support sandboxed execution. + </li> + +</ul> + +<h4 id='flag--local_genrule_timeout_seconds'><code class='flag'>--local_genrule_timeout_seconds <var>seconds</var></code></h4> +<p>Sets a timeout value for local genrules with the given number of seconds.</p> + +<h4 id='flag--jobs'><code class='flag'>--jobs <var>n</var></code> (-j)</h4> +<p> + This option, which takes an integer argument, specifies a limit on + the number of jobs that should be executed concurrently during the + execution phase of the build. The default is 200. +</p> +<p> + Note that the number of concurrent jobs that Bazel will run + is determined not only by the <code class='flag'>--jobs</code> setting, but also + by Bazel's scheduler, which tries to avoid running concurrent jobs + that will use up more resources (RAM or CPU) than are available, + based on some (very crude) estimates of the resource consumption + of each job. The behavior of the scheduler can be controlled by + the <code class='flag'>--ram_utilization_factor</code> option. +</p> + +<h4 id='flag--progress_report_interval'><code class='flag'>--progress_report_interval <var>n</var></code></h4> +<p> + + Bazel periodically prints a progress report on jobs that are not + finished yet (e.g. long running tests). This option sets the + reporting frequency, progress will be printed every <code>n</code> + seconds. +</p> +<p> + The default is 0, that means an incremental algorithm: the first + report will be printed after 10 seconds, then 30 seconds and after + that progress is reported once every minute. +</p> + +<h4 id='flag--ram_utilization_factor'><code class='flag'>--ram_utilization_factor</code> <var>percentage</var></h4> +<p> + This option, which takes an integer argument, specifies what percentage + of the system's RAM Bazel should try to use for its subprocesses. + This option affects how many processes Bazel will try to run + in parallel. The default value is 67. + If you run several Bazel builds in parallel, using a lower + value for this option may avoid thrashing and thus improve overall + throughput. Using a value higher than the default is NOT recommended. Note + that Bazel's estimates are very coarse, so the actual RAM usage may be much + higher or much lower than specified. Note also that this option does not + affect the amount of memory that the Bazel server itself will use. +</p> + +<h4 id='flag--local_resources'><code class='flag'>--local_resources</code> <var>availableRAM,availableCPU,availableIO</var></h4> +<p> + This option, which takes three comma-separated floating point arguments, +specifies the amount of local resources that Bazel can take into +consideration when scheduling build and test activities. Option expects amount of +available RAM (in MB), number of CPU cores (with 1.0 representing single full +core) and workstation I/O capability (with 1.0 representing average +workstation). By default Bazel will estimate amount of RAM and number of CPU +cores directly from system configuration and will assume 1.0 I/O resource. +</p> +<p> + If this option is used, Bazel will ignore --ram_utilization_factor. +</p> + +<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4> +<p> + This option, which is currently enabled by default, specifies + whether the runfiles symlinks for tests and + <code>cc_binary</code> targets should be built in the output directory. + Using <code class='flag'>--nobuild_runfile_links</code> can be useful + to validate if all targets compile without incurring the overhead + for building the runfiles trees. + + Within Bazel's output tree, the + runfiles symlink tree is typically rooted as a sibling of the corresponding + binary or test. +</p> + +<p> + When tests (or applications) are executed, their + run-time data dependencies are gathered together in one place, and + may be accessed by the test using paths of the form + <code>$TEST_SRCDIR/workspace/<var>packagename</var>/<var>filename</var></code>. + The "runfiles" tree ensures that tests have access to all the files + upon which they have a declared dependence, and nothing more. By + default, the runfiles tree is implemented by constructing a set of + symbolic links to the required files. As the set of links grows, so + does the cost of this operation, and for some large builds it can + contribute significantly to overall build time, particularly because + each individual test (or application) requires its own runfiles tree. +</p> +<p> + The <code class='flag'>--build_runfile_links</code> flag controls the + construction of the tree of symbolic links (for C++ applications and + tests only). The reasons only C++ non-test rules are affected are numerous + and subtle: C++ builds are more likely to be slower due to runfiles; + no C++ host tools (tools that run during the build) need their runfiles, + so this option can be used by the host configuration; and other rules + (notably Python) need their runfiles for other purposes besides test + execution. +</p> + +<h4 id='flag--discard_analysis_cache'> + <code class='flag'>--[no]discard_analysis_cache</code></h4> +<p> + When this option is enabled, Bazel will discard the analysis cache + right before execution starts, thus freeing up additional memory + (around 10%) for the <a href="#execution-phase">execution phase</a>. + The drawback is that further incremental builds will be slower. +</p> + +<h4 id='flag--keep_going'><code class='flag'>--[no]keep_going</code> (-k)</h4> +<p> + As in GNU Make, the execution phase of a build stops when the first + error is encountered. Sometimes it is useful to try to build as + much as possible even in the face of errors. This option enables + that behavior, and when it is specified, the build will attempt to + build every target whose prerequisites were successfully built, but + will ignore errors. +</p> +<p> + While this option is usually associated with the execution phase of + a build, it also effects the analysis phase: if several targets are + specified in a build command, but only some of them can be + successfully analyzed, the build will stop with an error + unless <code class='flag'>--keep_going</code> is specified, in which case the + build will proceed to the execution phase, but only for the targets + that were successfully analyzed. +</p> + +<h4 id='flag--use_ijars'><code class='flag'>--[no]use_ijars</code></h4> +<p> + This option changes the way <code>java_library</code> targets are + compiled by Bazel. Instead of using the output of a + <code>java_library</code> for compiling dependent + <code>java_library</code> targets, Bazel will create interface jars + that contain only the signatures of non-private members (public, + protected, and default (package) access methods and fields) and use + the interface jars to compile the dependent targets. This makes it + possible to avoid recompilation when changes are only made to + method bodies or private members of a class. +</p> +<p> + Note that using <code class='flag'>--use_ijars</code> might give you a different + error message when you are accidentally referring to a non visible + member of another class: Instead of getting an error that the member + is not visible you will get an error that the member does not exist. +</p> +<p> + Note that changing the <code class='flag'>--use_ijars</code> setting will force + a recompilation of all affected classes. +</p> + +<h4 id='flag--interface_shared_objects'> + <code class='flag'>--[no]interface_shared_objects</code> +</h4> +<p> + This option enables <i>interface shared objects</i>, which makes binaries and + other shared libraries depend on the <i>interface</i> of a shared object, + rather than its implementation. When only the implementation changes, Bazel + can avoid rebuilding targets that depend on the changed shared library + unnecessarily. +</p> + +<h3 id='output-selection-options'>Output selection options</h3> +<p> + These options determine what to build or test. +</p> + +<h4 id="nobuild"><code class='flag'>--[no]build</code></h4> +<p> + This option causes the execution phase of the build to occur; it is + on by default. When it is switched off, the execution phase is + skipped, and only the first two phases, loading and analysis, occur. +</p> +<p> + This option can be useful for validating BUILD files and detecting + errors in the inputs, without actually building anything. +</p> + +<h4 id='flag--build_tests_only'><code class='flag'>--[no]build_tests_only</code></h4> +<p> + If specified, Bazel will build only what is necessary to run the *_test + and test_suite rules that were not filtered due to their + <a href='#flag--test_size_filters'>size</a>, + <a href='#flag--test_timeout_filters'>timeout</a>, + <a href='#flag--test_tag_filters'>tag</a>, or + <a href='#flag--test_lang_filters'>language</a>. + If specified, Bazel will ignore other targets specified on the command line. + By default, this option is disabled and Bazel will build everything + requested, including *_test and test_suite rules that are filtered out from + testing. This is useful because running + <code>bazel test --build_tests_only foo/...</code> may not detect all build + breakages in the <code>foo</code> tree. +</p> + +<h4 id='flag--check_up_to_date'><code class='flag'>--[no]check_up_to_date</code></h4> +<p> + This option causes Bazel not to perform a build, but merely check + whether all specified targets are up-to-date. If so, the build + completes successfully, as usual. However, if any files are out of + date, instead of being built, an error is reported and the build + fails. This option may be useful to determine whether a build has + been performed more recently than a source edit (e.g. for pre-submit + checks) without incurring the cost of a build. +</p> +<p> + See also <a href="#flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></a>. +</p> + +<h4 id='flag--compile_one_dependency'><code class='flag'>--[no]compile_one_dependency</code></h4> +<p> + Compile a single dependency of the argument files. This is useful for + syntax checking source files in IDEs, for example, by rebuilding a single + target that depends on the source file to detect errors as early as + possible in the edit/build/test cycle. This argument affects the way all + non-flag arguments are interpreted: for each source filename, one + rule that depends on it will be built. For + + C++ and Java + sources, rules in the same language space are preferentially chosen. For + multiple rules with the same preference, the one that appears first in the + BUILD file is chosen. An explicitly named target pattern which does not + reference a source file results in an error. +</p> + +<h4 id='flag--save_temps'><code class='flag'>--save_temps</code></h4> +<p> + The <code class='flag'>--save_temps</code> option causes temporary outputs from gcc to be saved. + These include .s files (assembler code), .i (preprocessed C) and .ii + (preprocessed C++) files. These outputs are often useful for debugging. Temps will only be + generated for the set of targets specified on the command line. +</p> +<p> + Note that our implementation of <code class='flag'>--save_temps</code> does not use gcc's + <code>-save-temps</code> flag. Instead, we do two passes, one with <code>-S</code> + and one with <code>-E</code>. A consequence of this is that if your build fails, + Bazel may not yet have produced the ".i" or ".ii" and ".s" files. + If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation, + you may need to also use <code class='flag'>--keep_going</code> so that Bazel will still try to + produce the preprocessed files after the compilation fails. +</p> +<p> + The <code class='flag'>--save_temps</code> flag currently works only for cc_* rules. +</p> +<p> + To ensure that Bazel prints the location of the additional output files, check that + your <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a> + setting is high enough. +</p> + +<h4 id='flag--build_tag_filters'><code class='flag'>--build_tag_filters <var>tag[,tag]*</var></code></h4> +<p> + If specified, Bazel will build only targets that have at least one required tag + (if any of them are specified) and does not have any excluded tags. Build tag + filter is specified as comma delimited list of tag keywords, optionally + preceded with '-' sign used to denote excluded tags. Required tags may also + have a preceding '+' sign. +</p> + +<h4 id='flag--test_size_filters'><code class='flag'>--test_size_filters <var>size[,size]*</var></code></h4> +<p> + If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> + is also specified) only test targets with the given size. Test size filter + is specified as comma delimited list of allowed test size values (small, + medium, large or enormous), optionally preceded with '-' sign used to denote + excluded test sizes. For example, +</p> +<pre> + % bazel test --test_size_filters=small,medium //foo:all +</pre> + and +<pre> + % bazel test --test_size_filters=-large,-enormous //foo:all +</pre> +<p> + will test only small and medium tests inside //foo. +</p> +<p> + By default, test size filtering is not applied. +</p> + +<h4 id='flag--test_timeout_filters'><code class='flag'>--test_timeout_filters <var>timeout[,timeout]*</var></code></h4> +<p> + If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> + is also specified) only test targets with the given timeout. Test timeout filter + is specified as comma delimited list of allowed test timeout values (short, + moderate, long or eternal), optionally preceded with '-' sign used to denote + excluded test timeouts. See <a href='#flag--test_size_filters'>--test_size_filters</a> + for example syntax. +</p> +<p> + By default, test timeout filtering is not applied. +</p> + + +<h4 id='flag--test_tag_filters'><code class='flag'>--test_tag_filters <var>tag[,tag]*</var></code></h4> +<p> + If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> + is also specified) only test targets that have at least one required tag + (if any of them are specified) and does not have any excluded tags. Test tag + filter is specified as comma delimited list of tag keywords, optionally + preceded with '-' sign used to denote excluded tags. Required tags may also + have a preceding '+' sign. +</p> +<p> + For example, +<pre> + % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all +</pre> +<p> + will test targets that are tagged with either <code>performance</code> or + <code>stress</code> tag but are <b>not</b> tagged with the <code>flaky</code> + tag. +</p> +<p> + By default, test tag filtering is not applied. Note that you can also filter + on test's <code>size</code> and <code>local</code> tags in + this manner. +</p> + +<h4 id='flag--test_lang_filters'><code class='flag'>--test_lang_filters <var>lang[,lang]*</var></code></h4> +<p> + Specifies a comma-separated list of test languages for languages with an official <code>*_test</code> rule the + (see <a href="be/overview.html">build encyclopedia</a> for a full list of these). Each + language can be optionally preceded with '-' to specify excluded + languages. The name used for each language should be the same as + the language prefix in the <code>*_test</code> rule, for example, + <code>cc</code>, <code>java</code> or <code>sh</code>. +</p> +<p> + If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> + is also specified) only test targets of the specified language(s). +</p> +<p> + For example, +</p> +<pre> + % bazel test --test_lang_filters=cc,java foo/... +</pre> +<p> + will test only the C/C++ and Java tests (defined using + <code>cc_test</code> and <code>java_test</code> rules, respectively) + in <code>foo/...</code>, while +</p> +<pre> + % bazel test --test_lang_filters=-sh,-java foo/... +</pre> +<p> + will run all of the tests in <code>foo/...</code> except for the + <code>sh_test</code> and <code>java_test</code> tests. +</p> +<p> + By default, test language filtering is not applied. +</p> + +<h4 id="flag--test_filter"><code class='flag'>--test_filter=<var>filter-expression</var></code></h4> +<p> + Specifies a filter that the test runner may use to pick a subset of tests for + running. All targets specified in the invocation are built, but depending on + the expression only some of them may be executed; in some cases, only certain + test methods are run. +</p> +<p> + The particular interpretation of <var>filter-expression</var> is up to + the test framework responsible for running the test. It may be a glob, + substring, or regexp. <code class='flag'>--test_filter</code> is a convenience + over passing different <code class='flag'>--test_arg</code> filter arguments, + but not all frameworks support it. +</p> + +<h3>Verbosity options: options that control what Bazel prints</h3> + +These options control the verbosity of Bazel's output, +either to the terminal, or to additional log files. + +<h4 id='flag--explain'><code class='flag'>--explain <var>logfile</var></code></h4> +<p> + This option, which requires a filename argument, causes the + dependency checker in <code>bazel build</code>'s execution phase to + explain, for each build step, either why it is being executed, or + that it is up-to-date. The explanation is written + to <i>logfile</i>. +</p> +<p> + If you are encountering unexpected rebuilds, this option can help to + understand the reason. Add it to your <code>.bazelrc</code> so that + logging occurs for all subsequent builds, and then inspect the log + when you see an execution step executed unexpectedly. This option + may carry a small performance penalty, so you might want to remove + it when it is no longer needed. +</p> + +<h4 id='flag--verbose_explanations'><code class='flag'>--verbose_explanations</code></h4> +<p> + This option increases the verbosity of the explanations generated + when the <a href='#flag--explain'>--explain</a> option is enabled. +</p> +<p> + In particular, if verbose explanations are enabled, + and an output file is rebuilt because the command used to + build it has changed, then the output in the explanation file will + include the full details of the new command (at least for most + commands). +</p> +<p> + Using this option may significantly increase the length of the + generated explanation file and the performance penalty of using + <code class='flag'>--explain</code>. +</p> +<p> + If <code class='flag'>--explain</code> is not enabled, then + <code class='flag'>--verbose_explanations</code> has no effect. +</p> + +<h4 id='flag--profile'><code class='flag'>--profile <var>file</var></code></h4> +<p> + This option, which takes a filename argument, causes Bazel to write + profiling data into a file. The data then can be analyzed or parsed using the + <code>bazel analyze-profile</code> command. The Build profile can be useful in + understanding where Bazel's <code>build</code> command is spending its time. +</p> + +<h4 id='flag--show_loading_progress'><code class='flag'>--[no]show_loading_progress</code></h4> +<p> + This option causes Bazel to output package-loading progress + messages. If it is disabled, the messages won't be shown. +</p> + +<h4 id='flag--show_progress'><code class='flag'>--[no]show_progress</code></h4> +<p> + This option causes progress messages to be displayed; it is on by + default. When disabled, progress messages are suppressed. +</p> + +<h4 id='flag--show_progress_rate_limit'><code class='flag'>--show_progress_rate_limit + <var>n</var></code></h4> +<p> + This option causes bazel to display only + one progress message per <code>n</code> seconds, where <var>n</var> is a real number. + If <code>n</code> is -1, all progress messages will be displayed. The default value for + this option is 0.03, meaning bazel will limit the progress messages to one per every + 0.03 seconds. +</p> + +<h4 id='flag--show_result'><code class='flag'>--show_result <var>n</var></code></h4> +<p> + This option controls the printing of result information at the end + of a <code>bazel build</code> command. By default, if a single + build target was specified, Bazel prints a message stating whether + or not the target was successfully brought up-to-date, and if so, + the list of output files that the target created. If multiple + targets were specified, result information is not displayed. +</p> +<p> + While the result information may be useful for builds of a single + target or a few targets, for large builds (e.g. an entire top-level + project tree), this information can be overwhelming and distracting; + this option allows it to be controlled. <code class='flag'>--show_result</code> + takes an integer argument, which is the maximum number of targets + for which full result information should be printed. By default, + the value is 1. Above this threshold, no result information is + shown for individual targets. Thus zero causes the result + information to be suppressed always, and a very large value causes + the result to be printed always. +</p> +<p> + Users may wish to choose a value in-between if they regularly + alternate between building a small group of targets (for example, + during the compile-edit-test cycle) and a large group of targets + (for example, when establishing a new workspace or running + regression tests). In the former case, the result information is + very useful whereas in the latter case it is less so. As with all + options, this can be specified implicitly via + the <a href='#bazelrc'><code>.bazelrc</code></a> file. +</p> +<p> + The files are printed so as to make it easy to copy and paste the + filename to the shell, to run built executables. The "up-to-date" + or "failed" messages for each target can be easily parsed by scripts + which drive a build. +</p> + +<h4 id='flag--subcommands'><code class='flag'>--subcommands</code> (<code>-s</code>)</h4> +<p> + This option causes Bazel's execution phase to print the full command line + for each command prior to executing it. +</p> + +<pre> + >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world'] + (cd /home/jrluser/.cache/bazel/_bazel_jrluser/4c084335afceb392cfbe7c31afee3a9f/bazel && \ + exec env - \ + /usr/bin/gcc -o bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params) +</pre> +<p> + Where possible, commands are printed in a Bourne shell compatible syntax, + so that they can be easily copied and pasted to a shell command prompt. + (The surrounding parentheses are provided to protect your shell from the + <code>cd</code> and <code>exec</code> calls; be sure to copy them!) + However some commands are implemented internally within Bazel, such as + creating symlink trees. For these there's no command line to display. + +</p> + +<p> + See also <a href="#flag--verbose_failures">--verbose_failures</a>, below. +</p> + +<h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4> +<p> + This option causes Bazel's execution phase to print the full command line + for commands that failed. This can be invaluable for debugging a + failing build. +</p> +<p> + Failing commands are printed in a Bourne shell compatible syntax, suitable + for copying and pasting to a shell prompt. +</p> + +<h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4> +<p> + This option controls whether stamping is enabled for + rule types that support it. For most of the supported rule types stamping is + enabled by default (e.g. <code>cc_binary</code>). + + By default, stamping is disabled for all tests. Specifying + <code class='flag'>--stamp</code> does not force affected targets to be rebuilt, + if their dependencies have not changed. +</p> + +<p> + Stamping can be enabled or disabled explicitly in BUILD using + the <code>stamp</code> attribute of certain rule types, please refer to + the <a href="be/overview.html">build encyclopedia</a> for details. For + rules that are neither explicitly or implicitly configured as <code>stamp = + 0</code> or <code>stamp = 1</code>, the <code class='flag'>--[no]stamp</code> option + selects whether stamping is enabled. Bazel never stamps binaries that are + built for the host configuration, regardless of the stamp attribute. +</p> + +<h3 id='misc_build_options'>Miscellaneous options</h3> + +<h4 id='flag--symlink_prefix'><code class='flag'>--symlink_prefix <var>string</var></code></h4> +<p> + Changes the prefix of the generated convenience symlinks. The + default value for the symlink prefix is <code>bazel-</code> which + will create the symlinks <code>bazel-bin</code>, <code>bazel-testlogs</code>, and + <code>bazel-genfiles</code>. +</p> +<p> + If the symbolic links cannot be created for any reason, a warning is + issued but the build is still considered a success. In particular, + this allows you to build in a read-only directory or one that you have no + permission to write into. Any paths printed in informational + messages at the conclusion of a build will only use the + symlink-relative short form if the symlinks point to the expected + location; in other words, you can rely on the correctness of those + paths, even if you cannot rely on the symlinks being created. +</p> +<p> + Some common values of this option: +</p> +<ul> + + <li> + <p><b>Suppress symlink creation:</b> + <code class='flag'>--symlink_prefix=/</code> will cause Bazel to not + create or update any symlinks, including the <code>bazel-out</code> and + + <code>bazel-<workspace></code> + symlinks. Use this option to suppress symlink creation entirely. + </p> + </li> + <li> + <p><b>Reduce clutter:</b> + <code class='flag'>--symlink_prefix=.bazel/</code> will cause Bazel to create + symlinks called <code>bin</code> (etc) inside a hidden directory <code>.bazel</code>. + </p> + </li> +</ul> + +<h4 id='flag--platform_suffix'><code class='flag'>--platform_suffix <var>string</var></code></h4> +<p> + Adds a suffix to the configuration short name, which is used to determine the + output directory. Setting this option to different values puts the files into + different directories, for example to improve cache hit rates for builds that + otherwise clobber each others output files, or to keep the output files around + for comparisons. +</p> + +<h4 id='flag--default_visibility'><code class='flag'>--default_visibility=<var>(private|public)</var></code></h4> +<p> + Temporary flag for testing bazel default visibility changes. Not intended for general use + but documented for completeness' sake. +</p> + +<h2 id='bazel-releng'>Using Bazel for releases</h2> +<p> + Bazel is used both by software engineers during the development + cycle, and by release engineers when preparing binaries for deployment + to production. This section provides a list of tips for release + engineers using Bazel. + +</p> + +<h3>Significant options</h3> + +<p> + When using Bazel for release builds, the same issues arise as for + other scripts that perform a build, so you should read + the <a href='#scripting'>scripting</a> section of this manual. + In particular, the following options are strongly recommended: +</p> +<ul> + <li><a href='#bazelrc'><code class='flag'>--bazelrc=/dev/null</code></a></li> + <li><a href='#flag--batch'><code class='flag'>--batch</code></a></li> +</ul> + +<p> + These options (q.v.) are also important: +</p> + +<ul> + + <li><a href='#flag--package_path'><code class='flag'>--package_path</code></a></li> + <li><a href='#flag--symlink_prefix'><code class='flag'>--symlink_prefix</code></a>: + for managing builds for multiple configurations, + it may be convenient to distinguish each build + with a distinct identifier, e.g. "64bit" vs. "32bit". This option + differentiates the <code>bazel-bin</code> (etc.) symlinks. + </li> +</ul> + +<h2 id='test'>Running tests with Bazel</h2> +<p> + To build and run tests with bazel, type <code>bazel test</code> followed by + the name of the test targets. +</p> +<p> + By default, this command performs simultaneous build and test + activity, building all specified targets (including any non-test + targets specified on the command line) and testing + <code>*_test</code> and <code>test_suite</code> targets as soon as + their prerequisites are built, meaning that test execution is + interleaved with building. Doing so usually results in significant + speed gains. + +</p> + +<h3>Options for <code>bazel test</code></h3> + +<h4 id="flag--cache_test_results"><code class='flag'>--cache_test_results=(yes|no|auto)</code> (<code>-t</code>)</h4> +<p> + If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the + following conditions applies: +</p> +<ul> + <li>Bazel detects changes in the test or its dependencies</li> + <li>the test is marked as <code>external</code></li> + <li>multiple test runs were requested with <code class='flag'>--runs_per_test</code></li> + <li>the test failed.</li> +</ul> +<p> + If 'no', all tests will be executed unconditionally. +</p> +<p> + If 'yes', the caching behavior will be the same as auto + except that it may cache test failures and test runs with + <code class='flag'>--runs_per_test</code>. +</p> +<p> + Note that test results are <em>always</em> saved in Bazel's output tree, + regardless of whether this option is enabled, so + you needn't have used <code class='flag'>--cache_test_results</code> on the + prior run(s) of <code>bazel test</code> in order to get cache hits. + The option only affects whether Bazel will <em>use</em> previously + saved results, not whether it will save results of the current run. +</p> +<p> + Users who have enabled this option by default in + their <code>.bazelrc</code> file may find the + abbreviations <code>-t</code> (on) or <code>-t-</code> (off) + convenient for overriding the default on a particular run. +</p> + +<h4 id="flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></h4> +<p> + This option tells Bazel not to run the tests, but to merely check and report + the cached test results. If there are any tests which have not been + previously built and run, or whose tests results are out-of-date (e.g. because + the source code or the build options have changed), then Bazel will report + an error message ("test result is not up-to-date"), will record the test's + status as "NO STATUS" (in red, if color output is enabled), and will return + a non-zero exit code. +</p> +<p> + This option also implies + <code><a href="#flag--check_up_to_date">--check_up_to_date</a></code> behavior. +</p> +<p> + This option may be useful for pre-submit checks. +</p> + +<h4 id="flag--test_verbose_timeout_warnings"><code class='flag'>--test_verbose_timeout_warnings</code></h4> +<p> + This option tells Bazel to explicitly warn the user if a test's timeout is +significantly longer then the test's actual execution time. While a test's +timeout should be set such that it is not flaky, a test that has a highly +over-generous timeout can hide real problems that crop up unexpectedly. +</p> +<p> +For instance, a test that normally executes in a minute or two should not have +a timeout of ETERNAL or LONG as these are much, much too generous. + + This option is useful to help users decide on a good timeout value or + sanity check existing timeout values. +</p> +<p> +Note that each test shard is allotted the timeout of the entire +<code>XX_test</code> target. Using this option does not affect a test's timeout +value, merely warns if Bazel thinks the timeout could be restricted further. +</p> + +<h4 id='flag--test_keep_going'><code class='flag'>--[no]test_keep_going</code></h4> +<p> + By default, all tests are run to completion. If this flag is disabled, + however, the build is aborted on any non-passing test. Subsequent build steps + and test invocations are not run, and in-flight invocations are canceled. + Do not specify both <code class='flag'>--notest_keep_going</code> and + <code class='flag'>--keep_going</code>. +</p> + +<h4 id='flag--flaky_test_attempts'><code class='flag'>--flaky_test_attempts <var>attempts</var></code></h4> +<p> + This option specifies the maximum number of times a test should be attempted + if it fails for any reason. A test that initially fails but eventually + succeeds is reported as <code>FLAKY</code> on the test summary. It is, + however, considered to be passed when it comes to identifying Bazel exit code + or total number of passed tests. Tests that fail all allowed attempts are + considered to be failed. +</p> +<p> + By default (when this option is not specified, or when it is set to + "default"), only a single attempt is allowed for regular tests, and + 3 for test rules with the <code>flaky</code> attribute set. You can specify + an integer value to override the maximum limit of test attempts. Bazel allows + a maximum of 10 test attempts in order to prevent abuse of the system. +</p> + +<h4 id='flag--runs_per_test'><code class='flag'>--runs_per_test <var>[regex@]number</var></code></h4> +<p> + This option specifies the number of times each test should be executed. All + test executions are treated as separate tests (e.g. fallback functionality + will apply to each of them independently). +</p> +<p> + The status of a target with failing runs depends on the value of the + <code>--runs_per_test_detects_flakes</code> flag: +</p> +<ul> + <li>If absent, any failing run causes the entire test to fail.</li> + <li>If present and two runs from the same shard return PASS and FAIL, the test + will receive a status of flaky (unless other failing runs cause it to + fail).</li> +</ul> + +<p> + If a single number is specified, all tests will run that many times. + Alternatively, a regular expression may be specified using the syntax + regex@number. This constrains the effect of --runs_per_test to targets + which match the regex (e.g. "--runs_per_test=^//pizza:.*@4" runs all tests + under //pizza/ 4 times). + This form of --runs_per_test may be specified more than once. +</p> + +<h4 id='flag--runs_per_test_detects_flakes'><code + class='flag'>--[no]runs_per_test_detects_flakes</code></h4> +<p> + If this option is specified (by default it is not), Bazel will detect flaky + test shards through --runs_per_test. If one or more runs for a single shard + fail and one or more runs for the same shard pass, the target will be + considered flaky with the flag. If unspecified, the target will report a + failing status. +</p> + +<h4 id='flag--test_summary'><code class='flag'>--test_summary <var>output_style</var></code></h4> +<p> + Specifies how the test result summary should be displayed. +</p> +<ul> + <li><code>short</code> prints the results of each test along with the name of + the file containing the test output if the test failed. This is the default + value. + </li> + <li><code>terse</code> like <code>short</code>, but even shorter: only print + information about tests which did not pass. + </li> + <li><code>detailed</code> prints each individual test case that failed, not + only each test. The names of test output files are omitted. + </li> + <li><code>none</code> does not print test summary. + </li> +</ul> + +<h4 id='flag--test_output'><code class='flag'>--test_output <var>output_style</var></code></h4> +<p> + Specifies how test output should be displayed: +</p> +<ul> + <li><code>summary</code> shows a summary of whether each test passed or + failed. Also shows the output log file name for failed tests. The summary + will be printed at the end of the build (during the build, one would see + just simple progress messages when tests start, pass or fail). + This is the default behavior. + </li> + <li><code>errors</code> sends combined stdout/stderr output from failed tests + only into the stdout immediately after test is completed, ensuring that + test output from simultaneous tests is not interleaved with each other. + Prints a summary at the build as per summary output above. + </li> + <li><code>all</code> is similar to <code>errors</code> but prints output for + all tests, including those which passed. + </li> + <li><code>streamed</code> streams stdout/stderr output from each test in + real-time. + + </li> +</ul> + +<h4 id='flag--java_debug'><code class='flag'>--java_debug</code></h4> +<p> + This option causes the Java virtual machine of a java test to wait for a connection from a + JDWP-compliant debugger before starting the test. This option implies --test_output=streamed. +</p> + +<h4 id='flag--verbose_test_summary'><code class='flag'>--[no]verbose_test_summary</code></h4> +<p> + By default this option is enabled, causing test times and other additional + information (such as test attempts) to be printed to the test summary. If + <code class='flag'>--noverbose_test_summary</code> is specified, test summary will + include only test name, test status and cached test indicator and will + be formatted to stay within 80 characters when possible. +</p> + +<h4 id='flag--test_tmpdir'><code class='flag'>--test_tmpdir <var>path</var></code></h4> +<p> + Specifies temporary directory for tests executed locally. Each test will be + executed in a separate subdirectory inside this directory. The directory will + be cleaned at the beginning of the each <code>bazel test</code> command. + By default, bazel will place this directory under Bazel output base directory. + Note that this is a directory for running tests, not storing test results + (those are always stored under the <code>bazel-out</code> directory). +</p> + +<h4 id='flag--test_timeout'> + <code class='flag'>--test_timeout + <var>seconds</var></code> + OR + <code class='flag'>--test_timeout + <var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var> + </code> +</h4> +<p> + Overrides the timeout value for all tests by using specified number of + seconds as a new timeout value. If only one value is provided, then it will + be used for all test timeout categories. + </p> + <p> + Alternatively, four comma-separated values may be provided, specifying + individual timeouts for short, moderate, long and eternal tests (in that + order). + In either form, zero or a negative value for any of the test sizes will + be substituted by the default timeout for the given timeout categories as + defined by the page + <a href="test-encyclopedia.html">Writing Tests</a>. + By default, Bazel will use these timeouts for all tests by + inferring the timeout limit from the test's size whether the size is + implicitly or explicitly set. +</p> +<p> + Tests which explicitly state their timeout category as distinct from their + size will receive the same value as if that timeout had been implicitly set by + the size tag. So a test of size 'small' which declares a 'long' timeout will + have the same effective timeout that a 'large' tests has with no explicit + timeout. +</p> + +<h4 id='flag--test_arg'><code class='flag'>--test_arg <var>arg</var></code></h4> +<p> + Passes command-line options/flags/arguments to each test process. This + option can be used multiple times to pass several arguments, e.g. + <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>. +</p> + +<h4 id='flag--test_env'><code class='flag'>--test_env <var>variable</var>=<i>value</i></code> + OR + <code class='flag'>--test_env <var>variable</var></code></h4> +<p> + Specifies additional variables that must be injected into the test + environment for each test. If <var>value</var> is not specified it will be + inherited from the shell environment used to start the <code>bazel test</code> + command. +</p> +<p> + The environment can be accessed from within a test by using + <code>System.getenv("var")</code> (Java), + <code>getenv("var")</code> (C or C++), + +</p> + +<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4> +<p> + This specifies a prefix that the test runner will insert in front + of the test command before running it. The + <var>command-prefix</var> is split into words using Bourne shell + tokenization rules, and then the list of words is prepended to the + command that will be executed. +</p> +<p> + If the first word is a fully qualified label (i.e. starts with + <code>//</code>) it is built. Then the label is substituted by the + corresponding executable location that is prepended to the command + that will be executed along with the other words. +</p> + +<p> +Some caveats apply: +</p> +<ul> + <li> + The PATH used for running tests may be different than the PATH in your environment, + so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code> + command (the first word in <var>command-prefix</var>). + </li> + <li> + <b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code> + can't be used for interactive commands. + </li> + +</ul> +<p> +Examples: +</p> +<pre> + --run_under=/usr/bin/valgrind + --run_under=/usr/bin/strace + --run_under='/usr/bin/strace -c' + --run_under='/usr/bin/valgrind --quiet --num-callers=20' + +</pre> + +<h4>Test selection</h4> +<p> + As documented under <a href='#output-selection-options'>Output selection options</a>, + you can filter tests by <a href='#flag--test_size_filters'>size</a>, + <a href='#flag--test_timeout_filters'>timeout</a>, + <a href='#flag--test_tag_filters'>tag</a>, or + <a href='#flag--test_lang_filters'>language</a>. A convenience + <a href='#flag--test_filter'>general name filter</a> can forward particular + filter args to the test runner. +</p> + +<h4 id="other_options_for_bazel_test">Other options for <code>bazel test</code></h4> +<p> + The syntax and the remaining options are exactly like + <a href='#build'>bazel build</a>. +</p> + + + +<h2 id='run'>Running executables with Bazel</h2> +<p> + The <code>bazel run</code> command is similar to <code>bazel build</code>, except + it is used to build and run a single target. Here is a typical session: +</p> +<pre> + % bazel run -- java/myapp:myapp --arg1 --arg2 + Welcome to Bazel + INFO: Loading package: java/myapp + INFO: Loading package: foo/bar + INFO: Loading complete. Analyzing... + INFO: Found 1 target... + ... + Target //java/myapp:myapp up-to-date: + bazel-bin/java/myapp:myapp + INFO: Elapsed time: 0.638s, Critical Path: 0.34s + + INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2 + Hello there + $EXEC_ROOT/java/myapp/myapp + --arg1 + --arg2 +</pre> + +<p> + Bazel closes stdin, so you can't use <code>bazel run</code> + if you want to start an interactive program or pipe data to it. +</p> + +<p> + Note the use of the <code>--</code>. This is needed so that Bazel + does not interpret <code>--arg1</code> and <code>--arg2</code> as + Bazel options, but rather as part of the command line for running the binary. + (The program being run simply says hello and prints out its args.) +</p> + +<h3>Options for <code>bazel run</code></h3> + +<h4 id='flag--run_under_run'><code class='flag'>--run_under=<var>command-prefix</var></code></h4> +<p> + This has the same effect as the <code class='flag'>--run_under</code> option for + <code>bazel test</code> (<a href='#flag--run_under'>see above</a>), + except that it applies to the command being run by <code>bazel + run</code> rather than to the tests being run by <code>bazel test</code> + and cannot run under label. +</p> + +<h3>Executing tests</h3> + +<p> + <code>bazel run</code> can also execute test binaries, which has the effect of +running the test, but without the setup documented on the page +<a href='test-encyclopedia.html'>Writing Tests</a>, so that the test runs +in an environment closer to the current shell environment. Note that none of the +--test_* arguments have an effect when running a test in this manner. +</p> + +<h2 id='query'>Querying the dependency graph with Bazel</h2> + +<p> + Bazel includes a query language for asking questions about the + dependency graph used during the build. The query tool is an + invaluable aid to many software engineering tasks. +</p> +<p> + The query language is based on the idea of + algebraic operations over graphs; it is documented in detail in + + <a href="query.html">Bazel Query Reference</a>. + Please refer to that document for reference, for + examples, and for query-specific command-line options. +</p> + +<p> + The query tool accepts several command-line + option. <code class='flag'>--output</code> selects the output format. + <code class='flag'>--[no]keep_going</code> (disabled by default) causes the query + tool to continue to make progress upon errors; this behavior may be + disabled if an incomplete result is not acceptable in case of errors. +</p> +<p> + The <code class='flag'>--[no]host_deps</code> option, + enabled by default, causes dependencies on "host + configuration" targets to be included in the dependency graph over + which the query operates. + +</p> +<p> + The <code class='flag'>--[no]implicit_deps</code> option, enabled by default, causes + implicit dependencies to be included in the dependency graph over which the query operates. An + implicit dependency is one that is not explicitly specified in the BUILD file + but added by bazel. +</p> +<p> + Example: "Show the locations of the definitions (in BUILD files) of + all genrules required to build all the tests in the PEBL tree." +</p> +<pre> + bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))' +</pre> + + +<h2 id='misc'>Miscellaneous Bazel commands and options</h2> + +<h3 id='help'>The <code>help</code> command</h3> + +<p> + The <code>help</code> command provides on-line help. By default, it + shows a summary of available commands and help topics, as shown in + the <a href='#overview'><i>Bazel overview</i></a> section above. + Specifying an argument displays detailed help for a particular + topic. Most topics are Bazel commands, e.g. <code>build</code> + or <code>query</code>, but there are some additional help topics + that do not correspond to commands. +</p> + +<h4 id='flag--long'><code class='flag'>--[no]long</code> (<code>-l</code>)</h4> +<p> + By default, <code>bazel help [<var>topic</var>]</code> prints only a + summary of the relevant options for a topic. If + the <code class='flag'>--long</code> option is specified, the type, default value + and full description of each option is also printed. +</p> + +<h3 id='shutdown'>The <code>shutdown</code> command</h3> + +<p> + Bazel server processes (see <a href='#client/server'>Client/server + implementation</a>) may be stopped by using the <code>shutdown</code> + command. This command causes the Bazel server to exit as soon as it + becomes idle (i.e. after the completion of any builds or other + commands that are currently in progress). + + Bazel servers stop themselves after an idle timeout, so this command + is rarely necessary; however, it can be useful in scripts when it is + known that no further builds will occur in a given workspace. +</p> +<p> + <code>shutdown</code> accepts one + option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which + requires an integer argument (in MB). If specified, this makes the shutdown + conditional on the amount of memory already consumed. This is + useful for scripts that initiate a lot of builds, as any memory + leaks in the Bazel server could cause it to crash spuriously on + occasion; performing a conditional restart preempts this condition. +</p> + +<h3 id='info'>The <code>info</code> command</h3> + +<p> + The <code>info</code> command prints various values associated with + the Bazel server instance, or with a specific build configuration. + (These may be used by scripts that drive a build.) +</p> + +<p> + The <code>info</code> command also permits a single (optional) + argument, which is the name of one of the keys in the list below. + In this case, <code>bazel info <var>key</var></code> will print only + the value for that one key. (This is especially convenient when + scripting Bazel, as it avoids the need to pipe the result + through <code>sed -ne /key:/s/key://p</code>: +</p> + +<h4>Configuration-independent data</h4> +<ul> + <li><code>release</code>: the release label for this Bazel + instance, or "development version" if this is not a released + binary. + </li> + <li><code>workspace</code> the absolute path to the base workspace + directory. + </li> + <li><code>install_base</code>: the absolute path to the installation + directory used by this Bazel instance for the current user. Bazel + installs its internally required executables below this directory. + + </li> + <li><code>output_base</code>: the absolute path to the base output + directory used by this Bazel instance for the current user and + workspace combination. Bazel puts all of its scratch and build + output below this directory. + </li> + <li><code>execution_root</code>: the absolute path to the execution + root directory under output_base. This directory is the root for all files + accessible to commands executed during the build, and is the working + directory for those commands. If the workspace directory is writable, a + symlink named + + <code>bazel-<workspace></code> + is placed there pointing to this directory. + </li> + <li><code>output_path</code>: the absolute path to the output + directory beneath the execution root used for all files actually + generated as a result of build commands. If the workspace directory is + writable, a symlink named <code>bazel-out</code> is placed there pointing + to this directory. + </li> + <li><code>server_pid</code>: the process ID of the Bazel server + process. </li> + <li><code>command_log</code>: the absolute path to the command log file; + this contains the interleaved stdout and stderr streams of the most recent + Bazel command. Note that running <code>bazel info</code> will overwrite the + contents of this file, since it then becomes the most recent Bazel command. + However, the location of the command log file will not change unless you + change the setting of the <code class='flag'>--output_base</code> or + <code class='flag'>--output_user_root</code> options. + </li> + + <li><code>used-heap-size</code>, + <code>committed-size</code>, + <code>max-heap-size</code>: reports various JVM heap size + parameters. Respectively: memory currently used, memory currently + guaranteed to be available to the JVM from the system, maximum + possible allocation. + </li> + <li><code>gc-count</code>, <code>gc-time</code>: The cumulative count of + garbage collections since the start of this Bazel server and the time spent + to perform them. Note that these values are not reset at the start of every + build. + </li> + <li><code>package_path</code>: A colon-separated list of paths which would be + searched for packages by bazel. Has the same format as the + <code class='flag'>--package_path</code> build command line argument. + </li> +</ul> +<p> + Example: the process ID of the Bazel server. +</p> +<pre>% bazel info server_pid +1285 +</pre> + +<h4>Configuration-specific data</h4> +<p> + These data may be affected by the configuration options passed + to <code>bazel info</code>, for + example <code class='flag'>--cpu</code>, <code class='flag'>--compilation_mode</code>, + etc. The <code>info</code> command accepts all + the <a href='#analysis-options'>options that control dependency + analysis</a>, since some of these determine the location of the + output directory of a build, the choice of compiler, etc. +</p> +<ul> + <li> + <code>bazel-bin</code>, <code>bazel-testlogs</code>, + <code>bazel-genfiles</code>: reports the absolute path to + the <code>bazel-*</code> directories in which programs generated by the + build are located. This is usually, though not always, the same as + the <code>bazel-*</code> symlinks created in the base workspace directory after a + successful build. However, if the workspace directory is read-only, + no <code>bazel-*</code> symlinks can be created. Scripts that use + the value reported by <code>bazel info</code>, instead of assuming the + existence of the symlink, will be more robust. + </li> + <li> + The complete + <a href='be/make-variables.html' + >"Make" environment</a>. If the <code class='flag'>--show_make_env</code> flag is + specified, all variables in the current configuration's "Make" environment + are also displayed (e.g. <code>CC</code>, <code>GLIBC_VERSION</code>, etc). + These are the variables accessed using the <code>$(CC)</code> + or <code>varref("CC")</code> syntax inside BUILD files. + </li> +</ul> + +<p> + Example: the C++ compiler for the current configuration. + This is the <code>$(CC)</code> variable in the "Make" environment, + so the <code class='flag'>--show_make_env</code> flag is needed. +</p> + +<pre> + % bazel info --show_make_env -c opt COMPILATION_MODE + opt +</pre> + +<p> + Example: the <code>bazel-bin</code> output directory for the current + configuration. This is guaranteed to be correct even in cases where + the <code>bazel-bin</code> symlink cannot be created for some reason + (e.g. you are building from a read-only directory). +</p> + +<h3 id='version'>The <code>version</code> command</h3> + +<p> + The version command prints version details about the built Bazel + binary, including the changelist at which it was built and the date. + These are particularly useful in determining if you have the latest + Bazel, or if you are reporting bugs. Some of the interesting values + are: +</p> +<ul> + <li><code>changelist</code>: the changelist at which this version of + Bazel was released. + </li> + <li><code>label</code>: the release label for this Bazel + instance, or "development version" if this is not a released + binary. Very useful when reporting bugs. + </li> +</ul> + +<h3 id='mobile-install'>The <code>mobile-install</code> command</h3> +<p> + The <code>mobile-install</code> command installs apps to mobile devices. + Currently only Android devices running ART are supported. + + See <a href="mobile-install.html">bazel mobile-install</a> + for more information. +</p> +<p> + Note that this command does not install the same thing that + <code>bazel build</code> produces: Bazel tweaks the app so that it can be + built, installed and re-installed quickly. This should, however, be mostly + transparent to the app. +</p> +<p> + The following options are supported: +</p> +<h4 id='flag--incremental'><code class='flag'>--incremental</code></h4> +<p> + If set, Bazel tries to install the app incrementally, that is, only those + parts that have changed since the last build. This cannot update resources + referenced from <code>AndroidManifest.xml</code>, native code or Java + resources (i.e. ones referenced by <code>Class.getResource()</code>). If these + things change, this option must be omitted. Contrary to the spirit of Bazel + and due to limitations of the Android platform, it is the + <b>responsibility of the user</b> to know when this command is good enough and + when a full install is needed. + + If you are using a device with Marshmallow or later, consider the + <a href='#flag--split_apks'><code class='flag'>--split_apks</code></a> flag. +</p> +<h4 id='flag--split_apks'><code class='flag'>--split_apks</code></h4> +<p> + Whether to use split apks to install and update the application on the device. + Works only with devices with Marshmallow or later. Note that the + <a href='#flag--incremental'><code class='flag'>--incremental</code></a> flag + is not necessary when using <code class='flag'>--split_apks</code>. +</p> +<h4 id='flag--start_app'><code class='flag'>--start_app</code></h4> +<p> + Starts the app in a clean state after installing. Equivalent to + <code>--start=COLD</code>. +</p> +<h4 id='flag--debug_app'><code class='flag'>--debug_app</code></h4> +<p> + Waits for debugger to be attached before starting the app in a clean state after installing. + Equivalent to <code>--start=DEBUG</code>. +</p> +<h4 id='flag--start'><code class='flag'>--start=<i>start_type</i></code></h4> +<p> + How the app should be started after installing it. Supported <i>start_type</i>s are: + <ul> + <li><code>NO</code> Does not start the app. This is the default.</li> + <li><code>COLD</code> Starts the app from a clean state after install.</li> + <li><code>WARM</code> Preserves and restores the application state on incremental installs.</li> + <li><code>DEBUG</code> Waits for the debugger before starting the app in a clean state after install.</li> + </ul> + Note that if more than one of <code class='flag'>--start=<i>start_type</i></code>, + <code class='flag'>--start_app</code> or + <code class='flag'>--debug_app</code> is set, the last value will be used. +</p> +<h4 id='flag--adb'><code class='flag'>--adb <var>path</var></code></h4> +<p> + Indicates the <code>adb</code> binary to be used. + + The default is to use the adb in the Android SDK specified by + <a href='#flag--android_sdk'><code class='flag'>--android_sdk</code></a>. + +</p> +<h4 id='flag--adb_arg'><code class='flag'>--adb_arg <var>arg</var></code></h4> +<p> + Extra arguments to <code>adb</code>. These come before the subcommand in the + command line and are typically used to specify which device to install to. + For example, to select the Android device or emulator to use: +<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef +</pre> +will invoke <code>adb</code> as +<pre> +adb -s deadbeef install ... +</pre> +</p> +<h4 id='flag--adb_jobs'><code class='flag'>--adb_jobs <var>number</var></code></h4> +<p> + The number of instances of adb to use in parallel to update files on the + device. +</p> +<h4 id='flag--incremental_install_verbosity'><code class='flag'>--incremental_install_verbosity <var>number</var></code></h4> +<p> + The verbosity for incremental install. Set to 1 for debug logging to be + printed to the console. +</p> + +<h3 id='analyze-profile'>The <code>analyze-profile</code> command</h3> + +<p> + The <code>analyze-profile</code> command analyzes data previously gathered + during the build using <code class='flag'>--profile</code> option. It provides several + options to either perform analysis of the build execution or export data in + the specified format. + +</p> +<p> + The following options are supported: +</p> +<ul> + <li><code id='flag--dump'>--dump=text</code> displays all gathered data in a + <a href='#dump-text-format'>human-readable format</a></li> + <li><code>--dump=raw</code> displays all gathered data in a + <a href='#dump-raw-format'>script-friendly format</a></li> + <li><code id='flag--html'>--html</code> generates an <a href='#dump-html-format'>HTML file</a> visualizing the + actions and rules executed in the build, as well as summary statistics for the build + <ul> + <li><code id='flag--html_details'>--html_details</code> adds more fine-grained + information on actions and rules to the HTML visualization</li> + <ul> + <li><code id='flag--html_histograms'>--html_histograms</code> adds histograms for Skylark + functions clicked in the statistics table. This will increase file size massively</li> + <li><code id='flag--nochart'>--nochart</code> hides the task chart from generated HTML + </li> + </ul> + </ul> + </li> + <li><code id='flag--combine'>--combine</code> combines multiple profile data files into a single + report. Does not generate HTML task charts</li> + <li><code id='flag--task_tree'>--task_tree</code> prints the tree of tasks matching the given + regular expression + <ul> + <li><code id='flag--task_tree_threshold'>--task_tree_threshold</code> skip tasks with duration + less than threshhold, in milliseconds. Default is 50ms</li> + </ul> + </li> +</ul> + +<p> + See the section on <a href='#profiling'>Troubleshooting performance by profiling</a> for + format details and usage help. + +</p> + +<h3 id='canonicalize'>The <code>canonicalize-flags</code> command</h3> + +<p> + The <code>canonicalize-flags</code> command, which takes a list of options for + a Bazel command and returns a list of options that has the same effect. The + new list of options is canonical, i.e., two lists of options with the same + effect are canonicalized to the same new list. +</p> +<p> + The <code class='flag'>--for_command</code> option can be used to select between different + commands. At this time, only <code>build</code> and <code>test</code> are + supported. Options that the given command does not support cause an error. +</p> +<p> + Note that a small number of options cannot be reordered, because Bazel cannot + ensure that the effect is identical. +</p> + +<h3 id='startup_options'>Bazel startup options</h3> + +<p> + The options described in this section affect the startup of the Java + virtual machine used by Bazel server process, and they apply to all + subsequent commands handled by that server. If there is an already + running Bazel server and the startup options do not match, it will + be restarted. +</p> +<p> + All of the options described in this section must be specified using the + <code class='flag'>--key=value</code> or <code class='flag'>--key value</code> + syntax. Also, these options must appear <i>before</i> the name of the Bazel + command. +</p> + +<h4 id='flag--output_base'><code class='flag'>--output_base=<var>dir</var></code></h4> +<p> + This option requires a path argument, which must specify a + writable directory. Bazel will use this location to write all its + output. The output base is also the key by which the client locates + the Bazel server. By changing the output base, you change the server + which will handle the command. +</p> +<p> + By default, the output base is derived from the user's login name, + and the name of the workspace directory (actually, its MD5 digest), + so a typical value looks like: + + <code>/var/tmp/google/_bazel_jrluser/d41d8cd98f00b204e9800998ecf8427e</code>. + Note that the client uses the output base to find the Bazel server + instance, so if you specify a different output base in a Bazel + command, a different server will be found (or started) to handle the + request. It's possible to perform two concurrent builds in the same + workspace directory by varying the output base. +</p> + +<p>For example:</p> +<pre> + % bazel --output_base /tmp/1 build //foo & bazel --output_base /tmp/2 build //bar +</pre> +<p> + In this command, the two Bazel commands run concurrently (because of + the shell <code>&</code> operator), each using a different Bazel + server instance (because of the different output bases). + In contrast, if the default output base was used in both commands, + then both requests would be sent to the same server, which would + handle them sequentially: building <code>//foo</code> first, followed + by an incremental build of <code>//bar</code>. +</p> +<p> + We recommend you do not use NFS locations for the output base, as + the higher access latency of NFS will cause noticeably slower + builds. +</p> + +<h4 id='flag--output_user_root'><code class='flag'>--output_user_root=<var>dir</var></code></h4> +<p> + By default, the <code>output_base</code> value is chosen to as to + avoid conflicts between multiple users building in the same workspace directory. + In some situations, though, it is desirable to build from a directory + shared between multiple users; release engineers often do this. In + those cases it may be useful to deliberately override the default so + as to ensure "conflicts" (i.e., sharing) between multiple users. + Use the <code class='flag'>--output_user_root</code> option to achieve this: the + output base is placed in a subdirectory of the output user root, + with a unique name based on the workspace, so the result of using an + output user root that is not a function of <code>$USER</code> is + sharing. Of course, it is important to ensure (via umask and group + membership) that all the cooperating users can read/write each + others files. +</p> +<p> + If the <code class='flag'>--output_base</code> option is specified, it overrides + using <code class='flag'>--output_user_root</code> to calculate the output base. +</p> +<p> + The install base location is also calculated based on + <code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded + binaries. +</p> +<p> + You can also use the <code class='flag'>--output_user_root</code> option to choose an + alternate base location for all of Bazel's output (install base and output + base) if there is a better location in your filesystem layout. +</p> + +<h4 id='flag--host_jvm_args'><code class='flag'>--host_jvm_args=<var>string</var></code></h4> +<p> + Specifies a startup option to be passed to the Java virtual machine in which <i>Bazel itself</i> + runs. This can be used to set the stack size, for example: +</p> +<pre> + % bazel --host_jvm_args="-Xss256K" build //foo +</pre> +<p> + This option can be used multiple times with individual arguments. Note that + setting this flag should rarely be needed. You can also pass a space-separated list of strings, + each of which will be interpreted as a separate JVM argument, but this feature will soon be + deprecated. + +</p> +<p> + That this does <i>not</i> affect any JVMs used by + subprocesses of Bazel: applications, tests, tools, etc. To pass + JVM options to executable Java programs, whether run by <code>bazel + run</code> or on the command-line, you should use + the <code>--jvm_flags</code> argument which + all <code>java_binary</code> and <code>java_test</code> programs + support. Alternatively for tests, use <code>bazel + test --test_arg=--jvm_flags=foo ...</code>. +</p> + +<h4 id='flag--host_jvm_debug'><code class='flag'>--host_jvm_debug</code></h4> +<p> + This option causes the Java virtual machine to wait for a connection + from a JDWP-compliant debugger before + calling the main method of <i>Bazel itself</i>. This is primarily + intended for use by Bazel developers. +</p> +<p> + (Please note that this does <i>not</i> affect any JVMs used by + subprocesses of Bazel: applications, tests, tools, etc.) +</p> + +<h4 id='flag--batch'><code class='flag'>--batch</code></h4> +<p> + This switch will cause bazel to be run in batch mode, instead of the + standard client/server mode described <a href='#client/server'>above</a>. + Doing so provides more predictable semantics with respect to signal handling, + job control, and environment variable inheritance, and is necessary for running + bazel in a chroot jail. +</p> + +<p> + Batch mode retains proper queueing semantics within the same output_base. + That is, simultaneous invocations will be processed in order, without overlap. + If a batch mode bazel is run on a client with a running server, it first + kills the server before processing the command. +</p> + +<p> + Bazel will run slower in batch mode, compared to client/server mode. + Among other things, the build file cache is memory-resident, so it is not + preserved between sequential batch invocations. + Therefore, using batch mode often makes more sense in cases where performance + is less critical, such as continuous builds. +</p> + +<h4 id='flag--max_idle_secs'><code class='flag'>--max_idle_secs <var>n</var></code></h4> +<p> + This option specifies how long, in seconds, the Bazel server process + should wait after the last client request, before it exits. The + default value is 10800 (3 hours). +</p> +<p> + This option may be used by scripts that invoke Bazel to ensure that + they do not leave Bazel server processes on a user's machine when they + would not be running otherwise. + For example, a presubmit script might wish to + invoke <code>bazel query</code> to ensure that a user's pending + change does not introduce unwanted dependencies. However, if the + user has not done a recent build in that workspace, it would be + undesirable for the presubmit script to start a Bazel server just + for it to remain idle for the rest of the day. + By specifying a small value of <code class='flag'>--max_idle_secs</code> in the + query request, the script can ensure that <i>if</i> it caused a new + server to start, that server will exit promptly, but if instead + there was already a server running, that server will continue to run + until it has been idle for the usual time. Of course, the existing + server's idle timer will be reset. +</p> + +<h4 id='flag--block_for_lock'><code class='flag'>--[no]block_for_lock</code></h4> +<p> + If enabled, Bazel will wait for other Bazel commands holding the + server lock to complete before progressing. If disabled, Bazel will + exit in error if it cannot immediately acquire the lock and + proceed. + + Developers might use this in presubmit checks to avoid long waits caused + by another Bazel command in the same client. +</p> + +<h4 id='flag--io_nice_level'><code class='flag'>--io_nice_level <var>n</var></code></h4> +<p> + Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority, + 7 is lowest. The anticipatory scheduler may only honor up to priority 4. + Negative values are ignored. +</p> + +<h4 id='flag--batch_cpu_scheduling'><code class='flag'>--batch_cpu_scheduling</code></h4> +<p> + Use <code>batch</code> CPU scheduling for Bazel. This policy is useful for + workloads that are non-interactive, but do not want to lower their nice value. + See 'man 2 sched_setscheduler'. This policy may provide for better system + interactivity at the expense of Bazel throughput. +</p> + +<h3 id='misc_options'>Miscellaneous options</h3> + +<h4 id='flag--announce_rc'><code class='flag'>--[no]announce_rc</code></h4> +<p> + Controls whether Bazel announces command options read from the bazelrc file when + starting up. (Startup options are unconditionally announced.) +</p> + +<h4 id='flag--color'><code class='flag'>--color (yes|no|auto)</code></h4> +<p> + This option determines whether Bazel will use colors to highlight + its output on the screen. +</p> +<p> + If this option is set to <code>yes</code>, color output is enabled. + If this option is set to <code>auto</code>, Bazel will use color output only if + the output is being sent to a terminal and the TERM environment variable + is set to a value other than <code>dumb</code>, <code>emacs</code>, or <code>xterm-mono</code>. + If this option is set to <code>no</code>, color output is disabled, + regardless of whether the output is going to a terminal and regardless + of the setting of the TERM environment variable. +</p> + +<h4 id='flag--config'><code class='flag'>--config <var>name</var></code></h4> +<p> + Selects additional config section from the rc files; for the current + <code>command</code>, it also pulls in the options from + <code>command:name</code> if such a section exists. Can be specified multiple + times to add flags from several config sections. Expansions can refer to other + definitions (i.e. expansions can be chained). +</p> + +<h4 id='flag--curses'><code class='flag'>--curses (yes|no|auto)</code></h4> +<p> + This option determines whether Bazel will use cursor controls + in its screen output. This results in less scrolling data, and a more + compact, easy-to-read stream of output from Bazel. This works well with + <code class='flag'>--color</code>. +</p> +<p> + If this option is set to <code>yes</code>, use of cursor controls is enabled. + If this option is set to <code>no</code>, use of cursor controls is disabled. + If this option is set to <code>auto</code>, use of cursor controls will be + enabled under the same conditions as for <code class='flag'>--color=auto</code>. +</p> + +<h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4> +<p> + If specified, a timestamp is added to each message generated by + Bazel specifying the time at which the message was displayed. +</p> + +<h2 id='scripting'>Calling Bazel from scripts</h2> + +<p> + Bazel can be called from scripts in order to perform a build, run + tests or query the dependency graph. Bazel has been designed to + enable effective scripting, but this section lists some details to + bear in mind to make your scripts more robust. +</p> + +<h3>Choosing the output base</h3> + +<p> + The <code class='flag'>--output_base</code> option controls where the Bazel process should + write the outputs of a build to, as well as various working files used + internally by Bazel, one of which is a lock that guards against + concurrent mutation of the output base by multiple Bazel processes. +</p> +<p> + Choosing the correct output base directory for your script depends + on several factors. If you need to put the build outputs in a + specific location, this will dictate the output base you need to + use. If you are making a "read only" call to Bazel + (e.g. <code>bazel query</code>), the locking factors will be more important. + In particular, if you need to run multiple instances of your script + concurrently, you will need to give each one a different (or random) output + base. +</p> +<p> + If you use the default output base value, you will be contending for + the same lock used by the user's interactive Bazel commands. If the + user issues long-running commands such as builds, your script will + have to wait for those commands to complete before it can continue. +</p> + +<h3>Server or no server?</h3> + +<p> + By default, Bazel uses a long-running <a + href='#client/server'>server process</a> as an optimization; this + behavior can be disabled using the <a + href='#flag--batch'><code class='flag'>--batch</code></a> option. There's no hard and + fast rule about whether or not your script should use a server, but + in general, the trade-off is between performance and reliability. + The server mode makes a sequence of builds, especially incremental + builds, faster, but its behavior is more complex and prone to + failure. We recommend in most cases that you use batch mode unless + the performance advantage is critical. +</p> +<p> + If you do use the server, don't forget to call <code>shutdown</code> + when you're finished with it, or, specify + <code class='flag'>--max_idle_secs=5</code> so that idle servers shut themselves + down promptly. +</p> + +<h3>What exit code will I get?</h3> + +<p> + Bazel attempts to differentiate failures due to the source code under +consideration from external errors that prevent Bazel from executing properly. +Bazel execution can result in following exit codes: +</p> + +<b>Exit Codes common to all commands:</b> +<ul> + <li><code>0</code> - Success</li> + <li><code>2</code> - Command Line Problem, Bad or Illegal flags or command + combination, or Bad Environment Variables. Your command line must be + modified.</li> + <li><code>8</code> - Build Interrupted but we terminated with an orderly shutdown.</li> + <li><code>32</code> - External Environment Failure not on this machine.</li> + <li><code>33</code> - OOM failure. You need to modify your command line.</li> + + <li><code>34</code> - Reserved for Google-internal use.</li> + <li><code>35</code> - Reserved for Google-internal use.</li> + <li><code>36</code> - Local Environmental Issue, suspected permanent.</li> + <li><code>37</code> - Unhandled Exception / Internal Bazel Error.</li> + <li><code>38</code> - Reserved for Google-internal use.</li> + <li><code>40-44</code> - Reserved for errors in Bazel's command line launcher, + <code>bazel.cc</code> that are not command line + related. Typically these are related to bazel server + being unable to launch itself.</li> +</ul> + +<b>Return codes for commands <code>bazel build</code>, <code>bazel test</code>.</b> +<ul> + <li><code>1</code> - Build failed.</li> + <li><code>3</code> - Build OK, but some tests failed or timed out.</li> + <li><code>4</code> - Build successful but no tests were found even though + testing was requested.</li> +</ul> + +<b>For <code>bazel run</code>:</b> +<ul> + <li><code>1</code> - Build failed.</li> + <li><code>6</code> - Run command failure. The executed subprocess returned a + non-zero exit code. The actual subprocess exit code is + given in stderr.</li> +</ul> + + +<b>For + + <code>bazel query</code>:</b> +<ul> + <li><code>3</code> - Partial success, but the query encountered 1 or more + errors in the input BUILD file set and therefore the + results of the operation are not 100% reliable. + This is likely due to a <code class='flag'>--keep_going</code> option + on the command line.</li> + <li><code>7</code> - Command failure.</li> +</ul> + +<p> + Future Bazel versions may add additional exit codes, replacing generic failure + exit code <code>1</code> with a different non-zero value with a particular + meaning. However, all non-zero exit values will always constitute an error. +</p> + +<h3>Reading the .bazelrc file</h3> + +<p> + By default, Bazel will read the <a + href='#bazelrc'><code>.bazelrc</code> file</a> from the base workspace + directory or the user's home directory. Whether or not this is + desirable is a choice for your script; if your script needs to be + perfectly hermetic (e.g. when doing release builds), you should + disable reading the .bazelrc file by using the option + <code class='flag'>--bazelrc=/dev/null</code>. If you want to perform a build + using the user's preferred settings, the default behavior is better. +</p> + +<h3>Command log</h3> + +<p> + The Bazel output is also available in a command log file which you can + find with the following command: +</p> + +<pre> +% bazel info command_log +</pre> + +<p> + The command log file contains the interleaved stdout and stderr streams + of the most recent Bazel command. Note that running <code>bazel info</code> + will overwrite the contents of this file, since it then becomes the most + recent Bazel command. However, the location of the command log file will + not change unless you change the setting of the <code class='flag'>--output_base</code> + or <code class='flag'>--output_user_root</code> options. +</p> + +<h3>Parsing output</h3> + +<p> + The Bazel output is quite easy to parse for many purposes. Two + options that may be helpful for your script are + <code class='flag'>--noshow_progress</code> which suppresses progress messages, + and <code class='flag'>--show_result <var>n</var></code>, which controls whether + or not "build up-to-date" messages are printed; these messages may + be parsed to discover which targets were successfully built, and the + location of the output files they created. Be sure to specify a + very large value of <i>n</i> if you rely on these messages. +</p> + +<h2 id='profiling'>Troubleshooting performance by profiling</h2> + +<p> + The first step in analyzing the performance of your build is to profile your build with the + <a href='#flag--profile'><code class='flag'>--profile</code></a> option. +</p> + +<p> + The file generated by the <a href='#flag--profile'><code class='flag'>--profile</code></a> + command is a binary file. Once you have generated this binary profile, you can analyze it using + Bazel's <a href='#analyze-profile'><code>analyze-profile</code></a> command. By default, it will + print out summary analysis information for each of the specified profile datafiles. This includes + cumulative statistics for different task types for each build phase and an analysis of the + critical execution path. +</p> + +<p> + The first section of the default output describes an overview of the time spent on the different + build phases: +</p> +<pre> +=== PHASE SUMMARY INFORMATION === + +Total launch phase time 6.00 ms 0.01% +Total init phase time 864 ms 1.11% +Total loading phase time 21.841 s 28.05% +Total analysis phase time 5.444 s 6.99% +Total preparation phase time 155 ms 0.20% +Total execution phase time 49.473 s 63.54% +Total finish phase time 83.9 ms 0.11% +Total run time 77.866 s 100.00% +</pre> + +<p> + The following sections show the execution time of different tasks happening during a particular + phase: +</p> +<pre> +=== INIT PHASE INFORMATION === + +Total init phase time 864 ms + +Total time (across all threads) spent on: + Type Total Count Average + VFS_STAT 2.72% 1 23.5 ms + VFS_READLINK 32.19% 1 278 ms + +=== LOADING PHASE INFORMATION === + +Total loading phase time 21.841 s + +Total time (across all threads) spent on: + Type Total Count Average + SPAWN 3.26% 154 475 ms + VFS_STAT 10.81% 65416 3.71 ms +[...] +SKYLARK_BUILTIN_FN 13.12% 45138 6.52 ms + +=== ANALYSIS PHASE INFORMATION === + +Total analysis phase time 5.444 s + +Total time (across all threads) spent on: + Type Total Count Average + SKYFRAME_EVAL 9.35% 1 4.782 s + SKYFUNCTION 89.36% 43332 1.06 ms + +=== EXECUTION PHASE INFORMATION === + +Total preparation time 155 ms +Total execution phase time 49.473 s +Total time finalizing build 83.9 ms + +Action dependency map creation 0.00 ms +Actual execution time 49.473 s + +Total time (across all threads) spent on: + Type Total Count Average + ACTION 2.25% 12229 10.2 ms +[...] + SKYFUNCTION 1.87% 236131 0.44 ms +</pre> + +<p> + The last section shows the critical path: +</p> +<pre> +Critical path (32.078 s): + Id Time Percentage Description +1109746 5.171 s 16.12% Building [...] +1109745 164 ms 0.51% Extracting interface [...] +1109744 4.615 s 14.39% Building [...] +[...] +1109639 2.202 s 6.86% Executing genrule [...] +1109637 2.00 ms 0.01% Symlinking [...] +1109636 163 ms 0.51% Executing genrule [...] + 4.00 ms 0.01% [3 middleman actions] +</pre> + +<p> + You can use the following options to display more detailed information: +</p> + +<ul> + <li id='dump-text-format'><a href='#flag--dump'><code>--dump=text</code></a> + <p> + This option prints all recorded tasks in the order they occurred. Nested tasks are indented + relative to the parent. For each task, output includes the following information: + </p> +<pre> +[task type] [task description] +Thread: [thread id] Id: [task id] Parent: [parent task id or 0 for top-level tasks] +Start time: [time elapsed from the profiling session start] Duration: [task duration] +[aggregated statistic for nested tasks, including count and total duration for each nested task] +</pre> + </li> + <li id='dump-raw-format'><a href='#flag--dump'><code>--dump=raw</code></a> + <p> + This option is most useful for automated analysis with scripts. It outputs each task record on + a single line using '|' delimiter between fields. Fields are printed in the following order: + </p> + <ol> + <li>thread id - integer positive number, identifies owner thread for the task</li> + <li>task id - integer positive number, identifies specific task</li> + <li>parent task id for nested tasks or 0 for root tasks</li> + <li>task start time in ns, relative to the start of the profiling session</li> + <li>task duration in ns. Please note that this will include duration of all subtasks.</li> + <li>aggregated statistic for immediate subtasks per type. This will include type name (lower + case), number of subtasks for that type and their cumulative duration. Types are + space-delimited and information for single type is comma-delimited.</li> + <li>task type (upper case)</li> + <li>task description</li> + </ol> + + Example: +<pre> +1|1|0|0|0||PHASE|Launch Bazel +1|2|0|6000000|0||PHASE|Initialize command +1|3|0|168963053|278111411||VFS_READLINK|/[...] +1|4|0|571055781|23495512||VFS_STAT|/[...] +1|5|0|869955040|0||PHASE|Load packages +[...] +</pre> + </li> + <li id='dump-html-format'><a href='#flag--html'><code>--html</code></a> + <p> + This option writes a file called <code><profile-file>.html</code> in the directory of the + profile file. Open it in your browser to see the visualization of the actions in your build. + Note that the file can be quite large and may push the capabilities of your browser – + please wait for the file to load. + </p> + <p> + In most cases, the HTML output from <a href='#flag--html'><code>--html</code></a> is easier to + read than the <a href='#flag--dump'><code>--dump</code></a> output. + It includes a Gantt chart that displays time on the horizontal axis and + threads of execution along the vertical axis. If you click on the Statistics link in the top + right corner of the page, you will jump to a section that lists summary analysis information + from your build. + </p> + <ul> + <li><a href='#flag--html_details'><code>--html_details</code></a> + <p> + Additionally passing this option will render a more detailed execution chart and additional + tables on the performance of built-in and user-defined Skylark functions. Beware that this + increases the file size and the load on the browser considerably. + </p> + </li> + </ul></li> +</ul> + +<p>If Bazel appears to be hung, you can hit <kbd><kbd>ctrl</kbd> + <kbd>\</kbd></kbd> or send + Bazel a <code>SIGQUIT</code> signal (<code>kill -3 $(bazel info server_pid)</code>) to get a + thread dump in the file <code>$(bazel info output_base)/server/jvm.out</code>. +</p> + +<p> + Since you may not be able to run <code>bazel info</code> if bazel is hung, the + <code>output_base</code> directory is usually the parent of the <code>bazel-<workspace></code> + symlink in your workspace directory. +</p> diff --git a/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/BazelJavaBuilder.java b/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/BazelJavaBuilder.java index c4e32c5a63..974d04077c 100644 --- a/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/BazelJavaBuilder.java +++ b/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/BazelJavaBuilder.java @@ -16,6 +16,7 @@ package com.google.devtools.build.buildjar; import com.google.common.annotations.VisibleForTesting; import com.google.common.collect.ImmutableList; +import com.google.common.collect.ImmutableSet; import com.google.devtools.build.buildjar.javac.BlazeJavacResult; import com.google.devtools.build.buildjar.javac.FormattedDiagnostic; import com.google.devtools.build.buildjar.javac.JavacOptions; @@ -30,8 +31,8 @@ import java.io.PrintWriter; import java.io.StringWriter; import java.nio.charset.Charset; import java.util.Arrays; +import java.util.Collections; import java.util.List; -import java.util.ListIterator; /** The JavaBuilder main called by bazel. */ public abstract class BazelJavaBuilder { @@ -86,6 +87,16 @@ public abstract class BazelJavaBuilder { build.getDependencyModule().reduceClasspath() ? new ReducedClasspathJavaLibraryBuilder() : new SimpleJavaLibraryBuilder()) { + + // TODO(b/36228287): delete this once the migration to -XepDisableAllChecks is complete + if (!Collections.disjoint( + build.getJavacOpts(), + ImmutableSet.of("-extra_checks", "-extra_checks:on", "-extra_checks:off"))) { + throw new InvalidCommandLineException( + "-extra_checks is no longer supported;" + + " use -XepDisableAllChecks to disable Error Prone"); + } + BlazeJavacResult result = builder.run(build); for (FormattedDiagnostic d : result.diagnostics()) { err.write(d.getFormatted() + "\n"); @@ -102,29 +113,6 @@ public abstract class BazelJavaBuilder { } } - private static boolean processAndRemoveExtraChecksOptions(List<String> args) { - // error-prone is enabled by default for Bazel. - boolean errorProneEnabled = true; - - ListIterator<String> arg = args.listIterator(); - while (arg.hasNext()) { - switch (arg.next()) { - case "-extra_checks": - case "-extra_checks:on": - errorProneEnabled = true; - arg.remove(); - break; - case "-extra_checks:off": - errorProneEnabled = false; - arg.remove(); - break; - default: // fall out - } - } - - return errorProneEnabled; - } - /** * Parses the list of arguments into a {@link JavaLibraryBuildRequest}. The returned {@link * JavaLibraryBuildRequest} object can be then used to configure the compilation itself. @@ -137,18 +125,10 @@ public abstract class BazelJavaBuilder { public static JavaLibraryBuildRequest parse(List<String> args) throws IOException, InvalidCommandLineException { OptionsParser optionsParser = new OptionsParser(args); - ImmutableList.Builder<BlazeJavaCompilerPlugin> plugins = ImmutableList.builder(); - - // Support for -extra_checks:off was removed from ErrorPronePlugin, but Bazel still needs it, - // so we'll emulate support for this here by handling the flag ourselves and not loading the - // plug-in when it is specified. - boolean errorProneEnabled = processAndRemoveExtraChecksOptions(optionsParser.getJavacOpts()); - if (errorProneEnabled) { - plugins.add(new ErrorPronePlugin(optionsParser.testOnly())); - } - + ImmutableList<BlazeJavaCompilerPlugin> plugins = + ImmutableList.of(new ErrorPronePlugin(optionsParser.testOnly())); JavaLibraryBuildRequest build = - new JavaLibraryBuildRequest(optionsParser, plugins.build(), new DependencyModule.Builder()); + new JavaLibraryBuildRequest(optionsParser, plugins, new DependencyModule.Builder()); build.setJavacOpts(JavacOptions.normalizeOptions(build.getJavacOpts())); return build; } diff --git a/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/javac/JavacOptions.java b/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/javac/JavacOptions.java index 7e6100a4ca..e7a0c1c19d 100644 --- a/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/javac/JavacOptions.java +++ b/src/java_tools/buildjar/java/com/google/devtools/build/buildjar/javac/JavacOptions.java @@ -80,6 +80,7 @@ public final class JavacOptions { private static boolean isBazelSpecificFlag(String opt) { return opt.startsWith("-Werror:") || opt.startsWith("-Xep") + // TODO(b/36228287): delete this once the migration to -XepDisableAllChecks is complete || opt.equals("-extra_checks") || opt.startsWith("-extra_checks:"); } diff --git a/src/test/shell/bazel/bazel_java_test.sh b/src/test/shell/bazel/bazel_java_test.sh index 7c415da5a9..a4f5db3780 100755 --- a/src/test/shell/bazel/bazel_java_test.sh +++ b/src/test/shell/bazel/bazel_java_test.sh @@ -453,7 +453,7 @@ EOF package(default_visibility=['//visibility:public']) java_library(name = 'hello_library', srcs = ['HelloLibrary.java'], - javacopts = ['-extra_checks:off'],); + javacopts = ['-XepDisableAllChecks'],); EOF bazel build //java/main:main &> $TEST_log || fail "build failed" |