| --- |
| layout: documentation |
| title: User manual |
| --- |
| <h1>Commands and options</h1> |
| |
| <h2 id='target-patterns'>Target syntax</h2> |
| |
| Some commands, like <code>build</code> or <code>test</code>, can operate |
| on a list of targets. They use a syntax more flexible than labels, which is |
| documented in the "<a href="guide.html#specifying-targets-to-build">Specifying |
| targets to build</a>" section of the User's Guide. |
| |
| <h2>Options</h2> |
| |
| <p> |
| The following sections describe the options available during a |
| build. When <code class='flag'>--long</code> is used on a help command, the on-line |
| help messages provide summary information about the meaning, type and |
| default value for each option. |
| </p> |
| |
| <p> |
| Most options can only be specified once. When specified multiple times, the |
| last instance wins. Options that can be specified multiple times are |
| identified in the on-line help with the text 'may be used multiple times'. |
| </p> |
| |
| <h3>Package location</h3> |
| |
| <h4 id='flag--package_path'><code class='flag'>--package_path</code></h4> |
| <p> |
| This option specifies the set of directories that are searched to |
| find the BUILD file for a given package. |
| </p> |
| |
| <p> |
| Bazel finds its packages by searching the package path. This is a colon |
| separated ordered list of bazel directories, each being the root of a |
| partial source tree. |
| </p> |
| |
| <p> |
| <i>To specify a custom package path</i> using the |
| <code class='flag'>--package_path</code> option: |
| </p> |
| <pre> |
| % bazel build --package_path %workspace%:/some/other/root |
| </pre> |
| <p> |
| Package path elements may be specified in three formats: |
| </p> |
| <ol> |
| <li> |
| If the first character is <code>/</code>, the path is absolute. |
| </li> |
| <li> |
| If the path starts with <code>%workspace%</code>, the path is taken relative |
| to the nearest enclosing bazel directory.<br> |
| For instance, if your working directory |
| is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the |
| string <code>%workspace%</code> in the package-path is expanded |
| to <code>/home/bob/clients/bob_client/bazel</code>. |
| </li> |
| <li> |
| Anything else is taken relative to the working directory.<br> This is usually not what you mean to do, |
| and may behave unexpectedly if you use Bazel from directories below the bazel workspace. |
| For instance, if you use the package-path element <code>.</code>, |
| and then cd into the directory |
| <code>/home/bob/clients/bob_client/bazel/foo</code>, packages |
| will be resolved from the |
| <code>/home/bob/clients/bob_client/bazel/foo</code> directory. |
| </li> |
| </ol> |
| <p> |
| If you use a non-default package path, we recommend that you specify |
| it in your <a href='guide.html#bazelrc'>Bazel configuration file</a> for |
| convenience. |
| </p> |
| <p> |
| <i>Bazel doesn't require any packages to be in the |
| current directory</i>, so you can do a build from an empty bazel |
| workspace if all the necessary packages can be found somewhere else |
| on the package path. |
| </p> |
| <p> |
| <i>Example</i>: Building from an empty client |
| </p> |
| <pre> |
| % mkdir -p foo/bazel |
| % cd foo/bazel |
| % touch WORKSPACE |
| % bazel build --package_path /some/other/path //foo |
| </pre> |
| <h3 id='checking-options'>Error checking</h3> |
| <p> |
| These options control Bazel's error-checking and/or warnings. |
| </p> |
| |
| <h4 id='flag--check_constraint'><code class='flag'>--check_constraint <var>constraint</var></code></h4> |
| <p> |
| This option takes an argument that specifies which constraint |
| should be checked. |
| </p> |
| <p> |
| Bazel performs special checks on each rule that is annotated with the |
| given constraint. |
| </p> |
| <p> |
| The supported constraints and their checks are as follows: |
| </p> |
| <ul> |
| |
| <li><code>public</code>: Verify that all java_libraries marked with |
| <code>constraints = ['public']</code> only depend on java_libraries |
| that are marked as <code>constraints = ['public']</code> too. If bazel |
| finds a dependency that does not conform to this rule, bazel will issue |
| an error. |
| </li> |
| </ul> |
| |
| <h4 id='flag--check_visibility'><code class='flag'>--[no]check_visibility</code></h4> |
| <p> |
| If this option is set to false, visibility checks are demoted to warnings. |
| The default value of this option is true, so that by default, visibility |
| checking is done. |
| |
| </p> |
| <h4 id='flag--output_filter'><code class='flag'>--output_filter <var>regex</var></code></h4> |
| <p> |
| The <code class='flag'>--output_filter</code> option will only show build and compilation |
| warnings for targets that match the regular expression. If a target does not |
| match the given regular expression and its execution succeeds, its standard |
| output and standard error are thrown away. |
| </p> |
| <p> |
| Here are some typical values for this option: |
| </p> |
| <table> |
| <tr> |
| <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td> |
| <td>Show the output for the specified packages.</td> |
| </tr> |
| <tr> |
| <td><code class='flag'>--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'</code></td> |
| <td>Don't show output for the specified packages.</td> |
| </tr> |
| <tr> |
| <td><code class='flag'>--output_filter=</code></td> |
| <td>Show everything. |
| </td> |
| </tr> |
| <tr> |
| <td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td> |
| <td>Show nothing. |
| </td> |
| </tr> |
| </table> |
| |
| <h3 id='flags-options'>Tool flags</h3> |
| <p> |
| These options control which options Bazel will pass to other tools. |
| </p> |
| |
| <h4 id='flag--copt'><code class='flag'>--copt <var>cc-option</var></code></h4> |
| <p> |
| This option takes an argument which is to be passed to the compiler. |
| The argument will be passed to the compiler whenever it is invoked |
| for preprocessing, compiling, and/or assembling C, C++, or |
| assembler code. It will not be passed when linking. |
| </p> |
| <p> |
| This option can be used multiple times. |
| For example: |
| </p> |
| <pre> |
| % bazel build --copt="-g0" --copt="-fpic" //foo |
| </pre> |
| <p> |
| will compile the <code>foo</code> library without debug tables, generating |
| position-independent code. |
| </p> |
| <p> |
| Note that changing <code class='flag'>--copt</code> settings will force a recompilation |
| of all affected object files. Also note that copts values listed in specific |
| cc_library or cc_binary build rules will be placed on the compiler command line |
| <em>after</em> these options. |
| </p> |
| <p> |
| Warning: C++-specific options (such as <code>-fno-implicit-templates</code>) |
| should be specified in <code class='flag'>--cxxopt</code>, not in |
| <code class='flag'>--copt</code>. Likewise, C-specific options (such as -Wstrict-prototypes) |
| should be specified in <code class='flag'>--conlyopt</code>, not in <code>copt</code>. |
| Similarly, compiler options that only have an |
| effect at link time (such as <code>-l</code>) should be specified in |
| <code class='flag'>--linkopt</code>, not in <code class='flag'>--copt</code>. |
| </p> |
| |
| <h4 id='flag--host_copt'><code class='flag'>--host_copt <var>cc-option</var></code></h4> |
| <p> |
| This option takes an argument which is to be passed to the compiler for source files |
| that are compiled in the host configuration. This is analogous to |
| the <a href='#flag--copt'><code class='flag'>--copt</code></a> option, but applies only to the |
| host configuration. |
| </p> |
| |
| <h4 id='flag--host_cxxopt'><code class='flag'>--host_cxxopt <var>cc-option</var></code></h4> |
| <p> |
| This option takes an argument which is to be passed to the compiler for C++ source files |
| that are compiled in the host configuration. This is analogous to |
| the <a href='#flag--cxxopt'><code class='flag'>--cxxopt</code></a> option, but applies only to the |
| host configuration. |
| </p> |
| |
| <h4 id='flag--conlyopt'><code class='flag'>--conlyopt <var>cc-option</var></code></h4> |
| <p> |
| This option takes an argument which is to be passed to the compiler when compiling C source files. |
| </p> |
| <p> |
| This is similar to <code class='flag'>--copt</code>, but only applies to C compilation, |
| not to C++ compilation or linking. So you can pass C-specific options |
| (such as <code>-Wno-pointer-sign</code>) using <code class='flag'>--conlyopt</code>. |
| </p> |
| <p> |
| Note that copts parameters listed in specific cc_library or cc_binary build rules |
| will be placed on the compiler command line <em>after</em> these options. |
| </p> |
| |
| <h4 id='flag--cxxopt'><code class='flag'>--cxxopt <var>cc-option</var></code></h4> |
| <p> |
| This option takes an argument which is to be passed to the compiler when compiling C++ source |
| files. |
| </p> |
| <p> |
| This is similar to <code class='flag'>--copt</code>, but only applies to C++ compilation, |
| not to C compilation or linking. So you can pass C++-specific options |
| (such as <code>-fpermissive</code> or <code>-fno-implicit-templates</code>) using <code class='flag'>--cxxopt</code>. |
| For example: |
| </p> |
| <pre> |
| % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code |
| </pre> |
| <p> |
| Note that copts parameters listed in specific cc_library or cc_binary build rules |
| will be placed on the compiler command line <em>after</em> these options. |
| </p> |
| |
| <h4 id='flag--linkopt'><code class='flag'>--linkopt <var>linker-option</var></code></h4> |
| <p> |
| This option takes an argument which is to be passed to the compiler when linking. |
| </p> |
| <p> |
| This is similar to <code class='flag'>--copt</code>, but only applies to linking, |
| not to compilation. So you can pass compiler options that only make sense |
| at link time (such as <code>-lssp</code> or <code>-Wl,--wrap,abort</code>) |
| using <code class='flag'>--linkopt</code>. For example: |
| </p> |
| <pre> |
| % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code |
| </pre> |
| <p> |
| Build rules can also specify link options in their attributes. This option's |
| settings always take precedence. Also see |
| <a href="be/c-cpp.html#cc_library.linkopts">cc_library.linkopts</a>. |
| </p> |
| |
| <h4 id='flag--strip'><code class='flag'>--strip (always|never|sometimes)</code></h4> |
| <p> |
| This option determines whether Bazel will strip debugging information from |
| all binaries and shared libraries, by invoking the linker with the <code>-Wl,--strip-debug</code> option. |
| <code class='flag'>--strip=always</code> means always strip debugging information. |
| <code class='flag'>--strip=never</code> means never strip debugging information. |
| The default value of <code class='flag'>--strip=sometimes</code> means strip if the <code class='flag'>--compilation_mode</code> |
| is <code>fastbuild</code>. |
| </p> |
| <pre> |
| % bazel build --strip=always //foo:bar |
| </pre> |
| <p> |
| will compile the target while stripping debugging information from all generated |
| binaries. |
| </p> |
| <p> |
| Note that if you want debugging information, it's not enough to disable stripping; you also need to make |
| sure that the debugging information was generated by the compiler, which you can do by using either |
| <code>-c dbg</code> or <code class='flag'>--copt -g</code>. |
| </p> |
| <p> |
| Note also that Bazel's <code class='flag'>--strip</code> option corresponds with ld's <code>--strip-debug</code> option: |
| it only strips debugging information. If for some reason you want to strip <em>all</em> symbols, |
| not just <em>debug</em> symbols, you would need to use ld's <code>--strip-all</code> option, |
| which you can do by passing <code class='flag'>--linkopt=-Wl,--strip-all</code> to Bazel. Also be |
| aware that setting Bazel's <code class='flag'>--strip</code> flag will override |
| <code class='flag'>--linkopt=-Wl,--strip-all</code>, so you should only set one or the other. |
| </p> |
| |
| <h4 id='flag--stripopt'><code class='flag'>--stripopt <var>strip-option</var></code></h4> |
| <p> |
| An additional option to pass to the <code>strip</code> command when generating |
| a <a href="be/c-cpp.html#cc_binary_implicit_outputs"><code>*.stripped</code> |
| binary</a>. The default is <code>-S -p</code>. This option can be used |
| multiple times. |
| </p> |
| <p> |
| Note that <code class='flag'>--stripopt</code> does not apply to the stripping of the main |
| binary with <code><a href='#flag--strip'>--strip</a>=(always|sometimes)</code>. |
| </p> |
| |
| <h4 id='flag--fdo_instrument'><code class='flag'>--fdo_instrument <var>profile-output-dir</var></code></h4> |
| <p> |
| The <code class='flag'>--fdo_instrument</code> option enables the generation of |
| FDO (feedback directed optimization) profile output when the |
| built C/C++ binary is executed. For GCC, the argument provided is used as a |
| directory prefix for a per-object file directory tree of .gcda files |
| containing profile information for each .o file. |
| </p> |
| <p> |
| Once the profile data tree has been generated, the profile tree |
| should be zipped up, and provided to the |
| <code class='flag'>--fdo_optimize=<var>profile-zip</var></code> |
| Bazel option to enable the FDO optimized compilation. |
| |
| </p> |
| <p> |
| For the LLVM compiler the argument is also the directory under which the raw LLVM profile |
| data file(s) is dumped, e.g. |
| <code class='flag'>--fdo_instrument=<var>/path/to/rawprof/dir/</var></code>. |
| </p> |
| <p> |
| The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>--fdo_optimize</code> |
| cannot be used at the same time. |
| </p> |
| |
| <h4 id='flag--fdo_optimize'><code class='flag'>--fdo_optimize <var>profile-zip</var></code></h4> |
| <p> |
| The <code class='flag'>--fdo_optimize</code> option enables the use of the |
| per-object file profile information to perform FDO (feedback |
| directed optimization) optimizations when compiling. For GCC, the argument |
| provided is the zip file containing the previously-generated file tree |
| of .gcda files containing profile information for each .o file. |
| </p> |
| <p> |
| Alternatively, the argument provided can point to an auto profile |
| identified by the extension .afdo. |
| |
| </p> |
| <p> |
| Note that this option also accepts labels that resolve to source files. You |
| may need to add an <code>exports_files</code> directive to the corresponding package to |
| make the file visible to Bazel. |
| </p> |
| <p> |
| For the LLVM compiler the argument provided should point to the indexed LLVM |
| profile output file prepared by the llvm-profdata tool, and should have a .profdata |
| extension. |
| </p> |
| <p> |
| The options <code class='flag'>--fdo_instrument</code> and <code class='flag'> |
| --fdo_optimize</code> cannot be used at the same time. |
| </p> |
| |
| |
| <h4 id='flag--output_symbol_counts'><code class='flag'>--[no]output_symbol_counts</code></h4> |
| <p> |
| If enabled, each gold-invoked link of a C++ executable binary will output |
| a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold |
| option). For each linker input, the file logs the number of symbols that were |
| defined and the number of symbols that were used in the binary. |
| This information can be used to track unnecessary link dependencies. |
| The symbol counts file is written to the binary's output path with the name |
| <code>[targetname].sc</code>. |
| </p> |
| <p> |
| This option is disabled by default. |
| </p> |
| |
| <h4 id='flag--jvmopt'><code class='flag'>--jvmopt <var>jvm-option</var></code></h4> |
| <p> |
| This option allows option arguments to be passed to the Java VM. It can be used |
| with one big argument, or multiple times with individual arguments. For example: |
| </p> |
| <pre> |
| % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all |
| </pre> |
| <p> |
| will use the server VM for launching all Java binaries and set the |
| startup heap size for the VM to 256 MB. |
| </p> |
| |
| <h4 id='flag--javacopt'><code class='flag'>--javacopt <var>javac-option</var></code></h4> |
| <p> |
| This option allows option arguments to be passed to javac. It can be used |
| with one big argument, or multiple times with individual arguments. For example: |
| </p> |
| <pre> |
| % bazel build --javacopt="-g:source,lines" //myprojects:prog |
| </pre> |
| <p> |
| will rebuild a java_binary with the javac default debug info |
| (instead of the bazel default). |
| </p> |
| <p> |
| The option is passed to javac after the Bazel built-in default options for |
| javac and before the per-rule options. The last specification of |
| any option to javac wins. The default options for javac are: |
| </p> |
| |
| <pre> |
| -source 8 -target 8 -encoding UTF-8 |
| </pre> |
| <p> |
| Note that changing <code class='flag'>--javacopt</code> settings will force a recompilation |
| of all affected classes. Also note that javacopts parameters listed in |
| specific java_library or java_binary build rules will be placed on the javac |
| command line <em>after</em> these options. |
| </p> |
| |
| <h5 id='-extra_checks'><code>-extra_checks[:(off|on)]</code></h5> |
| |
| <p> |
| This javac option enables extra correctness checks. Any problems found will |
| be presented as errors. |
| Either <code>-extra_checks</code> or <code>-extra_checks:on</code> may be used |
| to force the checks to be turned on. <code>-extra_checks:off</code> completely |
| disables the analysis. |
| When this option is not specified, the default behavior is used. |
| </p> |
| |
| <h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps |
| (default|strict|off|warn|error)</code></h4> |
| <p> |
| This option controls whether javac checks for missing direct dependencies. |
| Java targets must explicitly declare all directly used targets as |
| dependencies. This flag instructs javac to determine the jars actually used |
| for type checking each java file, and warn/error if they are not the output |
| of a direct dependency of the current target. |
| </p> |
| |
| <ul> |
| <li> <code>off</code> means checking is disabled. |
| </li> |
| <li> <code>warn</code> means javac will generate standard java warnings of |
| type <code>[strict]</code> for each missing direct dependency. |
| </li> |
| <li> <code>default</code>, <code>strict</code> and <code>error</code> all |
| mean javac will generate errors instead of warnings, causing the current |
| target to fail to build if any missing direct dependencies are found. |
| This is also the default behavior when the flag is unspecified. |
| </li> |
| </ul> |
| |
| <h3 id='semantics-options'>Build semantics</h3> |
| <p> |
| These options affect the build commands and/or the output file contents. |
| </p> |
| |
| <h4 id='flag--compilation_mode'><code class='flag'>--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4> |
| <p> |
| 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, |
| and target CPU is allowed only if it has been specified in the currently |
| used CROSSTOOL file. |
| </p> |
| |
| <h4 id='flag--action_env'> |
| <code class='flag'>--action_env=<var>VAR=VALUE</var></code> |
| </h4> |
| <p> |
| Specifies the set of environment variables available during the execution of all actions. |
| Variables can be either specified by name, in which case the value will be taken from the |
| invocation environment, or by the `name=value` pair which sets the value independent of the |
| invocation environment. |
| |
| This `--action_env` flag can be specified multiple times. If a value is assigned to the same |
| variable across multiple `--action_env` flags, the latest assignment wins. |
| </p> |
| |
| <h4 id='flag--experimental_action_listener'> |
| <code class='flag'>--experimental_action_listener=<var>label</var></code> |
| </h4> |
| <p> |
| The <code>experimental_action_listener</code> option instructs Bazel to use |
| details from the <a href="be/extra-actions.html#action_listener" |
| ><code>action_listener</code></a> rule specified by <var>label</var> to |
| insert <a href="be/extra-actions.html#extra_action" |
| ><code>extra_actions</code></a> into the build graph. |
| </p> |
| |
| <h4 id='flag--experimental_extra_action_top_level_only'> |
| <code class='flag'>--[no]experimental_extra_action_top_level_only</code> |
| </h4> |
| <p> |
| If this option is set to true, extra actions specified by the |
| <a href='#flag--experimental_action_listener'> <code> |
| --experimental_action_listener</code></a> command line option will only be |
| scheduled for top level targets. |
| </p> |
| |
| <h4 id='flag--experimental_extra_action_filter'> |
| <code class='flag'>--experimental_extra_action_filter=<var>regex</var></code> |
| </h4> |
| <p> |
| The <code>experimental_extra_action_filter</code> option instructs Bazel to |
| filter the set of targets to schedule <code>extra_actions</code> for. |
| </p> |
| <p> |
| This flag is only applicable in combination with the |
| <a href='#flag--experimental_action_listener' |
| ><code>--experimental_action_listener</code></a> flag. |
| </p> |
| <p> |
| By default all <code>extra_actions</code> in the transitive closure of the |
| requested targets-to-build get scheduled for execution. |
| <code>--experimental_extra_action_filter</code> will restrict scheduling to |
| <code>extra_actions</code> of which the owner's label matches the specified |
| regular expression. |
| </p> |
| <p> |
| The following example will limit scheduling of <code>extra_actions</code> |
| to only apply to actions of which the owner's label contains '/bar/': |
| </p> |
| <pre>% bazel build --experimental_action_listener=//test:al //foo/... \ |
| --experimental_extra_action_filter=.*/bar/.* |
| </pre> |
| |
| <h4 id='flag--host_cpu'><code class='flag'>--host_cpu <var>cpu</var></code></h4> |
| <p> |
| This option specifies the name of the CPU architecture that should be |
| used to build host tools. |
| </p> |
| |
| <h4 id='flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu <var>cpu[,cpu]*</var></code></h4> |
| <p> |
| The CPUs to build C/C++ libraries for in the transitive <code>deps</code> of |
| <code>android_binary</code> |
| |
| rules. Other C/C++ rules are not affected. For example, if a <code>cc_library</code> |
| appears in the transitive <code>deps</code> of an <code>android_binary</code> rule and a |
| <code>cc_binary</code> rule, the <code>cc_library</code> will be built at least twice: |
| once for each CPU specified with <code class='flag'>--fat_apk_cpu</code> for the |
| <code>android_binary</code> rule, and once for the CPU specified with |
| <code class='flag'>--cpu</code> for the <code>cc_binary</code> rule. |
| |
| <p> |
| The default is <code>armeabi-v7a</code>. |
| </p> |
| <p> |
| One <code>.so</code> file will be created and packaged in the APK for |
| each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The name of the <code>.so</code> |
| file will be the name of the <code>android_binary</code> rule prefixed with "lib", e.g., if the name |
| of the <code>android_binary</code> is "foo", then the file will be <code>libfoo.so</code>. |
| </p> |
| |
| <p> |
| Note that an Android-compatible crosstool must be selected. |
| If an <code>android_ndk_repository</code> rule is defined in the |
| WORKSPACE file, an Android-compatible crosstool is automatically selected. |
| Otherwise, the crostool can be selected using the |
| <a href='#flag--android_crosstool_top'><code class='flag'>--android_crosstool_top</code></a> |
| or <a href='#flag--crosstool_top'><code class='flag'>--crosstool_top</code></a> flags. |
| </p> |
| </p> |
| |
| <h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt |
| <var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4> |
| <p> |
| When present, any C++ file with a label or an execution path matching one of the inclusion regex |
| expressions and not matching any of the exclusion expressions will be built |
| with the given options. The label matching uses the canonical form of the label |
| (i.e //<code>package</code>:<code>label_name</code>). |
| |
| The execution path is the relative path to your workspace directory including the base name |
| (including extension) of the C++ file. It also includes any platform dependent prefixes. |
| Note, that if only one of the label or the execution path matches the options will be used. |
| </p> |
| <p> |
| <b>Notes</b>: |
| To match the generated files (e.g. genrule outputs) |
| Bazel can only use the execution path. In this case the regexp shouldn't start with '//' |
| since that doesn't match any execution paths. Package names can be used like this: |
| <code class='flag'>--per_file_copt=base/.*\.pb\.cc@-g0</code>. This will match every |
| <code>.pb.cc</code> file under a directory called <code>base</code>. |
| </p> |
| <p> |
| This option can be used multiple times. |
| </p> |
| <p> |
| The option is applied regardless of the compilation mode used. I.e. it is possible |
| to compile with <code class='flag'>--compilation_mode=opt</code> and selectively compile some |
| files with stronger optimization turned on, or with optimization disabled. |
| </p> |
| <p> |
| <b>Caveat</b>: If some files are selectively compiled with debug symbols the symbols |
| might be stripped during linking. This can be prevented by setting |
| <code class='flag'>--strip=never</code>. |
| </p> |
| <p> |
| <b>Syntax</b>: <code>[+-]regex[,[+-]regex]...@option[,option]...</code> Where |
| <code>regex</code> stands for a regular expression that can be prefixed with |
| a <code>+</code> to identify include patterns and with <code>-</code> to identify |
| exclude patterns. <code>option</code> stands for an arbitrary option that is passed |
| to the C++ compiler. If an option contains a <code>,</code> it has to be quoted like so |
| <code>\,</code>. Options can also contain <code>@</code>, since only the first |
| <code>@</code> is used to separate regular expressions from options. |
| </p> |
| <p> |
| <b>Example</b>: |
| <code class='flag'>--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs</code> |
| adds the <code>-O0</code> and the <code>-fprofile-arcs</code> options to the command |
| line of the C++ compiler for all <code>.cc</code> files in <code>//foo/</code> except |
| <code>file.cc</code>. |
| </p> |
| <h4 id='flag--dynamic_mode'><code class='flag'>--dynamic_mode <var>mode</var></code></h4> |
| <p> |
| Determines whether C++ binaries will be linked dynamically, interacting with |
| the <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic |
| attribute</a> on build rules. |
| </p> |
| |
| <p> |
| Modes: |
| </p> |
| <ul> |
| <li><code>auto</code>: Translates to a platform-dependent mode; |
| <code>default</code> for linux and <code>off</code> for cygwin.</li> |
| <li><code>default</code>: Allows bazel to choose whether to link dynamically. |
| See <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic</a> for more |
| information.</li> |
| <li><code>fully</code>: Links all targets dynamically. This will speed up |
| linking time, and reduce the size of the resulting binaries. |
| |
| </li> |
| <li><code>off</code>: Links all targets in |
| <a href='be/c-cpp.html#cc_binary.linkstatic'>mostly static</a> mode. |
| If <code>-static</code> is set in linkopts, targets will change to fully |
| static.</li> |
| </ul> |
| |
| <h4 id='flag--fission'><code class='flag'>--fission (yes|no|[dbg][,opt][,fastbuild])</code></h4> |
| <p> |
| Enables |
| |
| <a href='https://gcc.gnu.org/wiki/DebugFission'>Fission</a>, |
| which writes C++ debug information to dedicated .dwo files instead of .o files, where it would |
| otherwise go. This substantially reduces the input size to links and can reduce link times. |
| |
| </p> |
| <p> |
| When set to <code class='flag'>[dbg][,opt][,fastbuild]</code> (example: |
| <code class='flag'>--fission=dbg,fastbuild</code>), Fission is enabled |
| only for the specified set of compilation modes. This is useful for bazelrc |
| settings. When set to <code class='flag'>yes</code>, Fission is enabled |
| universally. When set to <code class='flag'>no</code>, Fission is disabled |
| universally. Default is <code class='flag'>dbg</code>. |
| </p> |
| |
| <h4 id='flag--force_ignore_dash_static'><code class='flag'>--force_ignore_dash_static</code></h4> |
| <p> |
| If this flag is set, any <code>-static</code> options in linkopts of |
| <code>cc_*</code> rules BUILD files are ignored. This is only intended as a |
| workaround for C++ hardening builds. |
| </p> |
| |
| <h4 id='flag--force_pic'><code class='flag'>--[no]force_pic</code></h4> |
| <p> |
| If enabled, all C++ compilations produce position-independent code ("-fPIC"), |
| links prefer PIC pre-built libraries over non-PIC libraries, and links produce |
| position-independent executables ("-pie"). Default is disabled. |
| </p> |
| <p> |
| Note that dynamically linked binaries (i.e. <code>--dynamic_mode fully</code>) |
| generate PIC code regardless of this flag's setting. So this flag is for cases |
| where users want PIC code explicitly generated for static links. |
| </p> |
| |
| <h4 id='flag--android_resource_shrinking'><code class='flag'>--android_resource_shrinking</code></h4> |
| <p> |
| Selects whether to perform resource shrinking for android_binary rules. Sets the default for the |
| <a href='be/android.html#android_binary.shrink_resources'>shrink_resources attribute</a> on |
| android_binary rules; see the documentation for that rule for further details. Defaults to off. |
| </p> |
| |
| <h4 id='flag--custom_malloc'><code class='flag'>--custom_malloc <var>malloc-library-target</var></code></h4> |
| <p> |
| When specified, always use the given malloc implementation, overriding all |
| <code>malloc="target"</code> attributes, including in those targets that use the |
| default (by not specifying any <code>malloc</code>). |
| </p> |
| |
| <h4 id='flag--crosstool_top'><code class='flag'>--crosstool_top <var>label</var></code></h4> |
| <p> |
| This option specifies the location of the crosstool compiler suite |
| to be used for all C++ compilation during a build. Bazel will look in that |
| location for a CROSSTOOL file and uses that to automatically determine |
| settings for |
| |
| <code class='flag'>--compiler</code>. |
| </p> |
| |
| <h4 id='flag--host_crosstool_top'><code class='flag'>--host_crosstool_top <var>label</var></code></h4> |
| <p> |
| If not specified, bazel uses the value of <code class='flag'>--crosstool_top</code> to compile |
| code in the host configuration, i.e., tools run during the build. The main purpose of this flag |
| is to enable cross-compilation. |
| </p> |
| |
| <h4 id='flag--apple_crosstool_top'><code class='flag'>--apple_crosstool_top <var>label</var></code></h4> |
| <p> |
| The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of |
| objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites |
| <code class='flag'>--crosstool_top</code>. |
| </p> |
| |
| <h4 id='flag--android_crosstool_top'><code class='flag'>--android_crosstool_top <var>label</var></code></h4> |
| <p> |
| The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of |
| <code>android_binary</code> rules. This is useful if other targets in the |
| build require a different crosstool. The default is to use the crosstool |
| generated by the <code>android_ndk_repository</code> rule in the WORKSPACE file. |
| See also <a href='#flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu</code></a>. |
| </p> |
| <h4 id='flag--compiler'><code class='flag'>--compiler <var>version</var></code></h4> |
| <p> |
| This option specifies the C/C++ compiler version (e.g. <code>gcc-4.1.0</code>) |
| to be used for the compilation of binaries during the build. If you want to |
| build with a custom crosstool, you should use a CROSSTOOL file instead of |
| specifying this flag. |
| </p> |
| <p> |
| Note that only certain combinations of crosstool version, compiler version, |
| and target CPU are allowed. |
| </p> |
| |
| <h4 id='flag--android_sdk'><code class='flag'>--android_sdk <var>label</var></code></h4> |
| <p> |
| This option specifies the Android SDK/platform toolchain |
| and Android runtime library that will be used to build any Android-related |
| rule. |
| |
| The Android SDK will be automatically selected if an <code>android_sdk_repository</code> |
| rule is defined in the WORKSPACE file. |
| </p> |
| |
| <h4 id='flag--java_toolchain'><code class='flag'>--java_toolchain <var>label</var></code></h4> |
| <p> |
| This option specifies the label of the java_toolchain used to compile Java |
| source files. |
| </p> |
| |
| <h4 id='flag--host_java_toolchain'><code class='flag'>--host_java_toolchain <var>label</var></code></h4> |
| <p> |
| If not specified, bazel uses the value of <code class='flag'>--java_toolchain</code> to compile |
| code in the host configuration, i.e., tools run during the build. The main purpose of this flag |
| is to enable cross-compilation. |
| </p> |
| |
| <h4 id='flag--javabase'><code class='flag'>--javabase (<var>label</var>)</code></h4> |
| <p> |
| This option sets the <i>label</i> of the base Java installation to use for <i>bazel run</i>, |
| <i>bazel test</i>, and for Java binaries built by <code>java_binary</code> and |
| <code>java_test</code> rules. The <code>JAVABASE</code> and <code>JAVA</code> |
| <a href='be/make-variables.html'>"Make" variables</a> are derived from this option. |
| </p> |
| |
| <h4 id='flag--host_javabase'><code class='flag'>--host_javabase <var>label</var></code></h4> |
| <p> |
| This option sets the <i>label</i> of the base Java installation to use in the host configuration, |
| for example for host build tools including JavaBuilder and Singlejar. |
| </p> |
| <p> |
| This does not select the Java compiler that is used to compile Java |
| source files. The compiler can be selected by settings the |
| <a href="#flag--java_toolchain"><code class='flag'>--java_toolchain</code></a> |
| option. |
| </p> |
| |
| <h3 id='strategy-options'>Execution strategy</h3> |
| <p> |
| These options affect how Bazel will execute the build. |
| They should not have any significant effect on the output files |
| generated by the build. Typically their main effect is on the |
| speed on the build. |
| </p> |
| |
| <h4 id='flag--spawn_strategy'><code class='flag'>--spawn_strategy <var>strategy</var></code></h4> |
| <p> |
| This option controls where and how commands are executed. |
| </p> |
| <ul> |
| |
| <li> |
| <code>standalone</code> causes commands to be executed as local subprocesses. This value is |
| deprecated. Please use <code>local</code> instead. |
| </li> |
| <li> |
| <code>sandboxed</code> causes commands to be executed inside a sandbox on the local machine. |
| This requires that all input files, data dependencies and tools are listed as direct |
| dependencies in the <code>srcs</code>, <code>data</code> and <code>tools</code> attributes. |
| This is the default on systems that support sandboxed execution. |
| </li> |
| |
| <li> |
| <code>local</code> causes commands to be executed as local subprocesses. |
| </li> |
| |
| <li> |
| <code>worker</code> causes commands to be executed using a persistent worker, if available. |
| </li> |
| |
| <li> |
| <code>docker</code> causes commands to be executed inside a docker sandbox on the local machine. |
| This requires that docker is installed. |
| </li> |
| |
| <li> |
| <code>remote</code> causes commands to be executed remotely; this is only available if a |
| remote executor has been configured separately. |
| </li> |
| </ul> |
| |
| <h4 id='flag--strategy'><code class='flag'>--strategy <var>mnemonic</var>=<var>strategy</var></code></h4> |
| <p> |
| This option controls where and how commands are executed, overriding the default setting on a |
| per-mnemonic basis. See |
| <code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported |
| strategies and their effects. |
| </p> |
| |
| <h4 id='flag--strategy_regexp'><code class='flag'>--strategy_regexp <var><filter,filter,...>=<strategy></var></code></h4> |
| <p> |
| This option specifies which strategy should be used to execute commands that have descriptions |
| matching a certain <code>regex_filter</code>. See |
| <code class='flag'><a href="#flag--per_file_copt">--per_file_copt</a></code> for details on |
| regex_filter matching. See |
| <code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported |
| strategies and their effects. |
| </p> |
| <p> |
| The first <code>regex_filter</code> that matches the description is used. This option overrides |
| other flags for specifying strategy. |
| </p> |
| <ul> |
| <li> |
| Example: <code>--strategy_regexp=//foo.*\\.cc,-//foo/bar=local</code> means to run actions using |
| <code>local</code> strategy if their descriptions match //foo.*.cc but not //foo/bar. |
| </li> |
| <li> |
| Example: |
| <code>--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed</code> |
| will run 'Compiling //foo/bar/baz' with the <code>local</code> strategy, but reversing the order |
| would run it with <code>sandboxed</code>. |
| </li> |
| </ul> |
| |
| <h4 id='flag--genrule_strategy'><code class='flag'>--genrule_strategy <var>strategy</var></code></h4> |
| <p> |
| This is a deprecated short-hand for |
| <code class='flag'>--strategy=Genrule=<var>strategy</var></code>. |
| </p> |
| |
| <h4 id='flag--jobs'><code class='flag'>--jobs <var>n</var></code> (-j)</h4> |
| <p> |
| This option, which takes an integer argument, specifies a limit on |
| the number of jobs that should be executed concurrently during the |
| execution phase of the build. |
| </p> |
| <p> |
| Note that the number of concurrent jobs that Bazel will run |
| is determined not only by the <code class='flag'>--jobs</code> setting, but also |
| by Bazel's scheduler, which tries to avoid running concurrent jobs |
| that will use up more resources (RAM or CPU) than are available, |
| based on some (very crude) estimates of the resource consumption |
| of each job. The behavior of the scheduler can be controlled by |
| the <code class='flag'>--local_ram_resources</code> option. |
| </p> |
| |
| <h4 id='flag--progress_report_interval'><code class='flag'>--progress_report_interval <var>n</var></code></h4> |
| <p> |
| |
| Bazel periodically prints a progress report on jobs that are not |
| finished yet (e.g. long running tests). This option sets the |
| reporting frequency, progress will be printed every <code>n</code> |
| seconds. |
| </p> |
| <p> |
| The default is 0, that means an incremental algorithm: the first |
| report will be printed after 10 seconds, then 30 seconds and after |
| that progress is reported once every minute. |
| </p> |
| |
| <h4 id='flag--local_{ram,cpu}_resources'><code class='flag'>--local_{ram,cpu}_resources</code> |
| <var>resources or resource expression</var></h4> |
| <p> |
| These options specify the amount of local resources (RAM in MB and number of CPU logical cores) |
| that Bazel can take into consideration when scheduling build and test activities. They take |
| an integer, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by [-|*<float>float</float>] |
| (for example, <code class='flag'>--local_cpu_resources=2</code>, |
| <code class='flag'>--local_ram_resources=HOST_RAM*.5</code>, |
| <code class='flag'>--local_cpu_resources=HOST_CPUS-1</code>). |
| The flags are independent; one or both may be set. By default Bazel will estimate amount of RAM |
| and number of CPU cores directly from system configuration. |
| </p> |
| |
| <h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4> |
| <p> |
| This option, which is enabled by default, specifies whether the runfiles |
| symlinks for tests and binaries should be built in the output directory. |
| Using <code class='flag'>--nobuild_runfile_links</code> can be useful |
| to validate if all targets compile without incurring the overhead |
| for building the runfiles trees. |
| |
| </p> |
| |
| <p> |
| When tests (or applications) are executed, their run-time data |
| dependencies are gathered together in one place. Within Bazel's |
| output tree, this "runfiles" tree is typically rooted as a sibling of |
| the corresponding binary or test. |
| During test execution, runfiles may be accessed using paths of the form |
| <code>$TEST_SRCDIR/workspace/<var>packagename</var>/<var>filename</var></code>. |
| The runfiles tree ensures that tests have access to all the files |
| upon which they have a declared dependence, and nothing more. By |
| default, the runfiles tree is implemented by constructing a set of |
| symbolic links to the required files. As the set of links grows, so |
| does the cost of this operation, and for some large builds it can |
| contribute significantly to overall build time, particularly because |
| each individual test (or application) requires its own runfiles tree. |
| </p> |
| |
| <h4 id='flag--build_runfile_manifests'><code class='flag'>--[no]build_runfile_manifests</code></h4> |
| <p> |
| This option, which is enabled by default, specifies whether runfiles manifests |
| should be written to the output tree. |
| Disabling it implies <code class='flag'>--nobuild_runfile_links</code>. |
| |
| It can be disabled when executing tests remotely, as runfiles trees will |
| be created remotely from in-memory manifests. |
| |
| <h4 id='flag--discard_analysis_cache'> |
| <code class='flag'>--[no]discard_analysis_cache</code></h4> |
| <p> |
| When this option is enabled, Bazel will discard the analysis cache |
| right before execution starts, thus freeing up additional memory |
| (around 10%) for the <a href="guide.html#execution-phase">execution phase</a>. |
| The drawback is that further incremental builds will be slower. See also |
| <a href="/versions/{{ current_version }}/memory-saving-mode.html"> |
| memory-saving mode</a>. |
| </p> |
| |
| <h4 id='flag--keep_going'><code class='flag'>--[no]keep_going</code> (-k)</h4> |
| <p> |
| As in GNU Make, the execution phase of a build stops when the first |
| error is encountered. Sometimes it is useful to try to build as |
| much as possible even in the face of errors. This option enables |
| that behavior, and when it is specified, the build will attempt to |
| build every target whose prerequisites were successfully built, but |
| will ignore errors. |
| </p> |
| <p> |
| While this option is usually associated with the execution phase of |
| a build, it also effects the analysis phase: if several targets are |
| specified in a build command, but only some of them can be |
| successfully analyzed, the build will stop with an error |
| unless <code class='flag'>--keep_going</code> is specified, in which case the |
| build will proceed to the execution phase, but only for the targets |
| that were successfully analyzed. |
| </p> |
| |
| <h4 id='flag--use_ijars'><code class='flag'>--[no]use_ijars</code></h4> |
| <p> |
| This option changes the way <code>java_library</code> targets are |
| compiled by Bazel. Instead of using the output of a |
| <code>java_library</code> for compiling dependent |
| <code>java_library</code> targets, Bazel will create interface jars |
| that contain only the signatures of non-private members (public, |
| protected, and default (package) access methods and fields) and use |
| the interface jars to compile the dependent targets. This makes it |
| possible to avoid recompilation when changes are only made to |
| method bodies or private members of a class. |
| </p> |
| <p> |
| Note that using <code class='flag'>--use_ijars</code> might give you a different |
| error message when you are accidentally referring to a non visible |
| member of another class: Instead of getting an error that the member |
| is not visible you will get an error that the member does not exist. |
| </p> |
| <p> |
| Note that changing the <code class='flag'>--use_ijars</code> setting will force |
| a recompilation of all affected classes. |
| </p> |
| |
| <h4 id='flag--interface_shared_objects'> |
| <code class='flag'>--[no]interface_shared_objects</code> |
| </h4> |
| <p> |
| This option enables <i>interface shared objects</i>, which makes binaries and |
| other shared libraries depend on the <i>interface</i> of a shared object, |
| rather than its implementation. When only the implementation changes, Bazel |
| can avoid rebuilding targets that depend on the changed shared library |
| unnecessarily. |
| </p> |
| |
| <h3 id='output-selection-options'>Output selection</h3> |
| <p> |
| These options determine what to build or test. |
| </p> |
| |
| <h4 id="nobuild"><code class='flag'>--[no]build</code></h4> |
| <p> |
| This option causes the execution phase of the build to occur; it is |
| on by default. When it is switched off, the execution phase is |
| skipped, and only the first two phases, loading and analysis, occur. |
| </p> |
| <p> |
| This option can be useful for validating BUILD files and detecting |
| errors in the inputs, without actually building anything. |
| </p> |
| |
| <h4 id='flag--build_tests_only'><code class='flag'>--[no]build_tests_only</code></h4> |
| <p> |
| If specified, Bazel will build only what is necessary to run the *_test |
| and test_suite rules that were not filtered due to their |
| <a href='#flag--test_size_filters'>size</a>, |
| <a href='#flag--test_timeout_filters'>timeout</a>, |
| <a href='#flag--test_tag_filters'>tag</a>, or |
| <a href='#flag--test_lang_filters'>language</a>. |
| If specified, Bazel will ignore other targets specified on the command line. |
| By default, this option is disabled and Bazel will build everything |
| requested, including *_test and test_suite rules that are filtered out from |
| testing. This is useful because running |
| <code>bazel test --build_tests_only foo/...</code> may not detect all build |
| breakages in the <code>foo</code> tree. |
| </p> |
| |
| <h4 id='flag--check_up_to_date'><code class='flag'>--[no]check_up_to_date</code></h4> |
| <p> |
| This option causes Bazel not to perform a build, but merely check |
| whether all specified targets are up-to-date. If so, the build |
| completes successfully, as usual. However, if any files are out of |
| date, instead of being built, an error is reported and the build |
| fails. This option may be useful to determine whether a build has |
| been performed more recently than a source edit (e.g. for pre-submit |
| checks) without incurring the cost of a build. |
| </p> |
| <p> |
| See also <a href="#flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></a>. |
| </p> |
| |
| <h4 id='flag--compile_one_dependency'><code class='flag'>--[no]compile_one_dependency</code></h4> |
| <p> |
| Compile a single dependency of the argument files. This is useful for |
| syntax checking source files in IDEs, for example, by rebuilding a single |
| target that depends on the source file to detect errors as early as |
| possible in the edit/build/test cycle. This argument affects the way all |
| non-flag arguments are interpreted: for each source filename, one |
| rule that depends on it will be built. For |
| |
| C++ and Java |
| sources, rules in the same language space are preferentially chosen. For |
| multiple rules with the same preference, the one that appears first in the |
| BUILD file is chosen. An explicitly named target pattern which does not |
| reference a source file results in an error. |
| </p> |
| |
| <h4 id='flag--save_temps'><code class='flag'>--save_temps</code></h4> |
| <p> |
| The <code class='flag'>--save_temps</code> option causes temporary outputs from the compiler to be |
| saved. These include .s files (assembler code), .i (preprocessed C) and .ii |
| (preprocessed C++) files. These outputs are often useful for debugging. Temps will only be |
| generated for the set of targets specified on the command line. |
| </p> |
| <p> |
| Note that our implementation of <code class='flag'>--save_temps</code> does not use the compiler's |
| <code>-save-temps</code> flag. Instead, we do two passes, one with <code>-S</code> |
| and one with <code>-E</code>. A consequence of this is that if your build fails, |
| Bazel may not yet have produced the ".i" or ".ii" and ".s" files. |
| If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation, |
| you may need to also use <code class='flag'>--keep_going</code> so that Bazel will still try to |
| produce the preprocessed files after the compilation fails. |
| </p> |
| <p> |
| The <code class='flag'>--save_temps</code> flag currently works only for cc_* rules. |
| </p> |
| <p> |
| To ensure that Bazel prints the location of the additional output files, check that |
| your <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a> |
| setting is high enough. |
| </p> |
| |
| <h4 id='flag--build_tag_filters'><code class='flag'>--build_tag_filters <var>tag[,tag]*</var></code></h4> |
| <p> |
| If specified, Bazel will build only targets that have at least one required tag |
| (if any of them are specified) and does not have any excluded tags. Build tag |
| filter is specified as comma delimited list of tag keywords, optionally |
| preceded with '-' sign used to denote excluded tags. Required tags may also |
| have a preceding '+' sign. |
| </p> |
| |
| <h4 id='flag--test_size_filters'><code class='flag'>--test_size_filters <var>size[,size]*</var></code></h4> |
| <p> |
| If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> |
| is also specified) only test targets with the given size. Test size filter |
| is specified as comma delimited list of allowed test size values (small, |
| medium, large or enormous), optionally preceded with '-' sign used to denote |
| excluded test sizes. For example, |
| </p> |
| <pre> |
| % bazel test --test_size_filters=small,medium //foo:all |
| </pre> |
| and |
| <pre> |
| % bazel test --test_size_filters=-large,-enormous //foo:all |
| </pre> |
| <p> |
| will test only small and medium tests inside //foo. |
| </p> |
| <p> |
| By default, test size filtering is not applied. |
| </p> |
| |
| <h4 id='flag--test_timeout_filters'><code class='flag'>--test_timeout_filters <var>timeout[,timeout]*</var></code></h4> |
| <p> |
| If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> |
| is also specified) only test targets with the given timeout. Test timeout filter |
| is specified as comma delimited list of allowed test timeout values (short, |
| moderate, long or eternal), optionally preceded with '-' sign used to denote |
| excluded test timeouts. See <a href='#flag--test_size_filters'>--test_size_filters</a> |
| for example syntax. |
| </p> |
| <p> |
| By default, test timeout filtering is not applied. |
| </p> |
| |
| |
| <h4 id='flag--test_tag_filters'><code class='flag'>--test_tag_filters <var>tag[,tag]*</var></code></h4> |
| <p> |
| If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> |
| is also specified) only test targets that have at least one required tag |
| (if any of them are specified) and does not have any excluded tags. Test tag |
| filter is specified as comma delimited list of tag keywords, optionally |
| preceded with '-' sign used to denote excluded tags. Required tags may also |
| have a preceding '+' sign. |
| </p> |
| <p> |
| For example, |
| <pre> |
| % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all |
| </pre> |
| <p> |
| will test targets that are tagged with either <code>performance</code> or |
| <code>stress</code> tag but are <b>not</b> tagged with the <code>flaky</code> |
| tag. |
| </p> |
| <p> |
| By default, test tag filtering is not applied. Note that you can also filter |
| on test's <code>size</code> and <code>local</code> tags in |
| this manner. |
| </p> |
| |
| <h4 id='flag--test_lang_filters'><code class='flag'>--test_lang_filters <var>lang[,lang]*</var></code></h4> |
| <p> |
| Specifies a comma-separated list of test languages for languages with an official <code>*_test</code> rule the |
| (see <a href="be/overview.html">build encyclopedia</a> for a full list of these). Each |
| language can be optionally preceded with '-' to specify excluded |
| languages. The name used for each language should be the same as |
| the language prefix in the <code>*_test</code> rule, for example, |
| <code>cc</code>, <code>java</code> or <code>sh</code>. |
| </p> |
| <p> |
| If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> |
| is also specified) only test targets of the specified language(s). |
| </p> |
| <p> |
| For example, |
| </p> |
| <pre> |
| % bazel test --test_lang_filters=cc,java foo/... |
| </pre> |
| <p> |
| will test only the C/C++ and Java tests (defined using |
| <code>cc_test</code> and <code>java_test</code> rules, respectively) |
| in <code>foo/...</code>, while |
| </p> |
| <pre> |
| % bazel test --test_lang_filters=-sh,-java foo/... |
| </pre> |
| <p> |
| will run all of the tests in <code>foo/...</code> except for the |
| <code>sh_test</code> and <code>java_test</code> tests. |
| </p> |
| <p> |
| By default, test language filtering is not applied. |
| </p> |
| |
| <h4 id="flag--test_filter"><code class='flag'>--test_filter=<var>filter-expression</var></code></h4> |
| <p> |
| Specifies a filter that the test runner may use to pick a subset of tests for |
| running. All targets specified in the invocation are built, but depending on |
| the expression only some of them may be executed; in some cases, only certain |
| test methods are run. |
| </p> |
| <p> |
| The particular interpretation of <var>filter-expression</var> is up to |
| the test framework responsible for running the test. It may be a glob, |
| substring, or regexp. <code class='flag'>--test_filter</code> is a convenience |
| over passing different <code class='flag'>--test_arg</code> filter arguments, |
| but not all frameworks support it. |
| </p> |
| |
| <h3 id='verbosity'>Verbosity</h3> |
| |
| These options control the verbosity of Bazel's output, |
| either to the terminal, or to additional log files. |
| |
| <h4 id='flag--explain'><code class='flag'>--explain <var>logfile</var></code></h4> |
| <p> |
| This option, which requires a filename argument, causes the |
| dependency checker in <code>bazel build</code>'s execution phase to |
| explain, for each build step, either why it is being executed, or |
| that it is up-to-date. The explanation is written |
| to <i>logfile</i>. |
| </p> |
| <p> |
| If you are encountering unexpected rebuilds, this option can help to |
| understand the reason. Add it to your <code>.bazelrc</code> so that |
| logging occurs for all subsequent builds, and then inspect the log |
| when you see an execution step executed unexpectedly. This option |
| may carry a small performance penalty, so you might want to remove |
| it when it is no longer needed. |
| </p> |
| |
| <h4 id='flag--verbose_explanations'><code class='flag'>--verbose_explanations</code></h4> |
| <p> |
| This option increases the verbosity of the explanations generated |
| when the <a href='#flag--explain'>--explain</a> option is enabled. |
| </p> |
| <p> |
| In particular, if verbose explanations are enabled, |
| and an output file is rebuilt because the command used to |
| build it has changed, then the output in the explanation file will |
| include the full details of the new command (at least for most |
| commands). |
| </p> |
| <p> |
| Using this option may significantly increase the length of the |
| generated explanation file and the performance penalty of using |
| <code class='flag'>--explain</code>. |
| </p> |
| <p> |
| If <code class='flag'>--explain</code> is not enabled, then |
| <code class='flag'>--verbose_explanations</code> has no effect. |
| </p> |
| |
| <h4 id='flag--profile'><code class='flag'>--profile <var>file</var></code></h4> |
| <p> |
| This option, which takes a filename argument, causes Bazel to write |
| profiling data into a file. The data then can be analyzed or parsed using the |
| <code>bazel analyze-profile</code> command. The Build profile can be useful in |
| understanding where Bazel's <code>build</code> command is spending its time. |
| </p> |
| |
| <h4 id='flag--show_loading_progress'><code class='flag'>--[no]show_loading_progress</code></h4> |
| <p> |
| This option causes Bazel to output package-loading progress |
| messages. If it is disabled, the messages won't be shown. |
| </p> |
| |
| <h4 id='flag--show_progress'><code class='flag'>--[no]show_progress</code></h4> |
| <p> |
| This option causes progress messages to be displayed; it is on by |
| default. When disabled, progress messages are suppressed. |
| </p> |
| |
| <h4 id='flag--show_progress_rate_limit'><code class='flag'>--show_progress_rate_limit |
| <var>n</var></code></h4> |
| <p> |
| This option causes bazel to display only |
| one progress message per <code>n</code> seconds, where <var>n</var> is a real number. |
| If <code>n</code> is -1, all progress messages will be displayed. The default value for |
| this option is 0.03, meaning bazel will limit the progress messages to one per every |
| 0.03 seconds. |
| </p> |
| |
| <h4 id='flag--show_result'><code class='flag'>--show_result <var>n</var></code></h4> |
| <p> |
| This option controls the printing of result information at the end |
| of a <code>bazel build</code> command. By default, if a single |
| build target was specified, Bazel prints a message stating whether |
| or not the target was successfully brought up-to-date, and if so, |
| the list of output files that the target created. If multiple |
| targets were specified, result information is not displayed. |
| </p> |
| <p> |
| While the result information may be useful for builds of a single |
| target or a few targets, for large builds (e.g. an entire top-level |
| project tree), this information can be overwhelming and distracting; |
| this option allows it to be controlled. <code class='flag'>--show_result</code> |
| takes an integer argument, which is the maximum number of targets |
| for which full result information should be printed. By default, |
| the value is 1. Above this threshold, no result information is |
| shown for individual targets. Thus zero causes the result |
| information to be suppressed always, and a very large value causes |
| the result to be printed always. |
| </p> |
| <p> |
| Users may wish to choose a value in-between if they regularly |
| alternate between building a small group of targets (for example, |
| during the compile-edit-test cycle) and a large group of targets |
| (for example, when establishing a new workspace or running |
| regression tests). In the former case, the result information is |
| very useful whereas in the latter case it is less so. As with all |
| options, this can be specified implicitly via |
| the <a href='guide.html#bazelrc'><code>.bazelrc</code></a> file. |
| </p> |
| <p> |
| The files are printed so as to make it easy to copy and paste the |
| filename to the shell, to run built executables. The "up-to-date" |
| or "failed" messages for each target can be easily parsed by scripts |
| which drive a build. |
| </p> |
| |
| <h4 id='flag--subcommands'><code class='flag'>--subcommands</code> (<code>-s</code>)</h4> |
| <p> |
| This option causes Bazel's execution phase to print the full command line |
| for each command prior to executing it. |
| </p> |
| |
| <pre> |
| >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world'] |
| (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \ |
| exec env - \ |
| /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params) |
| </pre> |
| <p> |
| Where possible, commands are printed in a Bourne shell compatible syntax, |
| so that they can be easily copied and pasted to a shell command prompt. |
| (The surrounding parentheses are provided to protect your shell from the |
| <code>cd</code> and <code>exec</code> calls; be sure to copy them!) |
| However some commands are implemented internally within Bazel, such as |
| creating symlink trees. For these there's no command line to display. |
| |
| </p> |
| |
| <p> |
| <code class='flag'>--subcommands=pretty_print</code> may be passed to print |
| the arguments of the command as a list rather than as a single line. This may |
| help make long command lines more readable. |
| </p> |
| |
| <p> |
| See also <a href="#flag--verbose_failures">--verbose_failures</a>, below. |
| </p> |
| |
| <h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4> |
| <p> |
| This option causes Bazel's execution phase to print the full command line |
| for commands that failed. This can be invaluable for debugging a |
| failing build. |
| </p> |
| <p> |
| Failing commands are printed in a Bourne shell compatible syntax, suitable |
| for copying and pasting to a shell prompt. |
| </p> |
| |
| <h3 id='workspace_status'>Workspace status</h3> |
| |
| <p> |
| Use these options to "stamp" Bazel-built binaries: to embed additional information into the |
| binaries, such as the source control revision or other workspace-related information. You can use |
| this mechanism with rules that support the <code>stamp</code> attribute, such as |
| <code>genrule</code>, <code>cc_binary</code>, and more. |
| </p> |
| |
| <h4 id='flag--workspace_status_command'><code class='flag'>--workspace_status_command <var>program</var></code></h4> |
| <p> |
| This flag lets you specify a binary that Bazel runs before each build. The program can report |
| information about the status of the workspace, such as the current source control revision. |
| </p> |
| <p> |
| The flag's value must be a path to a native program. On Linux/macOS this may be any executable. |
| On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file. |
| </p> |
| |
| <p> |
| The program should print zero or more key/value pairs to standard output, one entry on each line, |
| then exit with zero (otherwise the build fails). The key names can be anything but they may only |
| use upper case letters and underscores. The first space after the key name separates it from the |
| value. The value is the rest of the line (including additional whitespaces). |
| </p> |
| <p> |
| Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and |
| "volatile" are a bit counter-intuitive, so don't think much about them.) |
| </p> |
| |
| <p>Bazel then writes the key-value pairs into two files:</p> |
| <ul> |
| <li> |
| <code>bazel-out/stable-status.txt</code> |
| contains all keys and values where the key's name starts with <code>STABLE_</code> |
| </li> |
| <li> |
| <code>bazel-out/volatile-status.txt</code> |
| contains the rest of the keys and their values |
| </li> |
| </ul> |
| |
| <p>The contract is:</p> |
| <ul> |
| <li> |
| <p> |
| "stable" keys' values should change rarely, if possible. If the contents of |
| <code>bazel-out/stable-status.txt</code> |
| change, Bazel invalidates the actions that depend on them. In |
| other words, if a stable key's value changes, Bazel will rerun stamped actions. |
| Therefore the stable status should not contain things like timestamps, because they change all |
| the time, and would make Bazel rerun stamped actions with each build. |
| </p> |
| <p>Bazel always outputs the following stable keys:</p> |
| <ul> |
| <li><code>BUILD_EMBED_LABEL</code>: value of <code class='flag'>--embed_label</code></li> |
| <li><code>BUILD_HOST</code>: the name of the host machine that Bazel is running on</li> |
| <li><code>BUILD_USER</code>: the name of the user that Bazel is running as</li> |
| </ul> |
| </li> |
| <li> |
| <p> |
| "volatile" keys' values may change often. Bazel expects them to change all the time, like |
| timestamps do, and duly updates the |
| <code>bazel-out/volatile-status.txt</code> |
| file. In order to avoid |
| rerunning stamped actions all the time though, <b>Bazel pretends that the volatile file never |
| changes</b>. In other words, if the volatile status file is the only file whose contents has |
| changed, Bazel will not invalidate actions that depend on it. If other inputs of the actions |
| have changed, then Bazel reruns that action, and the action will see the updated volatile |
| status, but just the volatile status changing alone will not invalidate the action. |
| </p> |
| <p>Bazel always outputs the following volatile keys:</p> |
| <ul> |
| <li> |
| <code>BUILD_TIMESTAMP</code>: time of the build in seconds since the Unix Epoch (the value |
| of <code>System.currentTimeMillis()</code> divided by a thousand) |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p> |
| On Linux/macOS you can pass <code class='flag'>--workspace_status_command=/bin/true</code> to |
| disable retrieving workspace status, because <code>true</code> does nothing, successfully (exits |
| with zero) and prints no output. On Windows you can pass the path of MSYS's <code>true.exe</code> |
| for the same effect. |
| </p> |
| |
| <p>If the workspace status command fails (exits non-zero) for any reason, the build will fail.</p> |
| |
| <p>Example program on Linux using Git:</p> |
| |
| <pre> |
| #!/bin/bash |
| echo "CURRENT_TIME $(date +%s)" |
| echo "RANDOM_HASH $(cat /dev/urandom | head -c16 | md5sum 2>/dev/null | cut -f1 -d' ')" |
| echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)" |
| echo "STABLE_USER_NAME $USER" |
| </pre> |
| |
| <p> |
| Pass this program's path with <code>--workspace_status_command</code>, and the stable status file |
| will include the STABLE lines and the volatile status file will include the rest of the lines. |
| </p> |
| |
| <h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4> |
| <p> |
| This option controls whether stamping is enabled for |
| rule types that support it. For most of the supported rule types stamping is |
| enabled by default (e.g. <code>cc_binary</code>). |
| |
| By default, stamping is disabled for all tests. Specifying |
| <code class='flag'>--stamp</code> does not force affected targets to be rebuilt, |
| if their dependencies have not changed. |
| </p> |
| |
| <p> |
| Stamping can be enabled or disabled explicitly in BUILD using |
| the <code>stamp</code> attribute of certain rule types, please refer to |
| the <a href="be/overview.html">build encyclopedia</a> for details. For |
| rules that are neither explicitly or implicitly configured as <code>stamp = |
| 0</code> or <code>stamp = 1</code>, the <code class='flag'>--[no]stamp</code> option |
| selects whether stamping is enabled. Bazel never stamps binaries that are |
| built for the host configuration, regardless of the stamp attribute. |
| </p> |
| |
| <h3 id='platform_build_options'>Platform</h3> |
| |
| <p> |
| Use these options to control the host and target platforms that configure how builds work, and to |
| control what execution platforms and toolchains are available to Bazel rules. |
| </p> |
| |
| <p> |
| Please see background information on |
| <a href="platforms.html">Platforms</a> and <a href="toolchains.html">Toolchains</a>. |
| </p> |
| |
| <h4 id="flag--platforms"><code class='flag'>--platforms <var>labels</var></code></h4> |
| <p> |
| The labels of the platform rules describing the target platforms for the |
| current command. |
| </p> |
| |
| <h4 id="flag--host_platform"><code class='flag'>--host_platform <var>label</var></code></h4> |
| <p> |
| The label of a platform rule that describes the host system. |
| </p> |
| |
| <h4 id="flag--extra_execution_platforms"><code class='flag'>--extra_execution_platforms <var>labels</var></code></h4> |
| <p> |
| The platforms that are available as execution platforms to run actions. |
| Platforms can be specified by exact target, or as a target pattern. These |
| platforms will be considered before those declared in the WORKSPACE file by |
| <a href="skylark/lib/globals.html#register_execution_platforms"> |
| register_execution_platforms()</a>. |
| </p> |
| |
| <h4 id="flag--extra_toolchains"><code class='flag'>--extra_toolchains <var>labels</var></code></h4> |
| <p> |
| The toolchain rules to be considered during toolchain resolution. Toolchains |
| can be specified by exact target, or as a target pattern. These toolchains will |
| be considered before those declared in the WORKSPACE file by |
| <a href="skylark/lib/globals.html#register_toolchains"> |
| register_toolchains()</a>. |
| </p> |
| |
| <h4 id="flag--toolchain_resolution_debug"><code class='flag'>--toolchain_resolution_debug=false</code></h4> |
| <p> |
| Print debug information while finding toolchains for a rule. This might help |
| developers of Bazel or Starlark rules with debugging failures due to missing |
| toolchains. |
| </p> |
| |
| <h3 id='misc_build_options'>Miscellaneous</h3> |
| |
| <h4 id='flag--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> |
| |
| <h4 id='flag--use_action_cache'><code class='flag'>--[no]use_action_cache</code></h4> |
| <p> |
| This option is enabled by default. If disabled, Bazel will not use its local action cache. |
| Disabling the local action cache saves memory and disk space for clean builds, but will make |
| incremental builds slower. |
| </p> |
| |
| <h4 id='flag--starlark_cpu_profile'><code class='flag'>--starlark_cpu_profile=<i>file</i></code></h4> |
| <p> |
| This flag, whose value is the name of a file, causes Bazel to gather |
| statistics about CPU usage by all Starlark threads, |
| and write the profile, in <a href='https://github.com/google/pprof'>pprof</a> format, |
| to the named file. |
| |
| Use this option to help identify Starlark functions that |
| make loading and analysis slow due to excessive computation. For example: |
| </p> |
| <pre> |
| $ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/... |
| $ pprof /tmp/pprof.gz |
| (pprof) top |
| Type: CPU |
| Time: Feb 6, 2020 at 12:06pm (PST) |
| Duration: 5.26s, Total samples = 3.34s (63.55%) |
| Showing nodes accounting for 3.34s, 100% of 3.34s total |
| flat flat% sum% cum cum% |
| 1.86s 55.69% 55.69% 1.86s 55.69% sort_source_files |
| 1.02s 30.54% 86.23% 1.02s 30.54% expand_all_combinations |
| 0.44s 13.17% 99.40% 0.44s 13.17% range |
| 0.02s 0.6% 100% 3.34s 100% sorted |
| 0 0% 100% 1.38s 41.32% my/project/main/BUILD |
| 0 0% 100% 1.96s 58.68% my/project/library.bzl |
| 0 0% 100% 3.34s 100% main |
| </pre> |
| <p> |
| For different views of the same data, try the <code>pprof</code> commands <code>svg</code>, |
| <code>web</code>, and <code>list</code>. |
| </p> |
| |
| <h2 id='bazel-releng'>Using Bazel for releases</h2> |
| <p> |
| Bazel is used both by software engineers during the development |
| cycle, and by release engineers when preparing binaries for deployment |
| to production. This section provides a list of tips for release |
| engineers using Bazel. |
| |
| </p> |
| |
| <h3>Significant options</h3> |
| |
| <p> |
| When using Bazel for release builds, the same issues arise as for |
| other scripts that perform a build, so you should read |
| the <a href='guide.html#scripting'>scripting</a> section of this manual. |
| In particular, the following options are strongly recommended: |
| </p> |
| <ul> |
| <li><a href='guide.html#bazelrc'><code class='flag'>--bazelrc=/dev/null</code></a></li> |
| <li><a href='#flag--keep_state_after_build'><code class='flag'>--nokeep_state_after_build</code></a></li> |
| </ul> |
| |
| <p> |
| These options are also important: |
| </p> |
| |
| <ul> |
| |
| <li><a href='#flag--package_path'><code class='flag'>--package_path</code></a></li> |
| <li><a href='#flag--symlink_prefix'><code class='flag'>--symlink_prefix</code></a>: |
| for managing builds for multiple configurations, |
| it may be convenient to distinguish each build |
| with a distinct identifier, e.g. "64bit" vs. "32bit". This option |
| differentiates the <code>bazel-bin</code> (etc.) symlinks. |
| </li> |
| </ul> |
| |
| <h2 id='test'>Running tests</h2> |
| <p> |
| To build and run tests with bazel, type <code>bazel test</code> followed by |
| the name of the test targets. |
| </p> |
| <p> |
| By default, this command performs simultaneous build and test |
| activity, building all specified targets (including any non-test |
| targets specified on the command line) and testing |
| <code>*_test</code> and <code>test_suite</code> targets as soon as |
| their prerequisites are built, meaning that test execution is |
| interleaved with building. Doing so usually results in significant |
| speed gains. |
| |
| </p> |
| |
| <h3>Options for <code>bazel test</code></h3> |
| |
| <h4 id="flag--cache_test_results"><code class='flag'>--cache_test_results=(yes|no|auto)</code> (<code>-t</code>)</h4> |
| <p> |
| If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the |
| following conditions applies: |
| </p> |
| <ul> |
| <li>Bazel detects changes in the test or its dependencies</li> |
| <li>the test is marked as <code>external</code></li> |
| <li>multiple test runs were requested with <code class='flag'>--runs_per_test</code></li> |
| <li>the test failed.</li> |
| </ul> |
| <p> |
| If 'no', all tests will be executed unconditionally. |
| </p> |
| <p> |
| If 'yes', the caching behavior will be the same as auto |
| except that it may cache test failures and test runs with |
| <code class='flag'>--runs_per_test</code>. |
| </p> |
| <p> |
| Note that test results are <em>always</em> saved in Bazel's output tree, |
| regardless of whether this option is enabled, so |
| you needn't have used <code class='flag'>--cache_test_results</code> on the |
| prior run(s) of <code>bazel test</code> in order to get cache hits. |
| The option only affects whether Bazel will <em>use</em> previously |
| saved results, not whether it will save results of the current run. |
| </p> |
| <p> |
| Users who have enabled this option by default in |
| their <code>.bazelrc</code> file may find the |
| abbreviations <code>-t</code> (on) or <code>-t-</code> (off) |
| convenient for overriding the default on a particular run. |
| </p> |
| |
| <h4 id="flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></h4> |
| <p> |
| This option tells Bazel not to run the tests, but to merely check and report |
| the cached test results. If there are any tests which have not been |
| previously built and run, or whose tests results are out-of-date (e.g. because |
| the source code or the build options have changed), then Bazel will report |
| an error message ("test result is not up-to-date"), will record the test's |
| status as "NO STATUS" (in red, if color output is enabled), and will return |
| a non-zero exit code. |
| </p> |
| <p> |
| This option also implies |
| <code><a href="#flag--check_up_to_date">--check_up_to_date</a></code> behavior. |
| </p> |
| <p> |
| This option may be useful for pre-submit checks. |
| </p> |
| |
| <h4 id="flag--test_verbose_timeout_warnings"><code class='flag'>--test_verbose_timeout_warnings</code></h4> |
| <p> |
| This option tells Bazel to explicitly warn the user if a test's timeout is |
| significantly longer than the test's actual execution time. While a test's |
| timeout should be set such that it is not flaky, a test that has a highly |
| over-generous timeout can hide real problems that crop up unexpectedly. |
| </p> |
| <p> |
| For instance, a test that normally executes in a minute or two should not have |
| a timeout of ETERNAL or LONG as these are much, much too generous. |
| |
| This option is useful to help users decide on a good timeout value or |
| sanity check existing timeout values. |
| </p> |
| <p> |
| Note that each test shard is allotted the timeout of the entire |
| <code>XX_test</code> target. Using this option does not affect a test's timeout |
| value, merely warns if Bazel thinks the timeout could be restricted further. |
| </p> |
| |
| <h4 id='flag--test_keep_going'><code class='flag'>--[no]test_keep_going</code></h4> |
| <p> |
| By default, all tests are run to completion. If this flag is disabled, |
| however, the build is aborted on any non-passing test. Subsequent build steps |
| and test invocations are not run, and in-flight invocations are canceled. |
| Do not specify both <code class='flag'>--notest_keep_going</code> and |
| <code class='flag'>--keep_going</code>. |
| </p> |
| |
| <h4 id='flag--flaky_test_attempts'><code class='flag'>--flaky_test_attempts <var>attempts</var></code></h4> |
| <p> |
| This option specifies the maximum number of times a test should be attempted |
| if it fails for any reason. A test that initially fails but eventually |
| succeeds is reported as <code>FLAKY</code> on the test summary. It is, |
| however, considered to be passed when it comes to identifying Bazel exit code |
| or total number of passed tests. Tests that fail all allowed attempts are |
| considered to be failed. |
| </p> |
| <p> |
| By default (when this option is not specified, or when it is set to |
| "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/strace |
| --run_under='/usr/bin/strace -c' |
| --run_under=/usr/bin/valgrind |
| --run_under='/usr/bin/valgrind --quiet --num-callers=20' |
| </pre> |
| |
| <h4>Test selection</h4> |
| <p> |
| As documented under <a href='#output-selection-options'>Output selection options</a>, |
| you can filter tests by <a href='#flag--test_size_filters'>size</a>, |
| <a href='#flag--test_timeout_filters'>timeout</a>, |
| <a href='#flag--test_tag_filters'>tag</a>, or |
| <a href='#flag--test_lang_filters'>language</a>. A convenience |
| <a href='#flag--test_filter'>general name filter</a> can forward particular |
| filter args to the test runner. |
| </p> |
| |
| <h4 id="other_options_for_bazel_test">Other options for <code>bazel test</code></h4> |
| <p> |
| The syntax and the remaining options are exactly like |
| <a href='guide.html#build'>bazel build</a>. |
| </p> |
| |
| |
| <h3 id='clean'>Cleaning build outputs</h3> |
| |
| <h4>The <code>clean</code> command</h4> |
| |
| <p> |
| Bazel has a <code>clean</code> command, analogous to that of Make. |
| It deletes the output directories for all build configurations performed |
| by this Bazel instance, or the entire working tree created by this |
| Bazel instance, and resets internal caches. If executed without any |
| command-line options, then the output directory for all configurations |
| will be cleaned. |
| </p> |
| |
| <p>Recall that each Bazel instance is associated with a single workspace, thus the |
| <code>clean</code> command will delete all outputs from all builds you've done |
| with that Bazel instance in that workspace. |
| </p> |
| <p> |
| To completely remove the entire working tree created by a Bazel |
| instance, you can specify the <code class='flag'>--expunge</code> option. When |
| executed with <code class='flag'>--expunge</code>, the clean command simply |
| removes the entire output base tree which, in addition to the build |
| output, contains all temp files created by Bazel. It also |
| stops the Bazel server after the clean, equivalent to the <a |
| href='#shutdown'><code>shutdown</code></a> command. For example, to |
| clean up all disk and memory traces of a Bazel instance, you could |
| specify: |
| </p> |
| <pre> |
| % bazel clean --expunge |
| </pre> |
| <p> |
| Alternatively, you can expunge in the background by using |
| <code class='flag'>--expunge_async</code>. It is safe to invoke a Bazel command |
| in the same client while the asynchronous expunge continues to run. |
| Note, however, that this may introduce IO contention. |
| </p> |
| |
| <p> |
| The <code>clean</code> command is provided primarily as a means of |
| reclaiming disk space for workspaces that are no longer needed. |
| However, we recognize that Bazel's incremental rebuilds might not be |
| perfect; <code>clean</code> may be used to recover a consistent |
| state when problems arise. |
| </p> |
| <p> |
| Bazel's design is such that these problems are fixable; we consider |
| such bugs a high priority, and will do our best fix them. If you |
| ever find an incorrect incremental build, please file a bug report. |
| We encourage developers to get out of the habit of |
| using <code>clean</code> and into that of reporting bugs in the |
| tools. |
| </p> |
| |
| |
| <h2 id='run'>Running executables</h2> |
| <p> |
| The <code>bazel run</code> command is similar to <code>bazel build</code>, except |
| it is used to build <em>and run</em> a single target. Here is a typical session: |
| </p> |
| <pre> |
| % bazel run -- java/myapp:myapp --arg1 --arg2 |
| Welcome to Bazel |
| INFO: Loading package: java/myapp |
| INFO: Loading package: foo/bar |
| INFO: Loading complete. Analyzing... |
| INFO: Found 1 target... |
| ... |
| Target //java/myapp:myapp up-to-date: |
| bazel-bin/java/myapp:myapp |
| INFO: Elapsed time: 0.638s, Critical Path: 0.34s |
| |
| INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2 |
| Hello there |
| $EXEC_ROOT/java/myapp/myapp |
| --arg1 |
| --arg2 |
| </pre> |
| |
| <p> |
| Note the use of the <code>--</code>. This is needed so that Bazel |
| does not interpret <code>--arg1</code> and <code>--arg2</code> as |
| Bazel options, but rather as part of the command line for running the binary. |
| (The program being run simply says hello and prints out its args.) |
| </p> |
| |
| <p><code>bazel run</code> is similar, but not identical, to directly invoking |
| the binary built by Bazel and its behavior is different depending on whether the |
| binary to be invoked is a test or not. |
| |
| When the binary is not a test, the current working directory will be the |
| runfiles tree of the binary. |
| |
| When the binary is a test, the current working directory will be the exec root |
| and a good-faith attempt is made to replicate the environment tests are usually |
| run in. The emulation is not perfect, though, and tests that have multiple |
| shards cannot be run this way (the |
| <code>--test_sharding_strategy=disabled</code> command line option can be used |
| to work around this) |
| |
| The following extra environment variables are also available to the binary: |
| <ul> |
| <li> |
| <code>BUILD_WORKSPACE_DIRECTORY</code>: the root of the workspace where the |
| build was run. |
| </li> |
| <li> |
| <code>BUILD_WORKING_DIRECTORY</code>: the current working directory where |
| Bazel was run from. |
| </li> |
| </ul> |
| |
| These can be used, for example, to interpret file names on the command line in |
| a user-friendly way. |
| |
| <h3>Options for <code>bazel run</code></h3> |
| |
| <h4 id='flag--run_under_run'><code class='flag'>--run_under=<var>command-prefix</var></code></h4> |
| <p> |
| This has the same effect as the <code class='flag'>--run_under</code> option for |
| <code>bazel test</code> (<a href='#flag--run_under'>see above</a>), |
| except that it applies to the command being run by <code>bazel |
| run</code> rather than to the tests being run by <code>bazel test</code> |
| and cannot run under label. |
| </p> |
| |
| <h3>Executing tests</h3> |
| |
| <p> |
| <code>bazel run</code> can also execute test binaries, which has the effect of |
| running the test in a close approximation of the environment described at |
| <a href='test-encyclopedia.html'>Writing Tests</a>. Note that none of the |
| <code>--test_*</code> arguments have an effect when running a test in this manner except |
| <code>--test_arg</code> . |
| </p> |
| |
| <h2 id='query'>Querying the dependency graph</h2> |
| |
| <p> |
| Bazel includes a query language for asking questions about the |
| dependency graph used during the build. The query language is used |
| by two commands: query and cquery. The major difference between the |
| two commands is that query runs after the <a href='guide.html#loading-phase'>loading phase</a> |
| and cquery runs after the <a href='guide.html#analysis-phase'>analysis phase</a>. These tools are an |
| invaluable aid to many software engineering tasks. |
| </p> |
| <p> |
| The query language is based on the idea of |
| algebraic operations over graphs; it is documented in detail in |
| |
| <a href="query.html">Bazel Query Reference</a>. |
| Please refer to that document for reference, for |
| examples, and for query-specific command-line options. |
| </p> |
| |
| <p> |
| The query tool accepts several command-line |
| option. <code class='flag'>--output</code> selects the output format. |
| <code class='flag'>--[no]keep_going</code> (disabled by default) causes the query |
| tool to continue to make progress upon errors; this behavior may be |
| disabled if an incomplete result is not acceptable in case of errors. |
| </p> |
| <p> |
| The <code class='flag'>--[no]tool_deps</code> option, |
| enabled by default, causes dependencies in non-target configurations to be included in the |
| dependency graph over which the query operates. |
| |
| </p> |
| <p> |
| The <code class='flag'>--[no]implicit_deps</code> option, enabled by default, causes |
| implicit dependencies to be included in the dependency graph over which the query operates. An |
| implicit dependency is one that is not explicitly specified in the BUILD file |
| but added by bazel. |
| </p> |
| <p> |
| Example: "Show the locations of the definitions (in BUILD files) of |
| all genrules required to build all the tests in the PEBL tree." |
| </p> |
| <pre> |
| bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))' |
| </pre> |
| |
| <h2 id='aquery'>Querying the action graph</h2> |
| |
| <b>Caution</b>: The aquery command is still experimental and its API will change. |
| |
| <p> |
| The <code>aquery</code> command allows you to query for actions in your build graph. |
| It operates on the post-analysis configured target graph and exposes |
| information about actions, artifacts and their relationships. |
| </p> |
| |
| <p> |
| The tool accepts several command-line options. |
| <code class='flag'>--output</code> selects the output format. The default output format |
| (<code>text</code>) is human-readable, use <code>proto</code> or <code>textproto</code> for |
| machine-readable format. |
| Notably, the aquery command runs on top of a regular Bazel build and inherits |
| the set of options available during a build. |
| </p> |
| |
| <p> |
| It supports the same set of functions that is also available to traditional |
| <code>query</code> but <code>siblings</code>, <code>buildfiles</code> and |
| <code>tests</code>. |
| </p> |
| |
| <p> |
| More details on aquery can be found <a href="aquery.html">here</a>. |
| </p> |
| |
| <h2 id='misc'>Miscellaneous commands and options</h2> |
| |
| <h3 id='help'><code>help</code></h3> |
| |
| <p> |
| The <code>help</code> command provides on-line help. By default, it |
| shows a summary of available commands and help topics, as shown in |
| the <a href='guide.html#overview'><i>Bazel overview</i></a> section above. |
| Specifying an argument displays detailed help for a particular |
| topic. Most topics are Bazel commands, e.g. <code>build</code> |
| or <code>query</code>, but there are some additional help topics |
| that do not correspond to commands. |
| </p> |
| |
| <h4 id='flag--long'><code class='flag'>--[no]long</code> (<code>-l</code>)</h4> |
| <p> |
| By default, <code>bazel help [<var>topic</var>]</code> prints only a |
| summary of the relevant options for a topic. If |
| the <code class='flag'>--long</code> option is specified, the type, default value |
| and full description of each option is also printed. |
| </p> |
| |
| <h3 id='shutdown'><code>shutdown</code></h3> |
| |
| <p> |
| Bazel server processes (see <a href='guide.html#client/server'>Client/server |
| implementation</a>) may be stopped by using the <code>shutdown</code> |
| command. This command causes the Bazel server to exit as soon as it |
| becomes idle (i.e. after the completion of any builds or other |
| commands that are currently in progress). |
| |
| Bazel servers stop themselves after an idle timeout, so this command |
| is rarely necessary; however, it can be useful in scripts when it is |
| known that no further builds will occur in a given workspace. |
| </p> |
| <p> |
| <code>shutdown</code> accepts one |
| option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which |
| requires an integer argument (in MB). If specified, this makes the shutdown |
| conditional on the amount of memory already consumed. This is |
| useful for scripts that initiate a lot of builds, as any memory |
| leaks in the Bazel server could cause it to crash spuriously on |
| occasion; performing a conditional restart preempts this condition. |
| </p> |
| |
| <h3 id='info'><code>info</code></h3> |
| |
| <p> |
| The <code>info</code> command prints various values associated with |
| the Bazel server instance, or with a specific build configuration. |
| (These may be used by scripts that drive a build.) |
| </p> |
| |
| <p> |
| The <code>info</code> command also permits a single (optional) |
| argument, which is the name of one of the keys in the list below. |
| In this case, <code>bazel info <var>key</var></code> will print only |
| the value for that one key. (This is especially convenient when |
| scripting Bazel, as it avoids the need to pipe the result |
| through <code>sed -ne /key:/s/key://p</code>: |
| </p> |
| |
| <h4>Configuration-independent data</h4> |
| <ul> |
| <li><code>release</code>: the release label for this Bazel |
| instance, or "development version" if this is not a released |
| binary. |
| </li> |
| <li><code>workspace</code> the absolute path to the base workspace |
| directory. |
| </li> |
| <li><code>install_base</code>: the absolute path to the installation |
| directory used by this Bazel instance for the current user. Bazel |
| installs its internally required executables below this directory. |
| |
| </li> |
| <li><code>output_base</code>: the absolute path to the base output |
| directory used by this Bazel instance for the current user and |
| workspace combination. Bazel puts all of its scratch and build |
| output below this directory. |
| </li> |
| <li><code>execution_root</code>: the absolute path to the execution |
| root directory under output_base. This directory is the root for all files |
| accessible to commands executed during the build, and is the working |
| directory for those commands. If the workspace directory is writable, a |
| symlink named |
| |
| <code>bazel-<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>server_log</code>: the absolute path to the Bazel server's debug log file. |
| This file contains debugging information for all commands over the lifetime of the |
| Bazel server, and is intended for human consumption by Bazel developers and power users. |
| </li> |
| <li><code>command_log</code>: the absolute path to the command log file; |
| this contains the interleaved stdout and stderr streams of the most recent |
| Bazel command. Note that running <code>bazel info</code> will overwrite the |
| contents of this file, since it then becomes the most recent Bazel command. |
| However, the location of the command log file will not change unless you |
| change the setting of the <code class='flag'>--output_base</code> or |
| <code class='flag'>--output_user_root</code> options. |
| </li> |
| |
| <li><code>used-heap-size</code>, |
| <code>committed-heap-size</code>, |
| <code>max-heap-size</code>: reports various JVM heap size |
| parameters. Respectively: memory currently used, memory currently |
| guaranteed to be available to the JVM from the system, maximum |
| possible allocation. |
| </li> |
| <li><code>gc-count</code>, <code>gc-time</code>: The cumulative count of |
| garbage collections since the start of this Bazel server and the time spent |
| to perform them. Note that these values are not reset at the start of every |
| build. |
| </li> |
| <li><code>package_path</code>: A colon-separated list of paths which would be |
| searched for packages by bazel. Has the same format as the |
| <code class='flag'>--package_path</code> build command line argument. |
| </li> |
| </ul> |
| <p> |
| Example: the process ID of the Bazel server. |
| </p> |
| <pre>% bazel info server_pid |
| 1285 |
| </pre> |
| |
| <h4>Configuration-specific data</h4> |
| <p> |
| These data may be affected by the configuration options passed |
| to <code>bazel info</code>, for |
| example <code class='flag'>--cpu</code>, <code class='flag'>--compilation_mode</code>, |
| etc. The <code>info</code> command accepts all |
| the <a href='#analysis-options'>options that control dependency |
| analysis</a>, since some of these determine the location of the |
| output directory of a build, the choice of compiler, etc. |
| </p> |
| <ul> |
| <li> |
| <code>bazel-bin</code>, <code>bazel-testlogs</code>, |
| <code>bazel-genfiles</code>: reports the absolute path to |
| the <code>bazel-*</code> directories in which programs generated by the |
| build are located. This is usually, though not always, the same as |
| the <code>bazel-*</code> symlinks created in the base workspace directory after a |
| successful build. However, if the workspace directory is read-only, |
| no <code>bazel-*</code> symlinks can be created. Scripts that use |
| the value reported by <code>bazel info</code>, instead of assuming the |
| existence of the symlink, will be more robust. |
| </li> |
| <li> |
| The complete |
| <a href='be/make-variables.html' |
| >"Make" environment</a>. If the <code class='flag'>--show_make_env</code> flag is |
| specified, all variables in the current configuration's "Make" environment |
| are also displayed (e.g. <code>CC</code>, <code>GLIBC_VERSION</code>, etc). |
| These are the variables accessed using the <code>$(CC)</code> |
| or <code>varref("CC")</code> syntax inside BUILD files. |
| </li> |
| </ul> |
| |
| <p> |
| Example: the C++ compiler for the current configuration. |
| This is the <code>$(CC)</code> variable in the "Make" environment, |
| so the <code class='flag'>--show_make_env</code> flag is needed. |
| </p> |
| |
| <pre> |
| % bazel info --show_make_env -c opt COMPILATION_MODE |
| opt |
| </pre> |
| |
| <p> |
| Example: the <code>bazel-bin</code> output directory for the current |
| configuration. This is guaranteed to be correct even in cases where |
| the <code>bazel-bin</code> symlink cannot be created for some reason |
| (e.g. you are building from a read-only directory). |
| </p> |
| |
| <pre>% bazel info --cpu=piii bazel-bin |
| /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin |
| % bazel info --cpu=k8 bazel-bin |
| /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin |
| </pre> |
| <h3 id='version'><code>version</code> and <code>--version</code></h3> |
| |
| <p> |
| The version command prints version details about the built Bazel |
| binary, including the changelist at which it was built and the date. |
| These are particularly useful in determining if you have the latest |
| Bazel, or if you are reporting bugs. Some of the interesting values |
| are: |
| </p> |
| <ul> |
| <li><code>changelist</code>: the changelist at which this version of |
| Bazel was released. |
| </li> |
| <li><code>label</code>: the release label for this Bazel |
| instance, or "development version" if this is not a released |
| binary. Very useful when reporting bugs. |
| </li> |
| </ul> |
| |
| <p> |
| <code>bazel --version</code>, with no other args, will emit the same output as |
| <code>bazel version --gnu_format</code>, except without the side-effect of potentially starting |
| a Bazel server or unpacking the server archive. <code>bazel --version</code> can be run from |
| anywhere - it does not require a workspace directory. |
| </p> |
| |
| <h3 id='mobile-install'><code>mobile-install</code></h3> |
| <p> |
| The <code>mobile-install</code> command installs apps to mobile devices. |
| Currently only Android devices running ART are supported. |
| |
| See <a href="mobile-install.html">bazel mobile-install</a> |
| for more information. |
| </p> |
| <p> |
| Note that this command does not install the same thing that |
| <code>bazel build</code> produces: Bazel tweaks the app so that it can be |
| built, installed and re-installed quickly. This should, however, be mostly |
| transparent to the app. |
| </p> |
| <p> |
| The following options are supported: |
| </p> |
| <h4 id='flag--incremental'><code class='flag'>--incremental</code></h4> |
| <p> |
| If set, Bazel tries to install the app incrementally, that is, only those |
| parts that have changed since the last build. This cannot update resources |
| referenced from <code>AndroidManifest.xml</code>, native code or Java |
| resources (i.e. ones referenced by <code>Class.getResource()</code>). If these |
| things change, this option must be omitted. Contrary to the spirit of Bazel |
| and due to limitations of the Android platform, it is the |
| <b>responsibility of the user</b> to know when this command is good enough and |
| when a full install is needed. |
| |
| If you are using a device with Marshmallow or later, consider the |
| <a href='#flag--split_apks'><code class='flag'>--split_apks</code></a> flag. |
| </p> |
| <h4 id='flag--split_apks'><code class='flag'>--split_apks</code></h4> |
| <p> |
| Whether to use split apks to install and update the application on the device. |
| Works only with devices with Marshmallow or later. Note that the |
| <a href='#flag--incremental'><code class='flag'>--incremental</code></a> flag |
| is not necessary when using <code class='flag'>--split_apks</code>. |
| </p> |
| <h4 id='flag--start_app'><code class='flag'>--start_app</code></h4> |
| <p> |
| Starts the app in a clean state after installing. Equivalent to |
| <code>--start=COLD</code>. |
| </p> |
| <h4 id='flag--debug_app'><code class='flag'>--debug_app</code></h4> |
| <p> |
| Waits for debugger to be attached before starting the app in a clean state after installing. |
| Equivalent to <code>--start=DEBUG</code>. |
| </p> |
| <h4 id='flag--start'><code class='flag'>--start=<i>start_type</i></code></h4> |
| <p> |
| How the app should be started after installing it. Supported <i>start_type</i>s are: |
| <ul> |
| <li><code>NO</code> Does not start the app. This is the default.</li> |
| <li><code>COLD</code> Starts the app from a clean state after install.</li> |
| <li><code>WARM</code> Preserves and restores the application state on incremental installs.</li> |
| <li><code>DEBUG</code> Waits for the debugger before starting the app in a clean state after install.</li> |
| </ul> |
| Note that if more than one of <code class='flag'>--start=<i>start_type</i></code>, |
| <code class='flag'>--start_app</code> or |
| <code class='flag'>--debug_app</code> is set, the last value will be used. |
| </p> |
| <h4 id='flag--adb'><code class='flag'>--adb <var>path</var></code></h4> |
| <p> |
| Indicates the <code>adb</code> binary to be used. |
| |
| The default is to use the adb in the Android SDK specified by |
| <a href='#flag--android_sdk'><code class='flag'>--android_sdk</code></a>. |
| |
| </p> |
| <h4 id='flag--adb_arg'><code class='flag'>--adb_arg <var>arg</var></code></h4> |
| <p> |
| Extra arguments to <code>adb</code>. These come before the subcommand in the |
| command line and are typically used to specify which device to install to. |
| For example, to select the Android device or emulator to use: |
| <pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef |
| </pre> |
| will invoke <code>adb</code> as |
| <pre> |
| adb -s deadbeef install ... |
| </pre> |
| </p> |
| <h4 id='flag--incremental_install_verbosity'><code class='flag'>--incremental_install_verbosity <var>number</var></code></h4> |
| <p> |
| The verbosity for incremental install. Set to 1 for debug logging to be |
| printed to the console. |
| </p> |
| |
| |
| <h3 id='dump'><code>dump</code></h3> |
| |
| <p> |
| The <code>dump</code> command prints to stdout a dump of the |
| internal state of the Bazel server. This command is intended |
| primarily for use by Bazel developers, so the output of this command |
| is not specified, and is subject to change. |
| </p> |
| |
| <p> |
| By default, command will just print help message outlining possible |
| options to dump specific areas of the Bazel state. In order to dump |
| internal state, at least one of the options must be specified. |
| </p> |
| <p> |
| Following options are supported: |
| </p> |
| <ul> |
| <li><code class='flag'>--action_cache</code> dumps action cache content.</li> |
| <li><code class='flag'>--packages</code> dumps package cache content.</li> |
| <li><code class='flag'>--skyframe</code> dumps state of internal Bazel dependency graph.</li> |
| <li><code class='flag'>--rules</code> dumps rule summary for each rule and aspect class, |
| including counts and action counts. This includes both native and Starlark rules. |
| If memory tracking is enabled, then the rules' memory consumption is also printed.</li> |
| <li><code class='flag'>--skylark_memory</code> dumps a |
| <href a=https://github.com/google/pprof>pprof</href> compatible .gz file to the specified path. |
| You must enable memory tracking for this to work.</li> |
| <li><code class='flag'>--action_graph=/path/to/file</code> dumps the state of |
| the internal Bazel action graph in proto format to |
| <code>/path/to/file</code>. You have to run (at least) the analysis phase |
| for the targets you are interested in (for example, <code>bazel build --nobuild |
| //foo:bar</code>). Note that this feature is still experimental, subject to |
| change and will probably be integrated into <code>cquery</code> in the |
| future. |
| <li><code class='flag'>--action_graph:targets=target1,target2,...</code> |
| filters the actions to the comma-separated list of targets when dumping the |
| action graph.</li> |
| <li><code class='flag'>--action_graph:include_cmdline</code> Include the command lines of actions |
| in the action graph dump.</li> |
| </ul> |
| |
| <h4 id='memory-tracking'>Memory tracking</h4> |
| <p> |
| Some <code>dump</code> commands require memory tracking. To turn this on, you have to pass |
| startup flags to Bazel: |
| </p> |
| <ul> |
| <li><code>--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar</code></li> |
| <li><code>--host_jvm_args=-DRULE_MEMORY_TRACKER=1</code></li> |
| </ul> |
| <p> |
| The java-agent is checked into bazel at |
| third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar, so make |
| sure you adjust <code>$BAZEL</code> for where you keep your bazel repository. |
| |
| Do not forget to keep passing these options to Bazel for every command or the server will |
| restart. |
| </p> |
| <p>Example:</p> |
| <pre> |
| % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \ |
| --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ |
| build --nobuild <targets> |
| |
| # Dump rules |
| % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \ |
| --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ |
| dump --rules |
| |
| # Dump Starlark heap and analyze it with pprof |
| % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \ |
| --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ |
| dump --skylark_memory=$HOME/prof.gz |
| % pprof -flame $HOME/prof.gz |
| </pre> |
| <h3 id='analyze-profile'><code>analyze-profile</code></h3> |
| |
| <p> |
| The <code>analyze-profile</code> command analyzes data previously gathered |
| during the build using <code class='flag'>--profile</code> option. It provides several |
| options to either perform analysis of the build execution or export data in |
| the specified format. |
| |
| </p> |
| <p> |
| The following options are supported: |
| </p> |
| <ul> |
| <li><code id='flag--dump'>--dump=text</code> displays all gathered data in a |
| <a href='guide.html#dump-text-format'>human-readable format</a></li> |
| <li><code>--dump=raw</code> displays all gathered data in a |
| <a href='guide.html#dump-raw-format'>script-friendly format</a></li> |
| <li><code id='flag--html'>--html</code> generates an <a href='guide.html#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 Starlark |
| 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 threshold, in milliseconds. Default is 50ms</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p> |
| See the section on <a href='guide.html#profiling'>Troubleshooting performance by profiling</a> for |
| format details and usage help. |
| |
| </p> |
| |
| <h3 id='canonicalize'><code>canonicalize-flags</code></h3> |
| |
| <p> |
| The <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'>Startup options</h3> |
| |
| <p> |
| The options described in this section affect the startup of the Java |
| virtual machine used by Bazel server process, and they apply to all |
| subsequent commands handled by that server. If there is an already |
| running Bazel server and the startup options do not match, it will |
| be restarted. |
| </p> |
| <p> |
| All of the options described in this section must be specified using the |
| <code class='flag'>--key=value</code> or <code class='flag'>--key value</code> |
| syntax. Also, these options must appear <i>before</i> the name of the Bazel |
| command. |
| </p> |
| |
| <h4 id='flag--output_base'><code class='flag'>--output_base=<var>dir</var></code></h4> |
| <p> |
| This option requires a path argument, which must specify a |
| writable directory. Bazel will use this location to write all its |
| output. The output base is also the key by which the client locates |
| the Bazel server. By changing the output base, you change the server |
| which will handle the command. |
| </p> |
| <p> |
| By default, the output base is derived from the user's login name, |
| and the name of the workspace directory (actually, its MD5 digest), |
| so a typical value looks like: |
| |
| <code>/var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e</code>. |
| Note that the client uses the output base to find the Bazel server |
| instance, so if you specify a different output base in a Bazel |
| command, a different server will be found (or started) to handle the |
| request. It's possible to perform two concurrent builds in the same |
| workspace directory by varying the output base. |
| </p> |
| |
| <p>For example:</p> |
| <pre><code> |
| OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base |
| % bazel --output_base $OUTPUT_BASE build //foo & bazel --output_base $OUTPUT_BASE build //bar |
| </code></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> |
| Points to the root directory where output bases are created unless |
| overriden with <code class='flag'>--output_base</code>. The directory |
| must either not exist or be owned by the calling user. In the past, |
| this was allowed to point to a directory shared among various users |
| but it's not allowed any longer. (We can reconsider allowing this once |
| <a href='https://github.com/bazelbuild/bazel/issues/11100'>#11100</a> |
| is addressed.) |
| </p> |
| <p> |
| If the <code class='flag'>--output_base</code> option is specified, it overrides |
| using <code class='flag'>--output_user_root</code> to calculate the output base. |
| </p> |
| <p> |
| The install base location is also calculated based on |
| <code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded |
| binaries. |
| </p> |
| <p> |
| You can also use the <code class='flag'>--output_user_root</code> option to choose an |
| alternate base location for all of Bazel's output (install base and output |
| base) if there is a better location in your filesystem layout. |
| </p> |
| |
| <a name="startup_flag--host_javabase"></a> |
| <h4 id='startup_flag--server_javabase'><code class='flag'>--server_javabase=<var>dir</var></code></h4> |
| <p> |
| Specifies the Java virtual machine in which <i>Bazel itself</i> runs. The value must be a path to |
| the directory containing a JDK or JRE. It should not be a label. |
| This option should appear before any Bazel command, for example: |
| </p> |
| <pre> |
| % bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo |
| </pre> |
| <p> |
| This flag does <i>not</i> affect the JVMs used by Bazel subprocesses such as applications, tests, |
| tools, and so on. Use build options <a href='#flag--javabase'>--javabase</a> or |
| <a href='#flag--host_javabase'>--host_javabase</a> instead. |
| </p> |
| <p> |
| This flag was previously named <code>--host_javabase</code> (sometimes referred to as the |
| 'left-hand side' <code>--host_javabase</code>), but was renamed to avoid confusion with the |
| build flag <a href='#flag--host_javabase'>--host_javabase</a> (sometimes referred to as the |
| 'right-hand side' <code>--host_javabase</code>). |
| </p> |
| |
| <h4 id='flag--host_jvm_args'><code class='flag'>--host_jvm_args=<var>string</var></code></h4> |
| <p> |
| Specifies a startup option to be passed to the Java virtual machine in which <i>Bazel itself</i> |
| runs. This can be used to set the stack size, for example: |
| </p> |
| <pre> |
| % bazel --host_jvm_args="-Xss256K" build //foo |
| </pre> |
| <p> |
| This option can be used multiple times with individual arguments. Note that |
| setting this flag should rarely be needed. You can also pass a space-separated list of strings, |
| each of which will be interpreted as a separate JVM argument, but this feature will soon be |
| deprecated. |
| |
| </p> |
| <p> |
| That this does <i>not</i> affect any JVMs used by |
| subprocesses of Bazel: applications, tests, tools, and so on. To pass |
| JVM options to executable Java programs, whether run by <code>bazel |
| run</code> or on the command-line, you should use |
| the <code>--jvm_flags</code> argument which |
| all <code>java_binary</code> and <code>java_test</code> programs |
| support. Alternatively for tests, use <code>bazel |
| test --test_arg=--jvm_flags=foo ...</code>. |
| </p> |
| |
| <h4 id='flag--host_jvm_debug'><code class='flag'>--host_jvm_debug</code></h4> |
| <p> |
| This option causes the Java virtual machine to wait for a connection |
| from a JDWP-compliant debugger before |
| calling the main method of <i>Bazel itself</i>. This is primarily |
| intended for use by Bazel developers. |
| </p> |
| <p> |
| (Please note that this does <i>not</i> affect any JVMs used by |
| subprocesses of Bazel: applications, tests, tools, etc.) |
| </p> |
| |
| <h4 id='flag--batch'><code class='flag'>--batch</code></h4> |
| |
| <p> |
| Batch mode causes Bazel to not use the standard client/server mode described |
| <a href='guide.html#client/server'>above</a>, instead running a bazel java process for a |
| single command, which has been used for more predictable semantics with respect |
| to signal handling, job control, and environment variable inheritance, and is |
| necessary for running bazel in a chroot jail. |
| </p> |
| |
| <p> |
| Batch mode retains proper queueing semantics within the same output_base. |
| That is, simultaneous invocations will be processed in order, without overlap. |
| If a batch mode Bazel is run on a client with a running server, it first |
| kills the server before processing the command. |
| </p> |
| |
| <p> |
| Bazel will run slower in batch mode, or with the alternatives described above. |
| This is because, among other things, the build file cache is memory-resident, so it is not |
| preserved between sequential batch invocations. |
| Therefore, using batch mode often makes more sense in cases where performance |
| is less critical, such as continuous builds. |
| </p> |
| |
| <p> |
| <i>WARNING:</i> <code class='flag'>--batch</code> is sufficiently slower than standard |
| client/server mode. Additionally it might not support all of the features and optimizations which |
| are made possible by a persistent Bazel server. If you're using <code class='flag'>--batch</code> |
| for the purpose of build isolation, we recommend using the command option |
| <code class='flag'>--nokeep_state_after_build</code>, which guarantees that no incremental |
| in-memory state is kept between builds. In order to restart the Bazel server and JVM after a |
| build, please explicitly do so using the "shutdown" command. |
| </p> |
| |
| |
| <h4 id='flag--max_idle_secs'><code class='flag'>--max_idle_secs <var>n</var></code></h4> |
| <p> |
| This option specifies how long, in seconds, the Bazel server process |
| should wait after the last client request, before it exits. The |
| default value is 10800 (3 hours). <code class='flag'>--max_idle_secs=0</code> will cause the |
| Bazel server process to persist indefinitely. |
| </p> |
| <p> |
| This option may be used by scripts that invoke Bazel to ensure that |
| they do not leave Bazel server processes on a user's machine when they |
| would not be running otherwise. |
| For example, a presubmit script might wish to |
| invoke <code>bazel query</code> to ensure that a user's pending |
| change does not introduce unwanted dependencies. However, if the |
| user has not done a recent build in that workspace, it would be |
| undesirable for the presubmit script to start a Bazel server just |
| for it to remain idle for the rest of the day. |
| By specifying a small value of <code class='flag'>--max_idle_secs</code> in the |
| query request, the script can ensure that <i>if</i> it caused a new |
| server to start, that server will exit promptly, but if instead |
| there was already a server running, that server will continue to run |
| until it has been idle for the usual time. Of course, the existing |
| server's idle timer will be reset. |
| </p> |
| <h4 id='flag--shutdown_on_low_sys_mem'><code class='flag'>--[no]shutdown_on_low_sys_mem</code></h4> |
| <p> |
| If enabled and <code class='flag'>--max_idle_secs</code> is set to a positive duration, |
| after the build server has been idle for a while, shut down the server when the system is |
| low on memory. Linux only. |
| </p> |
| <p> |
| In addition to running an idle check corresponding to max_idle_secs, the build server will |
| starts monitoring available system memory after the server has been idle for some time. |
| If the available system memory becomes critically low, the server will exit. |
| </p> |
| |
| <h4 id='flag--block_for_lock'><code class='flag'>--[no]block_for_lock</code></h4> |
| <p> |
| If enabled, Bazel will wait for other Bazel commands holding the |
| server lock to complete before progressing. If disabled, Bazel will |
| exit in error if it cannot immediately acquire the lock and |
| proceed. |
| |
| Developers might use this in presubmit checks to avoid long waits caused |
| by another Bazel command in the same client. |
| </p> |
| |
| <h4 id='flag--io_nice_level'><code class='flag'>--io_nice_level <var>n</var></code></h4> |
| <p> |
| Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority, |
| 7 is lowest. The anticipatory scheduler may only honor up to priority 4. |
| Negative values are ignored. |
| </p> |
| |
| <h4 id='flag--batch_cpu_scheduling'><code class='flag'>--batch_cpu_scheduling</code></h4> |
| <p> |
| Use <code>batch</code> CPU scheduling for Bazel. This policy is useful for |
| workloads that are non-interactive, but do not want to lower their nice value. |
| See 'man 2 sched_setscheduler'. This policy may provide for better system |
| interactivity at the expense of Bazel throughput. |
| </p> |
| |
| <h3 id='misc_options'>Miscellaneous options</h3> |
| |
| <h4 id='flag--announce_rc'><code class='flag'>--[no]announce_rc</code></h4> |
| <p> |
| Controls whether Bazel announces command options read from the bazelrc file when |
| starting up. (Startup options are unconditionally announced.) |
| </p> |
| |
| <h4 id='flag--color'><code class='flag'>--color (yes|no|auto)</code></h4> |
| <p> |
| This option determines whether Bazel will use colors to highlight |
| its output on the screen. |
| </p> |
| <p> |
| If this option is set to <code>yes</code>, color output is enabled. |
| If this option is set to <code>auto</code>, Bazel will use color output only if |
| the output is being sent to a terminal and the TERM environment variable |
| is set to a value other than <code>dumb</code>, <code>emacs</code>, or <code>xterm-mono</code>. |
| If this option is set to <code>no</code>, color output is disabled, |
| regardless of whether the output is going to a terminal and regardless |
| of the setting of the TERM environment variable. |
| </p> |
| |
| <h4 id='flag--config'><code class='flag'>--config <var>name</var></code></h4> |
| <p> |
| Selects additional config section from the rc files; for the current |
| <code>command</code>, it also pulls in the options from |
| <code>command:name</code> if such a section exists. Can be specified multiple |
| times to add flags from several config sections. Expansions can refer to other |
| definitions (i.e. expansions can be chained). |
| </p> |
| |
| <h4 id='flag--curses'><code class='flag'>--curses (yes|no|auto)</code></h4> |
| <p> |
| This option determines whether Bazel will use cursor controls |
| in its screen output. This results in less scrolling data, and a more |
| compact, easy-to-read stream of output from Bazel. This works well with |
| <code class='flag'>--color</code>. |
| </p> |
| <p> |
| If this option is set to <code>yes</code>, use of cursor controls is enabled. |
| If this option is set to <code>no</code>, use of cursor controls is disabled. |
| If this option is set to <code>auto</code>, use of cursor controls will be |
| enabled under the same conditions as for <code class='flag'>--color=auto</code>. |
| </p> |
| |
| <h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4> |
| <p> |
| If specified, a timestamp is added to each message generated by |
| Bazel specifying the time at which the message was displayed. |
| </p> |