blob: a23aa5821719ca4d90cd3460c074bf448264eb8b [file] [log] [blame]
David Chen8fe82a32016-08-24 10:55:41 +00001---
2layout: documentation
Greg Estrenc0816752020-02-20 13:04:29 -08003title: User manual
David Chen8fe82a32016-08-24 10:55:41 +00004---
Googler9e7ae8d2021-01-08 19:01:23 -08005<h1>Commands and Options</h1>
David Chen8fe82a32016-08-24 10:55:41 +00006
Googler630941e2020-12-23 17:13:31 -08007This page covers the options that are available with various Bazel commands,
daroberts065423f2021-03-02 19:52:50 -08008such as <code>bazel build</code>, <code>bazel run</code>, and
9<code>bazel test</code>. This page is a companion to the
10<a href="https://docs.bazel.build/versions/master/guide.html">Bazel user guide</a>,
Googler630941e2020-12-23 17:13:31 -080011which lists Bazel's commands.
Greg Estrenc0816752020-02-20 13:04:29 -080012<h2 id='target-patterns'>Target syntax</h2>
laurentlbadf36072018-11-05 16:20:20 -080013
14Some commands, like <code>build</code> or <code>test</code>, can operate
15on a list of targets. They use a syntax more flexible than labels, which is
Googlerbb6ecd72020-05-28 12:52:28 -070016documented in the "<a href="guide.html#specifying-targets-to-build">Specifying
laurentlbadf36072018-11-05 16:20:20 -080017targets to build</a>" section of the User's Guide.
18
David Chen8fe82a32016-08-24 10:55:41 +000019<h2>Options</h2>
20
21<p>
22 The following sections describe the options available during a
Googler0e692fb2021-01-22 18:38:24 +010023 build. When <code class='flag'>--long</code> is used on a help command, the on-line
David Chen8fe82a32016-08-24 10:55:41 +000024 help messages provide summary information about the meaning, type and
25 default value for each option.
26</p>
27
28<p>
29 Most options can only be specified once. When specified multiple times, the
30 last instance wins. Options that can be specified multiple times are
31 identified in the on-line help with the text 'may be used multiple times'.
32</p>
33
brandjoncf0390b2020-02-20 10:37:40 -080034<h3>Package location</h3>
David Chen8fe82a32016-08-24 10:55:41 +000035
David Chen8fe82a32016-08-24 10:55:41 +000036<h4 id='flag--package_path'><code class='flag'>--package_path</code></h4>
37<p>
38 This option specifies the set of directories that are searched to
39 find the BUILD file for a given package.
David Chen8fe82a32016-08-24 10:55:41 +000040</p>
41
David Chen8fe82a32016-08-24 10:55:41 +000042<p>
Googler0e692fb2021-01-22 18:38:24 +010043 Bazel finds its packages by searching the package path. This is a colon
laurentlb15918182018-10-17 11:44:25 -070044 separated ordered list of bazel directories, each being the root of a
45 partial source tree.
David Chen8fe82a32016-08-24 10:55:41 +000046</p>
47
laurentlb15918182018-10-17 11:44:25 -070048<p>
49 <i>To specify a custom package path</i> using the
50 <code class='flag'>--package_path</code> option:
51</p>
52<pre>
53 % bazel build --package_path %workspace%:/some/other/root
54</pre>
55<p>
56Package path elements may be specified in three formats:
57</p>
58<ol>
59 <li>
60 If the first character is <code>/</code>, the path is absolute.
61 </li>
62 <li>
63 If the path starts with <code>%workspace%</code>, the path is taken relative
64 to the nearest enclosing bazel directory.<br>
65 For instance, if your working directory
66 is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the
67 string <code>%workspace%</code> in the package-path is expanded
68 to <code>/home/bob/clients/bob_client/bazel</code>.
69 </li>
70 <li>
71 Anything else is taken relative to the working directory.<br> This is usually not what you mean to do,
72 and may behave unexpectedly if you use Bazel from directories below the bazel workspace.
73 For instance, if you use the package-path element <code>.</code>,
74 and then cd into the directory
75 <code>/home/bob/clients/bob_client/bazel/foo</code>, packages
76 will be resolved from the
77 <code>/home/bob/clients/bob_client/bazel/foo</code> directory.
78 </li>
79</ol>
80<p>
Googler03fd5412021-03-11 18:57:14 -080081 If you use a non-default package path, specify it in your
82 <a href='guide.html#bazelrc'>Bazel configuration file</a> for
laurentlb15918182018-10-17 11:44:25 -070083 convenience.
84</p>
85<p>
86 <i>Bazel doesn't require any packages to be in the
87 current directory</i>, so you can do a build from an empty bazel
88 workspace if all the necessary packages can be found somewhere else
89 on the package path.
90</p>
91<p>
92 <i>Example</i>: Building from an empty client
93</p>
94<pre>
95 % mkdir -p foo/bazel
96 % cd foo/bazel
97 % touch WORKSPACE
98 % bazel build --package_path /some/other/path //foo
99</pre>
brandjoncf0390b2020-02-20 10:37:40 -0800100<h3 id='checking-options'>Error checking</h3>
David Chen8fe82a32016-08-24 10:55:41 +0000101<p>
102 These options control Bazel's error-checking and/or warnings.
103</p>
104
David Chen8fe82a32016-08-24 10:55:41 +0000105<h4 id='flag--check_visibility'><code class='flag'>--[no]check_visibility</code></h4>
106<p>
107 If this option is set to false, visibility checks are demoted to warnings.
108 The default value of this option is true, so that by default, visibility
109 checking is done.
110
111</p>
ranjanih6a1a09f2021-03-10 15:39:14 -0800112<h4 id='flag--output_filter'><code class='flag'>--output_filter=<var>regex</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000113<p>
114 The <code class='flag'>--output_filter</code> option will only show build and compilation
115 warnings for targets that match the regular expression. If a target does not
116 match the given regular expression and its execution succeeds, its standard
ulfjack171314b2017-06-02 09:09:43 +0200117 output and standard error are thrown away.
118</p>
119<p>
120 Here are some typical values for this option:
David Chen8fe82a32016-08-24 10:55:41 +0000121</p>
122<table>
123 <tr>
David Chen8fe82a32016-08-24 10:55:41 +0000124 <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td>
125 <td>Show the output for the specified packages.</td>
126 </tr>
127 <tr>
128 <td><code class='flag'>--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'</code></td>
129 <td>Don't show output for the specified packages.</td>
130 </tr>
131 <tr>
ulfjack171314b2017-06-02 09:09:43 +0200132 <td><code class='flag'>--output_filter=</code></td>
Googler4da2f162017-07-17 21:36:56 +0200133 <td>Show everything.
ulfjack171314b2017-06-02 09:09:43 +0200134 </td>
135 </tr>
136 <tr>
David Chen8fe82a32016-08-24 10:55:41 +0000137 <td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td>
ulfjack171314b2017-06-02 09:09:43 +0200138 <td>Show nothing.
139 </td>
David Chen8fe82a32016-08-24 10:55:41 +0000140 </tr>
141</table>
142
brandjoncf0390b2020-02-20 10:37:40 -0800143<h3 id='flags-options'>Tool flags</h3>
David Chen8fe82a32016-08-24 10:55:41 +0000144<p>
145 These options control which options Bazel will pass to other tools.
146</p>
147
ranjanih6a1a09f2021-03-10 15:39:14 -0800148<h4 id='flag--copt'><code class='flag'>--copt=<var>cc-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000149<p>
Googler9cfa4cb2018-06-04 22:19:11 -0700150 This option takes an argument which is to be passed to the compiler.
151 The argument will be passed to the compiler whenever it is invoked
David Chen8fe82a32016-08-24 10:55:41 +0000152 for preprocessing, compiling, and/or assembling C, C++, or
Googler0e692fb2021-01-22 18:38:24 +0100153 assembler code. It will not be passed when linking.
David Chen8fe82a32016-08-24 10:55:41 +0000154</p>
155<p>
156 This option can be used multiple times.
157 For example:
158</p>
159<pre>
160 % bazel build --copt="-g0" --copt="-fpic" //foo
161</pre>
162<p>
163 will compile the <code>foo</code> library without debug tables, generating
164 position-independent code.
165</p>
166<p>
167 Note that changing <code class='flag'>--copt</code> settings will force a recompilation
168 of all affected object files. Also note that copts values listed in specific
Googler9cfa4cb2018-06-04 22:19:11 -0700169 cc_library or cc_binary build rules will be placed on the compiler command line
David Chen8fe82a32016-08-24 10:55:41 +0000170 <em>after</em> these options.
171</p>
172<p>
173 Warning: C++-specific options (such as <code>-fno-implicit-templates</code>)
174 should be specified in <code class='flag'>--cxxopt</code>, not in
Googler0e692fb2021-01-22 18:38:24 +0100175 <code class='flag'>--copt</code>. Likewise, C-specific options (such as -Wstrict-prototypes)
David Chen8fe82a32016-08-24 10:55:41 +0000176 should be specified in <code class='flag'>--conlyopt</code>, not in <code>copt</code>.
Googler9cfa4cb2018-06-04 22:19:11 -0700177 Similarly, compiler options that only have an
David Chen8fe82a32016-08-24 10:55:41 +0000178 effect at link time (such as <code>-l</code>) should be specified in
179 <code class='flag'>--linkopt</code>, not in <code class='flag'>--copt</code>.
180</p>
181
ranjanih6a1a09f2021-03-10 15:39:14 -0800182<h4 id='flag--host_copt'><code class='flag'>--host_copt=<var>cc-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000183<p>
Googler9cfa4cb2018-06-04 22:19:11 -0700184 This option takes an argument which is to be passed to the compiler for source files
David Chen8fe82a32016-08-24 10:55:41 +0000185 that are compiled in the host configuration. This is analogous to
186 the <a href='#flag--copt'><code class='flag'>--copt</code></a> option, but applies only to the
187 host configuration.
188</p>
189
April Schleckc1ffe372021-04-01 12:12:35 -0700190<h4 id='flag--host_conlyopt'><code class='flag'>--host_conlyopt=<var>cc-option</var></code></h4>
191<p>
192 This option takes an argument which is to be passed to the compiler for C source files
193 that are compiled in the host configuration. This is analogous to
194 the <a href='#flag--conlyopt'><code class='flag'>--conlyopt</code></a> option, but applies only
195 to the host configuration.
196</p>
197
ranjanih6a1a09f2021-03-10 15:39:14 -0800198<h4 id='flag--host_cxxopt'><code class='flag'>--host_cxxopt=<var>cc-option</var></code></h4>
Marcel Hlopko4c1b1fd2017-02-24 12:54:17 +0000199<p>
Googler9cfa4cb2018-06-04 22:19:11 -0700200 This option takes an argument which is to be passed to the compiler for C++ source files
Marcel Hlopko4c1b1fd2017-02-24 12:54:17 +0000201 that are compiled in the host configuration. This is analogous to
202 the <a href='#flag--cxxopt'><code class='flag'>--cxxopt</code></a> option, but applies only to the
203 host configuration.
204</p>
205
April Schleckc1ffe372021-04-01 12:12:35 -0700206<h4 id='flag--host_linkopt'><code class='flag'>--host_linkopt=<var>linker-option</var></code></h4>
207<p>
208 This option takes an argument which is to be passed to the linker for source files
209 that are compiled in the host configuration. This is analogous to
210 the <a href='#flag--linkopt'><code class='flag'>--linkopt</code></a> option, but applies only to
211 the host configuration.
212</p>
213
ranjanih6a1a09f2021-03-10 15:39:14 -0800214<h4 id='flag--conlyopt'><code class='flag'>--conlyopt=<var>cc-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000215<p>
Googler9cfa4cb2018-06-04 22:19:11 -0700216 This option takes an argument which is to be passed to the compiler when compiling C source files.
David Chen8fe82a32016-08-24 10:55:41 +0000217</p>
218<p>
219 This is similar to <code class='flag'>--copt</code>, but only applies to C compilation,
Googler0e692fb2021-01-22 18:38:24 +0100220 not to C++ compilation or linking. So you can pass C-specific options
David Chen8fe82a32016-08-24 10:55:41 +0000221 (such as <code>-Wno-pointer-sign</code>) using <code class='flag'>--conlyopt</code>.
222</p>
223<p>
224 Note that copts parameters listed in specific cc_library or cc_binary build rules
Googler9cfa4cb2018-06-04 22:19:11 -0700225 will be placed on the compiler command line <em>after</em> these options.
David Chen8fe82a32016-08-24 10:55:41 +0000226</p>
227
ranjanih6a1a09f2021-03-10 15:39:14 -0800228<h4 id='flag--cxxopt'><code class='flag'>--cxxopt=<var>cc-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000229<p>
Googler9cfa4cb2018-06-04 22:19:11 -0700230 This option takes an argument which is to be passed to the compiler when compiling C++ source
231 files.
David Chen8fe82a32016-08-24 10:55:41 +0000232</p>
233<p>
234 This is similar to <code class='flag'>--copt</code>, but only applies to C++ compilation,
Googler0e692fb2021-01-22 18:38:24 +0100235 not to C compilation or linking. So you can pass C++-specific options
David Chen8fe82a32016-08-24 10:55:41 +0000236 (such as <code>-fpermissive</code> or <code>-fno-implicit-templates</code>) using <code class='flag'>--cxxopt</code>.
237 For example:
238</p>
239<pre>
240 % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code
241</pre>
242<p>
243 Note that copts parameters listed in specific cc_library or cc_binary build rules
Googler9cfa4cb2018-06-04 22:19:11 -0700244 will be placed on the compiler command line <em>after</em> these options.
David Chen8fe82a32016-08-24 10:55:41 +0000245</p>
246
ranjanih6a1a09f2021-03-10 15:39:14 -0800247<h4 id='flag--linkopt'><code class='flag'>--linkopt=<var>linker-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000248<p>
Googler9cfa4cb2018-06-04 22:19:11 -0700249 This option takes an argument which is to be passed to the compiler when linking.
David Chen8fe82a32016-08-24 10:55:41 +0000250</p>
251<p>
252 This is similar to <code class='flag'>--copt</code>, but only applies to linking,
Googler0e692fb2021-01-22 18:38:24 +0100253 not to compilation. So you can pass compiler options that only make sense
David Chen8fe82a32016-08-24 10:55:41 +0000254 at link time (such as <code>-lssp</code> or <code>-Wl,--wrap,abort</code>)
Googler0e692fb2021-01-22 18:38:24 +0100255 using <code class='flag'>--linkopt</code>. For example:
David Chen8fe82a32016-08-24 10:55:41 +0000256</p>
257<pre>
258 % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code
259</pre>
260<p>
261 Build rules can also specify link options in their attributes. This option's
262 settings always take precedence. Also see
263 <a href="be/c-cpp.html#cc_library.linkopts">cc_library.linkopts</a>.
264</p>
265
266<h4 id='flag--strip'><code class='flag'>--strip (always|never|sometimes)</code></h4>
267<p>
268 This option determines whether Bazel will strip debugging information from
269 all binaries and shared libraries, by invoking the linker with the <code>-Wl,--strip-debug</code> option.
270 <code class='flag'>--strip=always</code> means always strip debugging information.
271 <code class='flag'>--strip=never</code> means never strip debugging information.
Googler77e5b922019-10-23 12:09:20 -0700272 The default value of <code class='flag'>--strip=sometimes</code> means strip if the <code class='flag'>--compilation_mode</code>
David Chen8fe82a32016-08-24 10:55:41 +0000273 is <code>fastbuild</code>.
274</p>
275<pre>
276 % bazel build --strip=always //foo:bar
277</pre>
278<p>
279 will compile the target while stripping debugging information from all generated
280 binaries.
281</p>
282<p>
283 Note that if you want debugging information, it's not enough to disable stripping; you also need to make
284 sure that the debugging information was generated by the compiler, which you can do by using either
285 <code>-c dbg</code> or <code class='flag'>--copt -g</code>.
286</p>
287<p>
288 Note also that Bazel's <code class='flag'>--strip</code> option corresponds with ld's <code>--strip-debug</code> option:
Googler0e692fb2021-01-22 18:38:24 +0100289 it only strips debugging information. If for some reason you want to strip <em>all</em> symbols,
David Chen8fe82a32016-08-24 10:55:41 +0000290 not just <em>debug</em> symbols, you would need to use ld's <code>--strip-all</code> option,
Googler87598722020-06-10 08:54:40 -0700291 which you can do by passing <code class='flag'>--linkopt=-Wl,--strip-all</code> to Bazel. Also be
292 aware that setting Bazel's <code class='flag'>--strip</code> flag will override
293 <code class='flag'>--linkopt=-Wl,--strip-all</code>, so you should only set one or the other.
Googler11b73bf2021-04-30 14:15:36 -0700294
295 If you are only building a single binary and want all symbols stripped, you could also
296 pass <code class='flag'>--stripopt=--strip-all</code> and explicitly build the
297 <code>//foo:bar.stripped</code> version of the target. As described in the section on
298 <code class='flag'>--stripopt</code>, this applies a strip action after the final binary is
299 linked rather than including stripping in all of the build's link actions.
David Chen8fe82a32016-08-24 10:55:41 +0000300</p>
301
ranjanih6a1a09f2021-03-10 15:39:14 -0800302<h4 id='flag--stripopt'><code class='flag'>--stripopt=<var>strip-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000303<p>
Googler11b73bf2021-04-30 14:15:36 -0700304 This is an additional option to pass to the <code>strip</code> command when generating
David Chen8fe82a32016-08-24 10:55:41 +0000305 a <a href="be/c-cpp.html#cc_binary_implicit_outputs"><code>*.stripped</code>
306 binary</a>. The default is <code>-S -p</code>. This option can be used
307 multiple times.
308</p>
309<p>
310 Note that <code class='flag'>--stripopt</code> does not apply to the stripping of the main
311 binary with <code><a href='#flag--strip'>--strip</a>=(always|sometimes)</code>.
312</p>
313
ranjanih6a1a09f2021-03-10 15:39:14 -0800314<h4 id='flag--fdo_instrument'><code class='flag'>--fdo_instrument=<var>profile-output-dir</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000315<p>
316 The <code class='flag'>--fdo_instrument</code> option enables the generation of
317 FDO (feedback directed optimization) profile output when the
318 built C/C++ binary is executed. For GCC, the argument provided is used as a
319 directory prefix for a per-object file directory tree of .gcda files
320 containing profile information for each .o file.
321</p>
322<p>
323 Once the profile data tree has been generated, the profile tree
324 should be zipped up, and provided to the
325 <code class='flag'>--fdo_optimize=<var>profile-zip</var></code>
Googler66663572020-11-09 09:58:27 -0800326 Bazel option to enable the FDO-optimized compilation.
David Chen8fe82a32016-08-24 10:55:41 +0000327
328</p>
329<p>
330 For the LLVM compiler the argument is also the directory under which the raw LLVM profile
331 data file(s) is dumped, e.g.
332 <code class='flag'>--fdo_instrument=<var>/path/to/rawprof/dir/</var></code>.
333</p>
334<p>
335 The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>--fdo_optimize</code>
336 cannot be used at the same time.
337</p>
338
Googler66663572020-11-09 09:58:27 -0800339
ranjanih6a1a09f2021-03-10 15:39:14 -0800340<h4 id='flag--fdo_optimize'><code class='flag'>--fdo_optimize=<var>profile-zip</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000341<p>
342 The <code class='flag'>--fdo_optimize</code> option enables the use of the
343 per-object file profile information to perform FDO (feedback
344 directed optimization) optimizations when compiling. For GCC, the argument
345 provided is the zip file containing the previously-generated file tree
346 of .gcda files containing profile information for each .o file.
347</p>
348<p>
349 Alternatively, the argument provided can point to an auto profile
350 identified by the extension .afdo.
351
352</p>
353<p>
354 Note that this option also accepts labels that resolve to source files. You
355 may need to add an <code>exports_files</code> directive to the corresponding package to
356 make the file visible to Bazel.
357</p>
358<p>
359 For the LLVM compiler the argument provided should point to the indexed LLVM
360 profile output file prepared by the llvm-profdata tool, and should have a .profdata
361 extension.
362</p>
363<p>
364 The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>
365 --fdo_optimize</code> cannot be used at the same time.
366</p>
367
David Chen8fe82a32016-08-24 10:55:41 +0000368
369<h4 id='flag--output_symbol_counts'><code class='flag'>--[no]output_symbol_counts</code></h4>
370<p>
Googlerd7273272017-05-02 18:56:29 +0200371 If enabled, each gold-invoked link of a C++ executable binary will output
David Chen8fe82a32016-08-24 10:55:41 +0000372 a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold
Googlerd7273272017-05-02 18:56:29 +0200373 option). For each linker input, the file logs the number of symbols that were
374 defined and the number of symbols that were used in the binary.
375 This information can be used to track unnecessary link dependencies.
376 The symbol counts file is written to the binary's output path with the name
David Chen8fe82a32016-08-24 10:55:41 +0000377 <code>[targetname].sc</code>.
378</p>
379<p>
Ivo List2fb9f3c2020-12-17 10:19:09 -0800380 This option is disabled by default.
David Chen8fe82a32016-08-24 10:55:41 +0000381</p>
382
Ivo List2fb9f3c2020-12-17 10:19:09 -0800383<h4 id='flag--java_language_version'><code class='flag'>--java_language_version=<var>version</var></code></h4>
384<p>
385 This option specifies the version of Java sources. For example:
386</p>
387<pre>
388 % bazel build --java_language_version=8 java/com/example/common/foo:all
389</pre>
390<p>
391 compiles and allows only constructs compatible with Java 8 specification.
392 Default value is 11. -->
393 Possible values are: 8, 9, 10, --> 11 <!--begin-block:external , 14, and 15 and may be extended by registering custom Java
394 toolchains using <code>default_java_toolchain</code> macro-->.
395</p>
396
397<h4 id='flag--tool_java_language_version'><code class='flag'>--tool_java_language_version=<var>version</var></code>
398</h4>
399<p>
400 The Java language version used to build tools that are executed during a build.
401 Default value is 11.
402</p>
403
404<h4 id='flag--java_runtime_version'><code class='flag'>--java_runtime_version=<var>version</var></code></h4>
405<p>
406 This option specifies the version of JVM to use to execute the code and run the tests. For
407 example:
408</p>
409<pre>
410 % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application
411</pre>
412<p>
413 downloads JDK 11 from a remote repository and run the Java application using it.
414</p>
415<p>
416 Default value is <code>localjdk</code>.
417 Possible values are: <code>localjdk</code>, <code>localjdk_<var>version</var></code>,
418 <code>remotejdk_11</code>,
419 <code>remotejdk_14</code>, and <code>remote_jdk15</code>.
420 You can extend the values by registering custom JVM using either
421 <code>local_java_repository</code> or
422 <code>remote_java_repostory</code> repository rules.
423</p>
424
425<h4 id='flag--tool_java_runtime_version'><code class='flag'>--tool_java_runtime_version=<var>version</var></code></h4>
426<p>
427 The version of JVM used to execute tools that are needed during a build.
428 Default value is <code>remotejdk_11</code>.
429</p>
430-->
431
ranjanih6a1a09f2021-03-10 15:39:14 -0800432<h4 id='flag--jvmopt'><code class='flag'>--jvmopt=<var>jvm-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000433<p>
434 This option allows option arguments to be passed to the Java VM. It can be used
435 with one big argument, or multiple times with individual arguments. For example:
436</p>
437<pre>
438 % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all
439</pre>
440<p>
441 will use the server VM for launching all Java binaries and set the
442 startup heap size for the VM to 256 MB.
443</p>
444
ranjanih6a1a09f2021-03-10 15:39:14 -0800445<h4 id='flag--javacopt'><code class='flag'>--javacopt=<var>javac-option</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000446<p>
447 This option allows option arguments to be passed to javac. It can be used
448 with one big argument, or multiple times with individual arguments. For example:
449</p>
450<pre>
451 % bazel build --javacopt="-g:source,lines" //myprojects:prog
452</pre>
453<p>
454 will rebuild a java_binary with the javac default debug info
455 (instead of the bazel default).
456</p>
457<p>
458 The option is passed to javac after the Bazel built-in default options for
459 javac and before the per-rule options. The last specification of
460 any option to javac wins. The default options for javac are:
461</p>
462
463<pre>
464 -source 8 -target 8 -encoding UTF-8
465</pre>
466<p>
467 Note that changing <code class='flag'>--javacopt</code> settings will force a recompilation
468 of all affected classes. Also note that javacopts parameters listed in
469 specific java_library or java_binary build rules will be placed on the javac
470 command line <em>after</em> these options.
471</p>
472
473<h5 id='-extra_checks'><code>-extra_checks[:(off|on)]</code></h5>
474
475<p>
476 This javac option enables extra correctness checks. Any problems found will
477 be presented as errors.
478 Either <code>-extra_checks</code> or <code>-extra_checks:on</code> may be used
479 to force the checks to be turned on. <code>-extra_checks:off</code> completely
480 disables the analysis.
481 When this option is not specified, the default behavior is used.
482</p>
483
484<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps
485 (default|strict|off|warn|error)</code></h4>
486<p>
487 This option controls whether javac checks for missing direct dependencies.
488 Java targets must explicitly declare all directly used targets as
489 dependencies. This flag instructs javac to determine the jars actually used
490 for type checking each java file, and warn/error if they are not the output
491 of a direct dependency of the current target.
492</p>
493
494<ul>
495 <li> <code>off</code> means checking is disabled.
496 </li>
497 <li> <code>warn</code> means javac will generate standard java warnings of
498 type <code>[strict]</code> for each missing direct dependency.
499 </li>
500 <li> <code>default</code>, <code>strict</code> and <code>error</code> all
501 mean javac will generate errors instead of warnings, causing the current
502 target to fail to build if any missing direct dependencies are found.
503 This is also the default behavior when the flag is unspecified.
504 </li>
505</ul>
506
brandjoncf0390b2020-02-20 10:37:40 -0800507<h3 id='semantics-options'>Build semantics</h3>
David Chen8fe82a32016-08-24 10:55:41 +0000508<p>
509 These options affect the build commands and/or the output file contents.
510</p>
511
512<h4 id='flag--compilation_mode'><code class='flag'>--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4>
513<p>
Googlerd96e8db2020-07-09 20:38:37 -0700514 The <code class="flag">--compilation_mode</code> option (often shortened to <code>-c</code>,
515 especially <code>-c opt</code>) takes an argument of <code>fastbuild</code>, <code>dbg</code>
David Chen8fe82a32016-08-24 10:55:41 +0000516 or <code>opt</code>, and affects various C/C++ code-generation
517 options, such as the level of optimization and the completeness of
Googler0e692fb2021-01-22 18:38:24 +0100518 debug tables. Bazel uses a different output directory for each
David Chen8fe82a32016-08-24 10:55:41 +0000519 different compilation mode, so you can switch between modes without
520 needing to do a full rebuild <i>every</i> time.
521</p>
522<ul>
523 <li> <code>fastbuild</code> means build as fast as possible:
524 generate minimal debugging information (<code>-gmlt
Googler0e692fb2021-01-22 18:38:24 +0100525 -Wl,-S</code>), and don't optimize. This is the
David Chen8fe82a32016-08-24 10:55:41 +0000526 default. Note: <code>-DNDEBUG</code> will <b>not</b> be set.
527 </li>
528 <li> <code>dbg</code> means build with debugging enabled (<code>-g</code>),
529 so that you can use gdb (or another debugger).
530 </li>
531 <li> <code>opt</code> means build with optimization enabled and
532 with <code>assert()</code> calls disabled (<code>-O2 -DNDEBUG</code>).
533 Debugging information will not be generated in <code>opt</code> mode
534 unless you also pass <code class='flag'>--copt -g</code>.
535 </li>
536</ul>
537
ranjanih6a1a09f2021-03-10 15:39:14 -0800538<h4 id='flag--cpu'><code class='flag'>--cpu=<var>cpu</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000539<p>
540This option specifies the target CPU architecture to be used for
541the compilation of binaries during the build.
542</p>
543<p>
544
545</p>
Googlerf12e8022018-09-11 07:51:31 -0700546<p>
547 Note that a particular combination of crosstool version, compiler version,
548 and target CPU is allowed only if it has been specified in the currently
549 used CROSSTOOL file.
550</p>
551
jingwen38b1fee2020-05-11 09:19:25 -0700552<h4 id='flag--action_env'>
553 <code class='flag'>--action_env=<var>VAR=VALUE</var></code>
554</h4>
555<p>
556 Specifies the set of environment variables available during the execution of all actions.
557 Variables can be either specified by name, in which case the value will be taken from the
558 invocation environment, or by the `name=value` pair which sets the value independent of the
559 invocation environment.
560
561 This `--action_env` flag can be specified multiple times. If a value is assigned to the same
562 variable across multiple `--action_env` flags, the latest assignment wins.
563</p>
David Chen8fe82a32016-08-24 10:55:41 +0000564
Benjamin Peterson0b318542017-12-04 10:46:48 -0800565<h4 id='flag--experimental_action_listener'>
566 <code class='flag'>--experimental_action_listener=<var>label</var></code>
567</h4>
568<p>
lberki7b0ff0a2021-03-05 00:14:47 -0800569 <b>WARNING:</b> Extra actions are deprecated. Use
570 <a href="https://docs.bazel.build/versions/master/skylark/aspects.html">aspects</a>
571 instead.
572</p>
573<p>
Benjamin Peterson0b318542017-12-04 10:46:48 -0800574 The <code>experimental_action_listener</code> option instructs Bazel to use
575 details from the <a href="be/extra-actions.html#action_listener"
576 ><code>action_listener</code></a> rule specified by <var>label</var> to
577 insert <a href="be/extra-actions.html#extra_action"
578 ><code>extra_actions</code></a> into the build graph.
579</p>
580
581<h4 id='flag--experimental_extra_action_top_level_only'>
582 <code class='flag'>--[no]experimental_extra_action_top_level_only</code>
583</h4>
584<p>
lberki7b0ff0a2021-03-05 00:14:47 -0800585 <b>WARNING:</b> Extra actions are deprecated. Use
586 <a href="https://docs.bazel.build/versions/master/skylark/aspects.html">aspects</a>
587 instead.
588</p>
589<p>
Benjamin Peterson0b318542017-12-04 10:46:48 -0800590 If this option is set to true, extra actions specified by the
591 <a href='#flag--experimental_action_listener'> <code>
592 --experimental_action_listener</code></a> command line option will only be
593 scheduled for top level targets.
594</p>
595
596<h4 id='flag--experimental_extra_action_filter'>
597 <code class='flag'>--experimental_extra_action_filter=<var>regex</var></code>
598</h4>
599<p>
lberki7b0ff0a2021-03-05 00:14:47 -0800600 <b>WARNING:</b> Extra actions are deprecated. Use
601 <a href="https://docs.bazel.build/versions/master/skylark/aspects.html">aspects</a>
602 instead.
603</p>
604<p>
Benjamin Peterson0b318542017-12-04 10:46:48 -0800605 The <code>experimental_extra_action_filter</code> option instructs Bazel to
606 filter the set of targets to schedule <code>extra_actions</code> for.
607</p>
608<p>
609 This flag is only applicable in combination with the
610 <a href='#flag--experimental_action_listener'
611 ><code>--experimental_action_listener</code></a> flag.
612</p>
613<p>
614 By default all <code>extra_actions</code> in the transitive closure of the
615 requested targets-to-build get scheduled for execution.
616 <code>--experimental_extra_action_filter</code> will restrict scheduling to
617 <code>extra_actions</code> of which the owner's label matches the specified
618 regular expression.
619</p>
620<p>
621 The following example will limit scheduling of <code>extra_actions</code>
622 to only apply to actions of which the owner's label contains '/bar/':
623</p>
624<pre>% bazel build --experimental_action_listener=//test:al //foo/... \
625 --experimental_extra_action_filter=.*/bar/.*
626</pre>
627
ranjanih6a1a09f2021-03-10 15:39:14 -0800628<h4 id='flag--host_cpu'><code class='flag'>--host_cpu=<var>cpu</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000629<p>
630 This option specifies the name of the CPU architecture that should be
631 used to build host tools.
632</p>
633
ranjanih6a1a09f2021-03-10 15:39:14 -0800634<h4 id='flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu=<var>cpu[,cpu]*</var></code></h4>
Alex Humesky105e6612017-01-06 19:03:10 +0000635<p>
636 The CPUs to build C/C++ libraries for in the transitive <code>deps</code> of
637 <code>android_binary</code>
638
639 rules. Other C/C++ rules are not affected. For example, if a <code>cc_library</code>
640 appears in the transitive <code>deps</code> of an <code>android_binary</code> rule and a
641 <code>cc_binary</code> rule, the <code>cc_library</code> will be built at least twice:
642 once for each CPU specified with <code class='flag'>--fat_apk_cpu</code> for the
643 <code>android_binary</code> rule, and once for the CPU specified with
644 <code class='flag'>--cpu</code> for the <code>cc_binary</code> rule.
Ivo List2fb9f3c2020-12-17 10:19:09 -0800645</p>
Alex Humesky105e6612017-01-06 19:03:10 +0000646
647<p>
Ivo List2fb9f3c2020-12-17 10:19:09 -0800648 The default is <code>armeabi-v7a</code>.
649</p>
650<p>
651 One <code>.so</code> file is created and packaged in the APK for
652 each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The <code>.so</code> file's name
653 prefixes the name of the <code>android_binary</code> rule with "lib". For example, if the name of
654 the <code>android_binary</code> is "foo", then the file is <code>libfoo.so</code>.
Alex Humesky105e6612017-01-06 19:03:10 +0000655</p>
656 <p>
657 One <code>.so</code> file will be created and packaged in the APK for
658 each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The name of the <code>.so</code>
659 file will be the name of the <code>android_binary</code> rule prefixed with "lib", e.g., if the name
660 of the <code>android_binary</code> is "foo", then the file will be <code>libfoo.so</code>.
661 </p>
662
663 <p>
664 Note that an Android-compatible crosstool must be selected.
665 If an <code>android_ndk_repository</code> rule is defined in the
666 WORKSPACE file, an Android-compatible crosstool is automatically selected.
667 Otherwise, the crostool can be selected using the
668 <a href='#flag--android_crosstool_top'><code class='flag'>--android_crosstool_top</code></a>
669 or <a href='#flag--crosstool_top'><code class='flag'>--crosstool_top</code></a> flags.
670 </p>
Ivo List2fb9f3c2020-12-17 10:19:09 -0800671
672
673<h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt
674 <var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4>
Alex Humesky105e6612017-01-06 19:03:10 +0000675</p>
676
ranjanih6a1a09f2021-03-10 15:39:14 -0800677<h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt=
David Chen8fe82a32016-08-24 10:55:41 +0000678 <var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4>
679<p>
680 When present, any C++ file with a label or an execution path matching one of the inclusion regex
681 expressions and not matching any of the exclusion expressions will be built
682 with the given options. The label matching uses the canonical form of the label
683 (i.e //<code>package</code>:<code>label_name</code>).
684
685 The execution path is the relative path to your workspace directory including the base name
686 (including extension) of the C++ file. It also includes any platform dependent prefixes.
687 Note, that if only one of the label or the execution path matches the options will be used.
688</p>
689<p>
690 <b>Notes</b>:
691 To match the generated files (e.g. genrule outputs)
692 Bazel can only use the execution path. In this case the regexp shouldn't start with '//'
693 since that doesn't match any execution paths. Package names can be used like this:
694 <code class='flag'>--per_file_copt=base/.*\.pb\.cc@-g0</code>. This will match every
695 <code>.pb.cc</code> file under a directory called <code>base</code>.
696</p>
697<p>
698 This option can be used multiple times.
699</p>
700<p>
701 The option is applied regardless of the compilation mode used. I.e. it is possible
702 to compile with <code class='flag'>--compilation_mode=opt</code> and selectively compile some
703 files with stronger optimization turned on, or with optimization disabled.
704</p>
705<p>
706 <b>Caveat</b>: If some files are selectively compiled with debug symbols the symbols
707 might be stripped during linking. This can be prevented by setting
708 <code class='flag'>--strip=never</code>.
709</p>
710<p>
711 <b>Syntax</b>: <code>[+-]regex[,[+-]regex]...@option[,option]...</code> Where
712 <code>regex</code> stands for a regular expression that can be prefixed with
713 a <code>+</code> to identify include patterns and with <code>-</code> to identify
714 exclude patterns. <code>option</code> stands for an arbitrary option that is passed
715 to the C++ compiler. If an option contains a <code>,</code> it has to be quoted like so
716 <code>\,</code>. Options can also contain <code>@</code>, since only the first
717 <code>@</code> is used to separate regular expressions from options.
718</p>
719<p>
720 <b>Example</b>:
721 <code class='flag'>--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs</code>
722 adds the <code>-O0</code> and the <code>-fprofile-arcs</code> options to the command
723 line of the C++ compiler for all <code>.cc</code> files in <code>//foo/</code> except
724 <code>file.cc</code>.
725</p>
ranjanih6a1a09f2021-03-10 15:39:14 -0800726<h4 id='flag--dynamic_mode'><code class='flag'>--dynamic_mode=<var>mode</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000727<p>
728 Determines whether C++ binaries will be linked dynamically, interacting with
729 the <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic
730 attribute</a> on build rules.
731</p>
732
733<p>
734 Modes:
735</p>
736<ul>
737 <li><code>auto</code>: Translates to a platform-dependent mode;
738 <code>default</code> for linux and <code>off</code> for cygwin.</li>
739 <li><code>default</code>: Allows bazel to choose whether to link dynamically.
740 See <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic</a> for more
741 information.</li>
Googler0e692fb2021-01-22 18:38:24 +0100742 <li><code>fully</code>: Links all targets dynamically. This will speed up
David Chen8fe82a32016-08-24 10:55:41 +0000743 linking time, and reduce the size of the resulting binaries.
744
745 </li>
746 <li><code>off</code>: Links all targets in
747 <a href='be/c-cpp.html#cc_binary.linkstatic'>mostly static</a> mode.
748 If <code>-static</code> is set in linkopts, targets will change to fully
749 static.</li>
750</ul>
751
752<h4 id='flag--fission'><code class='flag'>--fission (yes|no|[dbg][,opt][,fastbuild])</code></h4>
753<p>
754 Enables
755
756 <a href='https://gcc.gnu.org/wiki/DebugFission'>Fission</a>,
757 which writes C++ debug information to dedicated .dwo files instead of .o files, where it would
758 otherwise go. This substantially reduces the input size to links and can reduce link times.
759
760</p>
761<p>
762 When set to <code class='flag'>[dbg][,opt][,fastbuild]</code> (example:
763 <code class='flag'>--fission=dbg,fastbuild</code>), Fission is enabled
764 only for the specified set of compilation modes. This is useful for bazelrc
765 settings. When set to <code class='flag'>yes</code>, Fission is enabled
766 universally. When set to <code class='flag'>no</code>, Fission is disabled
767 universally. Default is <code class='flag'>dbg</code>.
768</p>
769
770<h4 id='flag--force_ignore_dash_static'><code class='flag'>--force_ignore_dash_static</code></h4>
771<p>
772 If this flag is set, any <code>-static</code> options in linkopts of
773 <code>cc_*</code> rules BUILD files are ignored. This is only intended as a
774 workaround for C++ hardening builds.
775</p>
776
777<h4 id='flag--force_pic'><code class='flag'>--[no]force_pic</code></h4>
778<p>
779 If enabled, all C++ compilations produce position-independent code ("-fPIC"),
780 links prefer PIC pre-built libraries over non-PIC libraries, and links produce
781 position-independent executables ("-pie"). Default is disabled.
782</p>
783<p>
784 Note that dynamically linked binaries (i.e. <code>--dynamic_mode fully</code>)
785 generate PIC code regardless of this flag's setting. So this flag is for cases
786 where users want PIC code explicitly generated for static links.
787</p>
788
Andrew Pellegrini8d2c1662017-01-26 16:04:12 +0000789<h4 id='flag--android_resource_shrinking'><code class='flag'>--android_resource_shrinking</code></h4>
790<p>
791 Selects whether to perform resource shrinking for android_binary rules. Sets the default for the
792 <a href='be/android.html#android_binary.shrink_resources'>shrink_resources attribute</a> on
793 android_binary rules; see the documentation for that rule for further details. Defaults to off.
794</p>
795
ranjanih6a1a09f2021-03-10 15:39:14 -0800796<h4 id='flag--custom_malloc'><code class='flag'>--custom_malloc=<var>malloc-library-target</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000797<p>
798 When specified, always use the given malloc implementation, overriding all
799 <code>malloc="target"</code> attributes, including in those targets that use the
800 default (by not specifying any <code>malloc</code>).
801</p>
802
ranjanih6a1a09f2021-03-10 15:39:14 -0800803<h4 id='flag--crosstool_top'><code class='flag'>--crosstool_top=<var>label</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000804<p>
805 This option specifies the location of the crosstool compiler suite
806 to be used for all C++ compilation during a build. Bazel will look in that
807 location for a CROSSTOOL file and uses that to automatically determine
808 settings for
809
810 <code class='flag'>--compiler</code>.
811</p>
812
ranjanih6a1a09f2021-03-10 15:39:14 -0800813<h4 id='flag--host_crosstool_top'><code class='flag'>--host_crosstool_top=<var>label</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000814<p>
815 If not specified, bazel uses the value of <code class='flag'>--crosstool_top</code> to compile
816 code in the host configuration, i.e., tools run during the build. The main purpose of this flag
817 is to enable cross-compilation.
818</p>
819
ranjanih6a1a09f2021-03-10 15:39:14 -0800820<h4 id='flag--apple_crosstool_top'><code class='flag'>--apple_crosstool_top=<var>label</var></code></h4>
Cal Peyserf1a15c02017-01-17 20:26:00 +0000821<p>
822 The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
Googler0e692fb2021-01-22 18:38:24 +0100823 objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites
Cal Peyserf1a15c02017-01-17 20:26:00 +0000824 <code class='flag'>--crosstool_top</code>.
825</p>
826
ranjanih6a1a09f2021-03-10 15:39:14 -0800827<h4 id='flag--android_crosstool_top'><code class='flag'>--android_crosstool_top=<var>label</var></code></h4>
Alex Humesky105e6612017-01-06 19:03:10 +0000828<p>
829 The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of
830 <code>android_binary</code> rules. This is useful if other targets in the
831 build require a different crosstool. The default is to use the crosstool
832 generated by the <code>android_ndk_repository</code> rule in the WORKSPACE file.
833 See also <a href='#flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu</code></a>.
834</p>
ranjanih6a1a09f2021-03-10 15:39:14 -0800835<h4 id='flag--compiler'><code class='flag'>--compiler=<var>version</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000836<p>
837 This option specifies the C/C++ compiler version (e.g. <code>gcc-4.1.0</code>)
838 to be used for the compilation of binaries during the build. If you want to
839 build with a custom crosstool, you should use a CROSSTOOL file instead of
840 specifying this flag.
841</p>
842<p>
843 Note that only certain combinations of crosstool version, compiler version,
rosica25ae1992018-06-04 10:41:53 -0700844 and target CPU are allowed.
David Chen8fe82a32016-08-24 10:55:41 +0000845</p>
846
ranjanih6a1a09f2021-03-10 15:39:14 -0800847<h4 id='flag--android_sdk'><code class='flag'>--android_sdk=<var>label</var></code></h4>
Alex Humesky105e6612017-01-06 19:03:10 +0000848<p>
849 This option specifies the Android SDK/platform toolchain
850 and Android runtime library that will be used to build any Android-related
851 rule.
852
853 The Android SDK will be automatically selected if an <code>android_sdk_repository</code>
854 rule is defined in the WORKSPACE file.
855</p>
856
ranjanih6a1a09f2021-03-10 15:39:14 -0800857<h4 id='flag--java_toolchain'><code class='flag'>--java_toolchain=<var>label</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000858<p>
859 This option specifies the label of the java_toolchain used to compile Java
860 source files.
861</p>
862
ranjanih6a1a09f2021-03-10 15:39:14 -0800863<h4 id='flag--host_java_toolchain'><code class='flag'>--host_java_toolchain=<var>label</var></code></h4>
cushon41375ac42017-10-30 17:03:18 -0400864<p>
865 If not specified, bazel uses the value of <code class='flag'>--java_toolchain</code> to compile
866 code in the host configuration, i.e., tools run during the build. The main purpose of this flag
867 is to enable cross-compilation.
868</p>
869
ranjanih6a1a09f2021-03-10 15:39:14 -0800870<h4 id='flag--javabase'><code class='flag'>--javabase=(<var>label</var>)</code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000871<p>
cushon7d9596c2018-07-23 13:55:14 -0700872 This option sets the <i>label</i> of the base Java installation to use for <i>bazel run</i>,
873 <i>bazel test</i>, and for Java binaries built by <code>java_binary</code> and
874 <code>java_test</code> rules. The <code>JAVABASE</code> and <code>JAVA</code>
875 <a href='be/make-variables.html'>"Make" variables</a> are derived from this option.
David Chen8fe82a32016-08-24 10:55:41 +0000876</p>
877
ranjanih6a1a09f2021-03-10 15:39:14 -0800878<h4 id='flag--host_javabase'><code class='flag'>--host_javabase=<var>label</var></code></h4>
cushon41375ac42017-10-30 17:03:18 -0400879<p>
cushon2a8b6572018-07-25 10:33:40 -0700880 This option sets the <i>label</i> of the base Java installation to use in the host configuration,
cushon7d9596c2018-07-23 13:55:14 -0700881 for example for host build tools including JavaBuilder and Singlejar.
cushon41375ac42017-10-30 17:03:18 -0400882</p>
David Chen8fe82a32016-08-24 10:55:41 +0000883<p>
884 This does not select the Java compiler that is used to compile Java
885 source files. The compiler can be selected by settings the
886 <a href="#flag--java_toolchain"><code class='flag'>--java_toolchain</code></a>
887 option.
888</p>
889
brandjoncf0390b2020-02-20 10:37:40 -0800890<h3 id='strategy-options'>Execution strategy</h3>
David Chen8fe82a32016-08-24 10:55:41 +0000891<p>
892 These options affect how Bazel will execute the build.
893 They should not have any significant effect on the output files
Googler0e692fb2021-01-22 18:38:24 +0100894 generated by the build. Typically their main effect is on the
Googler8d6ac072021-02-12 13:25:32 -0800895 speed of the build.
David Chen8fe82a32016-08-24 10:55:41 +0000896</p>
897
ranjanih6a1a09f2021-03-10 15:39:14 -0800898<h4 id='flag--spawn_strategy'><code class='flag'>--spawn_strategy=<var>strategy</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000899<p>
900 This option controls where and how commands are executed.
901</p>
902<ul>
903
904 <li>
ulfjacka42d1892019-02-12 08:34:30 -0800905 <code>standalone</code> causes commands to be executed as local subprocesses. This value is
906 deprecated. Please use <code>local</code> instead.
David Chen8fe82a32016-08-24 10:55:41 +0000907 </li>
908 <li>
909 <code>sandboxed</code> causes commands to be executed inside a sandbox on the local machine.
910 This requires that all input files, data dependencies and tools are listed as direct
911 dependencies in the <code>srcs</code>, <code>data</code> and <code>tools</code> attributes.
912 This is the default on systems that support sandboxed execution.
913 </li>
914
ulfjacka42d1892019-02-12 08:34:30 -0800915 <li>
916 <code>local</code> causes commands to be executed as local subprocesses.
917 </li>
918
ulfjacka42d1892019-02-12 08:34:30 -0800919 <li>
Dave Leebc67b362019-10-02 04:29:41 -0700920 <code>worker</code> causes commands to be executed using a persistent worker, if available.
921 </li>
922
923 <li>
ulfjacka42d1892019-02-12 08:34:30 -0800924 <code>docker</code> causes commands to be executed inside a docker sandbox on the local machine.
925 This requires that docker is installed.
926 </li>
927
928 <li>
929 <code>remote</code> causes commands to be executed remotely; this is only available if a
930 remote executor has been configured separately.
931 </li>
ulfjacka42d1892019-02-12 08:34:30 -0800932</ul>
933
934<h4 id='flag--strategy'><code class='flag'>--strategy <var>mnemonic</var>=<var>strategy</var></code></h4>
935<p>
936 This option controls where and how commands are executed, overriding the default setting on a
937 per-mnemonic basis. See
938 <code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported
939 strategies and their effects.
940</p>
941
ranjanih6a1a09f2021-03-10 15:39:14 -0800942<h4 id='flag--strategy_regexp'><code class='flag'>--strategy_regexp=<var>&lt;filter,filter,...&gt;=&lt;strategy&gt;</var></code></h4>
ulfjacka42d1892019-02-12 08:34:30 -0800943<p>
944 This option specifies which strategy should be used to execute commands that have descriptions
945 matching a certain <code>regex_filter</code>. See
946 <code class='flag'><a href="#flag--per_file_copt">--per_file_copt</a></code> for details on
947 regex_filter matching. See
948 <code class='flag'><a href="#flag--spawn_strategy">--spawn_strategy</a></code> for the supported
949 strategies and their effects.
950</p>
951<p>
952The first <code>regex_filter</code> that matches the description is used. This option overrides
953other flags for specifying strategy.
954</p>
955<ul>
956 <li>
957 Example: <code>--strategy_regexp=//foo.*\\.cc,-//foo/bar=local</code> means to run actions using
958 <code>local</code> strategy if their descriptions match //foo.*.cc but not //foo/bar.
959 </li>
960 <li>
961 Example:
962 <code>--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed</code>
963 will run 'Compiling //foo/bar/baz' with the <code>local</code> strategy, but reversing the order
964 would run it with <code>sandboxed</code>.
965 </li>
David Chen8fe82a32016-08-24 10:55:41 +0000966</ul>
967
ranjanih6a1a09f2021-03-10 15:39:14 -0800968<h4 id='flag--genrule_strategy'><code class='flag'>--genrule_strategy=<var>strategy</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000969<p>
ulfjacka42d1892019-02-12 08:34:30 -0800970 This is a deprecated short-hand for
971 <code class='flag'>--strategy=Genrule=<var>strategy</var></code>.
David Chen8fe82a32016-08-24 10:55:41 +0000972</p>
David Chen8fe82a32016-08-24 10:55:41 +0000973
ranjanih6a1a09f2021-03-10 15:39:14 -0800974<h4 id='flag--jobs'><code class='flag'>--jobs=<var>n</var></code> (-j)</h4>
David Chen8fe82a32016-08-24 10:55:41 +0000975<p>
976 This option, which takes an integer argument, specifies a limit on
977 the number of jobs that should be executed concurrently during the
Googlerb6857d52017-09-22 14:03:21 -0400978 execution phase of the build.
David Chen8fe82a32016-08-24 10:55:41 +0000979</p>
980<p>
981 Note that the number of concurrent jobs that Bazel will run
982 is determined not only by the <code class='flag'>--jobs</code> setting, but also
983 by Bazel's scheduler, which tries to avoid running concurrent jobs
984 that will use up more resources (RAM or CPU) than are available,
985 based on some (very crude) estimates of the resource consumption
Googler0e692fb2021-01-22 18:38:24 +0100986 of each job. The behavior of the scheduler can be controlled by
steinman7f530c82020-04-15 14:13:42 -0700987 the <code class='flag'>--local_ram_resources</code> option.
David Chen8fe82a32016-08-24 10:55:41 +0000988</p>
989
ranjanih6a1a09f2021-03-10 15:39:14 -0800990<h4 id='flag--progress_report_interval'><code class='flag'>--progress_report_interval=<var>n</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +0000991<p>
992
993 Bazel periodically prints a progress report on jobs that are not
Googler0e692fb2021-01-22 18:38:24 +0100994 finished yet (e.g. long running tests). This option sets the
David Chen8fe82a32016-08-24 10:55:41 +0000995 reporting frequency, progress will be printed every <code>n</code>
996 seconds.
997</p>
998<p>
999 The default is 0, that means an incremental algorithm: the first
1000 report will be printed after 10 seconds, then 30 seconds and after
1001 that progress is reported once every minute.
1002</p>
1003
steinmancd1783d2019-03-08 08:09:42 -08001004<h4 id='flag--local_{ram,cpu}_resources'><code class='flag'>--local_{ram,cpu}_resources</code>
1005 <var>resources or resource expression</var></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001006<p>
steinmancd1783d2019-03-08 08:09:42 -08001007 These options specify the amount of local resources (RAM in MB and number of CPU logical cores)
1008 that Bazel can take into consideration when scheduling build and test activities. They take
Ivo List2fb9f3c2020-12-17 10:19:09 -08001009 an integer, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by [-|*<code>float</code>]
steinmancd1783d2019-03-08 08:09:42 -08001010 (for example, <code class='flag'>--local_cpu_resources=2</code>,
1011 <code class='flag'>--local_ram_resources=HOST_RAM*.5</code>,
1012 <code class='flag'>--local_cpu_resources=HOST_CPUS-1</code>).
1013 The flags are independent; one or both may be set. By default Bazel will estimate amount of RAM
1014 and number of CPU cores directly from system configuration.
David Chen8fe82a32016-08-24 10:55:41 +00001015</p>
David Chen8fe82a32016-08-24 10:55:41 +00001016
1017<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4>
1018<p>
Googler5a495842017-08-22 01:30:36 +02001019 This option, which is enabled by default, specifies whether the runfiles
1020 symlinks for tests and binaries should be built in the output directory.
David Chen8fe82a32016-08-24 10:55:41 +00001021 Using <code class='flag'>--nobuild_runfile_links</code> can be useful
1022 to validate if all targets compile without incurring the overhead
1023 for building the runfiles trees.
1024
David Chen8fe82a32016-08-24 10:55:41 +00001025</p>
1026
1027<p>
Googler5a495842017-08-22 01:30:36 +02001028 When tests (or applications) are executed, their run-time data
Googler0e692fb2021-01-22 18:38:24 +01001029 dependencies are gathered together in one place. Within Bazel's
Googler5a495842017-08-22 01:30:36 +02001030 output tree, this "runfiles" tree is typically rooted as a sibling of
1031 the corresponding binary or test.
1032 During test execution, runfiles may be accessed using paths of the form
David Chen8fe82a32016-08-24 10:55:41 +00001033 <code>$TEST_SRCDIR/workspace/<var>packagename</var>/<var>filename</var></code>.
Googler5a495842017-08-22 01:30:36 +02001034 The runfiles tree ensures that tests have access to all the files
Googler0e692fb2021-01-22 18:38:24 +01001035 upon which they have a declared dependence, and nothing more. By
David Chen8fe82a32016-08-24 10:55:41 +00001036 default, the runfiles tree is implemented by constructing a set of
Googler0e692fb2021-01-22 18:38:24 +01001037 symbolic links to the required files. As the set of links grows, so
David Chen8fe82a32016-08-24 10:55:41 +00001038 does the cost of this operation, and for some large builds it can
1039 contribute significantly to overall build time, particularly because
1040 each individual test (or application) requires its own runfiles tree.
1041</p>
David Chen8fe82a32016-08-24 10:55:41 +00001042
Googler01f659d2017-08-22 02:53:02 +02001043<h4 id='flag--build_runfile_manifests'><code class='flag'>--[no]build_runfile_manifests</code></h4>
1044<p>
1045 This option, which is enabled by default, specifies whether runfiles manifests
1046 should be written to the output tree.
1047 Disabling it implies <code class='flag'>--nobuild_runfile_links</code>.
1048
Tobias Werth78e27f42019-08-12 00:49:58 -07001049 It can be disabled when executing tests remotely, as runfiles trees will
Googler01f659d2017-08-22 02:53:02 +02001050 be created remotely from in-memory manifests.
1051
David Chen8fe82a32016-08-24 10:55:41 +00001052<h4 id='flag--discard_analysis_cache'>
1053 <code class='flag'>--[no]discard_analysis_cache</code></h4>
1054<p>
1055 When this option is enabled, Bazel will discard the analysis cache
1056 right before execution starts, thus freeing up additional memory
Googler59830672019-01-03 10:33:49 -08001057 (around 10%) for the <a href="guide.html#execution-phase">execution phase</a>.
janakr428c5e12019-05-06 15:35:54 -07001058 The drawback is that further incremental builds will be slower. See also
janakr69781dd52019-05-07 09:04:41 -07001059 <a href="/versions/{{ current_version }}/memory-saving-mode.html">
Googlera05b7f02019-05-21 08:13:04 -07001060memory-saving mode</a>.
David Chen8fe82a32016-08-24 10:55:41 +00001061</p>
1062
1063<h4 id='flag--keep_going'><code class='flag'>--[no]keep_going</code> (-k)</h4>
1064<p>
1065 As in GNU Make, the execution phase of a build stops when the first
Googler0e692fb2021-01-22 18:38:24 +01001066 error is encountered. Sometimes it is useful to try to build as
1067 much as possible even in the face of errors. This option enables
David Chen8fe82a32016-08-24 10:55:41 +00001068 that behavior, and when it is specified, the build will attempt to
1069 build every target whose prerequisites were successfully built, but
1070 will ignore errors.
1071</p>
1072<p>
1073 While this option is usually associated with the execution phase of
Googler8d6ac072021-02-12 13:25:32 -08001074 a build, it also affects the analysis phase: if several targets are
David Chen8fe82a32016-08-24 10:55:41 +00001075 specified in a build command, but only some of them can be
1076 successfully analyzed, the build will stop with an error
1077 unless <code class='flag'>--keep_going</code> is specified, in which case the
1078 build will proceed to the execution phase, but only for the targets
1079 that were successfully analyzed.
1080</p>
1081
David Chen8fe82a32016-08-24 10:55:41 +00001082<h4 id='flag--use_ijars'><code class='flag'>--[no]use_ijars</code></h4>
1083<p>
1084 This option changes the way <code>java_library</code> targets are
1085 compiled by Bazel. Instead of using the output of a
1086 <code>java_library</code> for compiling dependent
1087 <code>java_library</code> targets, Bazel will create interface jars
1088 that contain only the signatures of non-private members (public,
1089 protected, and default (package) access methods and fields) and use
Googler0e692fb2021-01-22 18:38:24 +01001090 the interface jars to compile the dependent targets. This makes it
David Chen8fe82a32016-08-24 10:55:41 +00001091 possible to avoid recompilation when changes are only made to
1092 method bodies or private members of a class.
1093</p>
1094<p>
1095 Note that using <code class='flag'>--use_ijars</code> might give you a different
1096 error message when you are accidentally referring to a non visible
1097 member of another class: Instead of getting an error that the member
1098 is not visible you will get an error that the member does not exist.
1099</p>
1100<p>
1101 Note that changing the <code class='flag'>--use_ijars</code> setting will force
1102 a recompilation of all affected classes.
1103</p>
1104
1105<h4 id='flag--interface_shared_objects'>
1106 <code class='flag'>--[no]interface_shared_objects</code>
1107</h4>
1108<p>
1109 This option enables <i>interface shared objects</i>, which makes binaries and
1110 other shared libraries depend on the <i>interface</i> of a shared object,
1111 rather than its implementation. When only the implementation changes, Bazel
1112 can avoid rebuilding targets that depend on the changed shared library
1113 unnecessarily.
1114</p>
1115
brandjoncf0390b2020-02-20 10:37:40 -08001116<h3 id='output-selection-options'>Output selection</h3>
David Chen8fe82a32016-08-24 10:55:41 +00001117<p>
1118 These options determine what to build or test.
1119</p>
1120
1121<h4 id="nobuild"><code class='flag'>--[no]build</code></h4>
1122<p>
1123 This option causes the execution phase of the build to occur; it is
Googler0e692fb2021-01-22 18:38:24 +01001124 on by default. When it is switched off, the execution phase is
David Chen8fe82a32016-08-24 10:55:41 +00001125 skipped, and only the first two phases, loading and analysis, occur.
1126</p>
1127<p>
1128 This option can be useful for validating BUILD files and detecting
1129 errors in the inputs, without actually building anything.
1130</p>
1131
1132<h4 id='flag--build_tests_only'><code class='flag'>--[no]build_tests_only</code></h4>
1133<p>
1134 If specified, Bazel will build only what is necessary to run the *_test
1135 and test_suite rules that were not filtered due to their
1136 <a href='#flag--test_size_filters'>size</a>,
1137 <a href='#flag--test_timeout_filters'>timeout</a>,
1138 <a href='#flag--test_tag_filters'>tag</a>, or
1139 <a href='#flag--test_lang_filters'>language</a>.
1140 If specified, Bazel will ignore other targets specified on the command line.
1141 By default, this option is disabled and Bazel will build everything
1142 requested, including *_test and test_suite rules that are filtered out from
1143 testing. This is useful because running
1144 <code>bazel test --build_tests_only foo/...</code> may not detect all build
1145 breakages in the <code>foo</code> tree.
1146</p>
1147
1148<h4 id='flag--check_up_to_date'><code class='flag'>--[no]check_up_to_date</code></h4>
1149<p>
1150 This option causes Bazel not to perform a build, but merely check
Googler0e692fb2021-01-22 18:38:24 +01001151 whether all specified targets are up-to-date. If so, the build
1152 completes successfully, as usual. However, if any files are out of
David Chen8fe82a32016-08-24 10:55:41 +00001153 date, instead of being built, an error is reported and the build
Googler0e692fb2021-01-22 18:38:24 +01001154 fails. This option may be useful to determine whether a build has
David Chen8fe82a32016-08-24 10:55:41 +00001155 been performed more recently than a source edit (e.g. for pre-submit
1156 checks) without incurring the cost of a build.
1157</p>
1158<p>
1159 See also <a href="#flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></a>.
1160</p>
1161
1162<h4 id='flag--compile_one_dependency'><code class='flag'>--[no]compile_one_dependency</code></h4>
1163<p>
Googler0e692fb2021-01-22 18:38:24 +01001164 Compile a single dependency of the argument files. This is useful for
David Chen8fe82a32016-08-24 10:55:41 +00001165 syntax checking source files in IDEs, for example, by rebuilding a single
1166 target that depends on the source file to detect errors as early as
Googler0e692fb2021-01-22 18:38:24 +01001167 possible in the edit/build/test cycle. This argument affects the way all
Googler35a79c52021-05-05 02:58:41 -07001168 non-flag arguments are interpreted: each argument must be a
1169 file target label or a plain filename relative to the current working
1170 directory, and one rule that depends on each source filename is built. For
David Chen8fe82a32016-08-24 10:55:41 +00001171
1172 C++ and Java
1173 sources, rules in the same language space are preferentially chosen. For
1174 multiple rules with the same preference, the one that appears first in the
1175 BUILD file is chosen. An explicitly named target pattern which does not
1176 reference a source file results in an error.
1177</p>
1178
1179<h4 id='flag--save_temps'><code class='flag'>--save_temps</code></h4>
1180<p>
Googler9cfa4cb2018-06-04 22:19:11 -07001181 The <code class='flag'>--save_temps</code> option causes temporary outputs from the compiler to be
1182 saved. These include .s files (assembler code), .i (preprocessed C) and .ii
Googler0e692fb2021-01-22 18:38:24 +01001183 (preprocessed C++) files. These outputs are often useful for debugging. Temps will only be
David Chen8fe82a32016-08-24 10:55:41 +00001184 generated for the set of targets specified on the command line.
1185</p>
1186<p>
Googler03fd5412021-03-11 18:57:14 -08001187 Note that the implementation of <code class='flag'>--save_temps</code> does not use the compiler's
1188 <code>-save-temps</code> flag. Instead, there are two passes, one with <code>-S</code>
Googler0e692fb2021-01-22 18:38:24 +01001189 and one with <code>-E</code>. A consequence of this is that if your build fails,
David Chen8fe82a32016-08-24 10:55:41 +00001190 Bazel may not yet have produced the ".i" or ".ii" and ".s" files.
1191 If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation,
1192 you may need to also use <code class='flag'>--keep_going</code> so that Bazel will still try to
1193 produce the preprocessed files after the compilation fails.
1194</p>
1195<p>
1196 The <code class='flag'>--save_temps</code> flag currently works only for cc_* rules.
1197</p>
1198<p>
1199 To ensure that Bazel prints the location of the additional output files, check that
1200 your <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a>
1201 setting is high enough.
1202</p>
1203
ranjanih6a1a09f2021-03-10 15:39:14 -08001204<h4 id='flag--build_tag_filters'><code class='flag'>--build_tag_filters=<var>tag[,tag]*</var></code></h4>
Googlerd9db1692017-01-05 19:34:30 +00001205<p>
1206 If specified, Bazel will build only targets that have at least one required tag
1207 (if any of them are specified) and does not have any excluded tags. Build tag
1208 filter is specified as comma delimited list of tag keywords, optionally
1209 preceded with '-' sign used to denote excluded tags. Required tags may also
1210 have a preceding '+' sign.
1211</p>
janakrc63128d2020-08-05 15:42:49 -07001212<p>
1213 When running tests, Bazel ignores <code class='flag'>--build_tag_filters</code> for test targets,
1214 which are built and run even if they do not match this filter. To avoid building them, filter
1215 test targets using <code class='flag'>--test_tag_filters</code> or by explicitly excluding them.
1216</p>
Googlerd9db1692017-01-05 19:34:30 +00001217
ranjanih6a1a09f2021-03-10 15:39:14 -08001218<h4 id='flag--test_size_filters'><code class='flag'>--test_size_filters=<var>size[,size]*</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001219<p>
1220 If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
1221 is also specified) only test targets with the given size. Test size filter
1222 is specified as comma delimited list of allowed test size values (small,
1223 medium, large or enormous), optionally preceded with '-' sign used to denote
1224 excluded test sizes. For example,
1225</p>
1226<pre>
1227 % bazel test --test_size_filters=small,medium //foo:all
1228</pre>
1229 and
1230<pre>
1231 % bazel test --test_size_filters=-large,-enormous //foo:all
1232</pre>
1233<p>
1234 will test only small and medium tests inside //foo.
1235</p>
1236<p>
1237 By default, test size filtering is not applied.
1238</p>
1239
ranjanih6a1a09f2021-03-10 15:39:14 -08001240<h4 id='flag--test_timeout_filters'><code class='flag'>--test_timeout_filters=<var>timeout[,timeout]*</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001241<p>
1242 If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
1243 is also specified) only test targets with the given timeout. Test timeout filter
1244 is specified as comma delimited list of allowed test timeout values (short,
1245 moderate, long or eternal), optionally preceded with '-' sign used to denote
1246 excluded test timeouts. See <a href='#flag--test_size_filters'>--test_size_filters</a>
1247 for example syntax.
1248</p>
1249<p>
1250 By default, test timeout filtering is not applied.
1251</p>
1252
1253
ranjanih6a1a09f2021-03-10 15:39:14 -08001254<h4 id='flag--test_tag_filters'><code class='flag'>--test_tag_filters=<var>tag[,tag]*</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001255<p>
1256 If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
1257 is also specified) only test targets that have at least one required tag
1258 (if any of them are specified) and does not have any excluded tags. Test tag
1259 filter is specified as comma delimited list of tag keywords, optionally
1260 preceded with '-' sign used to denote excluded tags. Required tags may also
1261 have a preceding '+' sign.
1262</p>
1263<p>
1264 For example,
1265<pre>
1266 % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all
1267</pre>
1268<p>
1269 will test targets that are tagged with either <code>performance</code> or
1270 <code>stress</code> tag but are <b>not</b> tagged with the <code>flaky</code>
1271 tag.
1272</p>
1273<p>
Googler0e692fb2021-01-22 18:38:24 +01001274 By default, test tag filtering is not applied. Note that you can also filter
David Chen8fe82a32016-08-24 10:55:41 +00001275 on test's <code>size</code> and <code>local</code> tags in
1276 this manner.
1277</p>
1278
ranjanih6a1a09f2021-03-10 15:39:14 -08001279<h4 id='flag--test_lang_filters'><code class='flag'>--test_lang_filters=<var>lang[,lang]*</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001280<p>
1281 Specifies a comma-separated list of test languages for languages with an official <code>*_test</code> rule the
1282 (see <a href="be/overview.html">build encyclopedia</a> for a full list of these). Each
1283 language can be optionally preceded with '-' to specify excluded
Googler0e692fb2021-01-22 18:38:24 +01001284 languages. The name used for each language should be the same as
David Chen8fe82a32016-08-24 10:55:41 +00001285 the language prefix in the <code>*_test</code> rule, for example,
1286 <code>cc</code>, <code>java</code> or <code>sh</code>.
1287</p>
1288<p>
1289 If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
1290 is also specified) only test targets of the specified language(s).
1291</p>
1292<p>
1293 For example,
1294</p>
1295<pre>
1296 % bazel test --test_lang_filters=cc,java foo/...
1297</pre>
1298<p>
1299 will test only the C/C++ and Java tests (defined using
1300 <code>cc_test</code> and <code>java_test</code> rules, respectively)
1301 in <code>foo/...</code>, while
1302</p>
1303<pre>
1304 % bazel test --test_lang_filters=-sh,-java foo/...
1305</pre>
1306<p>
1307 will run all of the tests in <code>foo/...</code> except for the
1308 <code>sh_test</code> and <code>java_test</code> tests.
1309</p>
1310<p>
1311 By default, test language filtering is not applied.
1312</p>
1313
1314<h4 id="flag--test_filter"><code class='flag'>--test_filter=<var>filter-expression</var></code></h4>
1315<p>
1316 Specifies a filter that the test runner may use to pick a subset of tests for
michajlo20971eb2020-03-12 08:00:09 -07001317 running. All targets specified in the invocation are built, but depending on
David Chen8fe82a32016-08-24 10:55:41 +00001318 the expression only some of them may be executed; in some cases, only certain
1319 test methods are run.
1320</p>
1321<p>
1322 The particular interpretation of <var>filter-expression</var> is up to
1323 the test framework responsible for running the test. It may be a glob,
1324 substring, or regexp. <code class='flag'>--test_filter</code> is a convenience
1325 over passing different <code class='flag'>--test_arg</code> filter arguments,
1326 but not all frameworks support it.
1327</p>
1328
brandjoncf0390b2020-02-20 10:37:40 -08001329<h3 id='verbosity'>Verbosity</h3>
David Chen8fe82a32016-08-24 10:55:41 +00001330
1331These options control the verbosity of Bazel's output,
1332either to the terminal, or to additional log files.
1333
ranjanih6a1a09f2021-03-10 15:39:14 -08001334<h4 id='flag--explain'><code class='flag'>--explain=<var>logfile</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001335<p>
1336 This option, which requires a filename argument, causes the
1337 dependency checker in <code>bazel build</code>'s execution phase to
1338 explain, for each build step, either why it is being executed, or
Googler0e692fb2021-01-22 18:38:24 +01001339 that it is up-to-date. The explanation is written
David Chen8fe82a32016-08-24 10:55:41 +00001340 to <i>logfile</i>.
1341</p>
1342<p>
1343 If you are encountering unexpected rebuilds, this option can help to
Googler0e692fb2021-01-22 18:38:24 +01001344 understand the reason. Add it to your <code>.bazelrc</code> so that
David Chen8fe82a32016-08-24 10:55:41 +00001345 logging occurs for all subsequent builds, and then inspect the log
Googler0e692fb2021-01-22 18:38:24 +01001346 when you see an execution step executed unexpectedly. This option
David Chen8fe82a32016-08-24 10:55:41 +00001347 may carry a small performance penalty, so you might want to remove
1348 it when it is no longer needed.
1349</p>
1350
1351<h4 id='flag--verbose_explanations'><code class='flag'>--verbose_explanations</code></h4>
1352<p>
1353 This option increases the verbosity of the explanations generated
1354 when the <a href='#flag--explain'>--explain</a> option is enabled.
1355</p>
1356<p>
1357 In particular, if verbose explanations are enabled,
1358 and an output file is rebuilt because the command used to
1359 build it has changed, then the output in the explanation file will
1360 include the full details of the new command (at least for most
1361 commands).
1362</p>
1363<p>
1364 Using this option may significantly increase the length of the
1365 generated explanation file and the performance penalty of using
1366 <code class='flag'>--explain</code>.
1367</p>
1368<p>
1369 If <code class='flag'>--explain</code> is not enabled, then
1370 <code class='flag'>--verbose_explanations</code> has no effect.
1371</p>
1372
ranjanih6a1a09f2021-03-10 15:39:14 -08001373<h4 id='flag--profile'><code class='flag'>--profile=<var>file</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001374<p>
1375 This option, which takes a filename argument, causes Bazel to write
1376 profiling data into a file. The data then can be analyzed or parsed using the
1377 <code>bazel analyze-profile</code> command. The Build profile can be useful in
1378 understanding where Bazel's <code>build</code> command is spending its time.
1379</p>
1380
1381<h4 id='flag--show_loading_progress'><code class='flag'>--[no]show_loading_progress</code></h4>
1382<p>
1383 This option causes Bazel to output package-loading progress
Googler0e692fb2021-01-22 18:38:24 +01001384 messages. If it is disabled, the messages won't be shown.
David Chen8fe82a32016-08-24 10:55:41 +00001385</p>
1386
1387<h4 id='flag--show_progress'><code class='flag'>--[no]show_progress</code></h4>
1388<p>
1389 This option causes progress messages to be displayed; it is on by
Googler0e692fb2021-01-22 18:38:24 +01001390 default. When disabled, progress messages are suppressed.
David Chen8fe82a32016-08-24 10:55:41 +00001391</p>
1392
ranjanih6a1a09f2021-03-10 15:39:14 -08001393<h4 id='flag--show_progress_rate_limit'><code class='flag'>--show_progress_rate_limit=
David Chen8fe82a32016-08-24 10:55:41 +00001394 <var>n</var></code></h4>
1395<p>
1396 This option causes bazel to display only
1397 one progress message per <code>n</code> seconds, where <var>n</var> is a real number.
1398 If <code>n</code> is -1, all progress messages will be displayed. The default value for
1399 this option is 0.03, meaning bazel will limit the progress messages to one per every
1400 0.03 seconds.
1401</p>
1402
ranjanih6a1a09f2021-03-10 15:39:14 -08001403<h4 id='flag--show_result'><code class='flag'>--show_result=<var>n</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001404<p>
1405 This option controls the printing of result information at the end
Googler0e692fb2021-01-22 18:38:24 +01001406 of a <code>bazel build</code> command. By default, if a single
David Chen8fe82a32016-08-24 10:55:41 +00001407 build target was specified, Bazel prints a message stating whether
1408 or not the target was successfully brought up-to-date, and if so,
Googler0e692fb2021-01-22 18:38:24 +01001409 the list of output files that the target created. If multiple
David Chen8fe82a32016-08-24 10:55:41 +00001410 targets were specified, result information is not displayed.
1411</p>
1412<p>
1413 While the result information may be useful for builds of a single
1414 target or a few targets, for large builds (e.g. an entire top-level
1415 project tree), this information can be overwhelming and distracting;
Googler0e692fb2021-01-22 18:38:24 +01001416 this option allows it to be controlled. <code class='flag'>--show_result</code>
David Chen8fe82a32016-08-24 10:55:41 +00001417 takes an integer argument, which is the maximum number of targets
Googler0e692fb2021-01-22 18:38:24 +01001418 for which full result information should be printed. By default,
1419 the value is 1. Above this threshold, no result information is
1420 shown for individual targets. Thus zero causes the result
David Chen8fe82a32016-08-24 10:55:41 +00001421 information to be suppressed always, and a very large value causes
1422 the result to be printed always.
1423</p>
1424<p>
1425 Users may wish to choose a value in-between if they regularly
1426 alternate between building a small group of targets (for example,
1427 during the compile-edit-test cycle) and a large group of targets
1428 (for example, when establishing a new workspace or running
Googler0e692fb2021-01-22 18:38:24 +01001429 regression tests). In the former case, the result information is
1430 very useful whereas in the latter case it is less so. As with all
David Chen8fe82a32016-08-24 10:55:41 +00001431 options, this can be specified implicitly via
Vladimir Chebotarev66885ff2018-12-04 14:08:16 -08001432 the <a href='guide.html#bazelrc'><code>.bazelrc</code></a> file.
David Chen8fe82a32016-08-24 10:55:41 +00001433</p>
1434<p>
1435 The files are printed so as to make it easy to copy and paste the
Googler0e692fb2021-01-22 18:38:24 +01001436 filename to the shell, to run built executables. The "up-to-date"
David Chen8fe82a32016-08-24 10:55:41 +00001437 or "failed" messages for each target can be easily parsed by scripts
1438 which drive a build.
1439</p>
1440
rupertscc569682021-03-24 18:19:59 -07001441<h4 id='flag--sandbox_debug'><code class='flag'>--sandbox_debug</code></h4>
1442<p>
1443 This option causes Bazel to print extra debugging information when using sandboxing for action
1444 execution. This option also preserves sandbox directories, so that the files visible to actions
1445 during execution can be examined.
1446</p>
1447
David Chen8fe82a32016-08-24 10:55:41 +00001448<h4 id='flag--subcommands'><code class='flag'>--subcommands</code> (<code>-s</code>)</h4>
1449<p>
1450 This option causes Bazel's execution phase to print the full command line
1451 for each command prior to executing it.
1452</p>
1453
1454<pre>
1455 &gt;&gt;&gt;&gt;&gt; # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
lberkif071a232017-12-07 04:21:34 -08001456 (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
David Chen8fe82a32016-08-24 10:55:41 +00001457 exec env - \
lberkicbac3282017-12-07 05:47:43 -08001458 /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)
David Chen8fe82a32016-08-24 10:55:41 +00001459</pre>
1460<p>
1461 Where possible, commands are printed in a Bourne shell compatible syntax,
1462 so that they can be easily copied and pasted to a shell command prompt.
1463 (The surrounding parentheses are provided to protect your shell from the
1464 <code>cd</code> and <code>exec</code> calls; be sure to copy them!)
1465 However some commands are implemented internally within Bazel, such as
1466 creating symlink trees. For these there's no command line to display.
1467
1468</p>
1469
1470<p>
ahumeskybe31bb82018-07-26 13:37:45 -07001471 <code class='flag'>--subcommands=pretty_print</code> may be passed to print
1472 the arguments of the command as a list rather than as a single line. This may
1473 help make long command lines more readable.
1474</p>
1475
1476<p>
David Chen8fe82a32016-08-24 10:55:41 +00001477 See also <a href="#flag--verbose_failures">--verbose_failures</a>, below.
1478</p>
1479
1480<h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4>
1481<p>
1482 This option causes Bazel's execution phase to print the full command line
Googler0e692fb2021-01-22 18:38:24 +01001483 for commands that failed. This can be invaluable for debugging a
David Chen8fe82a32016-08-24 10:55:41 +00001484 failing build.
1485</p>
1486<p>
1487 Failing commands are printed in a Bourne shell compatible syntax, suitable
1488 for copying and pasting to a shell prompt.
1489</p>
1490
brandjoncf0390b2020-02-20 10:37:40 -08001491<h3 id='workspace_status'>Workspace status</h3>
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001492
1493<p>
1494 Use these options to "stamp" Bazel-built binaries: to embed additional information into the
1495 binaries, such as the source control revision or other workspace-related information. You can use
1496 this mechanism with rules that support the <code>stamp</code> attribute, such as
1497 <code>genrule</code>, <code>cc_binary</code>, and more.
1498</p>
1499
ranjanih6a1a09f2021-03-10 15:39:14 -08001500<h4 id='flag--workspace_status_command'><code class='flag'>--workspace_status_command=<var>program</var></code></h4>
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001501<p>
1502 This flag lets you specify a binary that Bazel runs before each build. The program can report
1503 information about the status of the workspace, such as the current source control revision.
1504</p>
1505<p>
1506 The flag's value must be a path to a native program. On Linux/macOS this may be any executable.
1507 On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file.
1508</p>
1509
1510<p>
1511 The program should print zero or more key/value pairs to standard output, one entry on each line,
1512 then exit with zero (otherwise the build fails). The key names can be anything but they may only
1513 use upper case letters and underscores. The first space after the key name separates it from the
jhorvitz2a5bf222020-11-30 14:05:02 -08001514 value. The value is the rest of the line (including additional whitespaces). Neither the key nor
1515 the value may span multiple lines. Keys must not be duplicated.
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001516</p>
1517<p>
1518 Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and
1519 "volatile" are a bit counter-intuitive, so don't think much about them.)
1520</p>
1521
1522<p>Bazel then writes the key-value pairs into two files:</p>
1523<ul>
1524 <li>
ahumesky5a6d8b62018-11-15 14:05:34 -08001525 <code>bazel-out/stable-status.txt</code>
1526 contains all keys and values where the key's name starts with <code>STABLE_</code>
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001527 </li>
ahumesky5a6d8b62018-11-15 14:05:34 -08001528 <li>
1529 <code>bazel-out/volatile-status.txt</code>
1530 contains the rest of the keys and their values
1531 </li>
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001532</ul>
1533
1534<p>The contract is:</p>
1535<ul>
1536 <li>
1537 <p>
1538 "stable" keys' values should change rarely, if possible. If the contents of
ahumesky5a6d8b62018-11-15 14:05:34 -08001539 <code>bazel-out/stable-status.txt</code>
1540 change, Bazel invalidates the actions that depend on them. In
1541 other words, if a stable key's value changes, Bazel will rerun stamped actions.
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001542 Therefore the stable status should not contain things like timestamps, because they change all
ahumesky5a6d8b62018-11-15 14:05:34 -08001543 the time, and would make Bazel rerun stamped actions with each build.
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001544 </p>
1545 <p>Bazel always outputs the following stable keys:</p>
1546 <ul>
1547 <li><code>BUILD_EMBED_LABEL</code>: value of <code class='flag'>--embed_label</code></li>
1548 <li><code>BUILD_HOST</code>: the name of the host machine that Bazel is running on</li>
1549 <li><code>BUILD_USER</code>: the name of the user that Bazel is running as</li>
1550 </ul>
1551 </li>
1552 <li>
1553 <p>
1554 "volatile" keys' values may change often. Bazel expects them to change all the time, like
ahumesky5a6d8b62018-11-15 14:05:34 -08001555 timestamps do, and duly updates the
David McNettfa388c32019-05-16 13:16:56 -07001556 <code>bazel-out/volatile-status.txt</code>
ahumesky5a6d8b62018-11-15 14:05:34 -08001557 file. In order to avoid
1558 rerunning stamped actions all the time though, <b>Bazel pretends that the volatile file never
1559 changes</b>. In other words, if the volatile status file is the only file whose contents has
1560 changed, Bazel will not invalidate actions that depend on it. If other inputs of the actions
1561 have changed, then Bazel reruns that action, and the action will see the updated volatile
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001562 status, but just the volatile status changing alone will not invalidate the action.
1563 </p>
1564 <p>Bazel always outputs the following volatile keys:</p>
1565 <ul>
1566 <li>
lberki911c7c52018-04-25 07:56:27 -07001567 <code>BUILD_TIMESTAMP</code>: time of the build in seconds since the Unix Epoch (the value
1568 of <code>System.currentTimeMillis()</code> divided by a thousand)
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001569 </li>
1570 </ul>
1571 </li>
1572</ul>
1573
1574<p>
1575 On Linux/macOS you can pass <code class='flag'>--workspace_status_command=/bin/true</code> to
Googler956ecf62018-11-26 10:15:05 -08001576 disable retrieving workspace status, because <code>true</code> does nothing, successfully (exits
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001577 with zero) and prints no output. On Windows you can pass the path of MSYS's <code>true.exe</code>
1578 for the same effect.
1579</p>
1580
1581<p>If the workspace status command fails (exits non-zero) for any reason, the build will fail.</p>
1582
1583<p>Example program on Linux using Git:</p>
1584
1585<pre>
1586#!/bin/bash
1587echo "CURRENT_TIME $(date +%s)"
Googler98982a02020-07-29 10:16:10 -07001588echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)"
laszlocsomor45a0ffe2018-02-05 00:48:35 -08001589echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
1590echo "STABLE_USER_NAME $USER"
1591</pre>
1592
1593<p>
1594 Pass this program's path with <code>--workspace_status_command</code>, and the stable status file
1595 will include the STABLE lines and the volatile status file will include the rest of the lines.
1596</p>
1597
David Chen8fe82a32016-08-24 10:55:41 +00001598<h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4>
1599<p>
1600 This option controls whether stamping is enabled for
1601 rule types that support it. For most of the supported rule types stamping is
1602 enabled by default (e.g. <code>cc_binary</code>).
1603
1604 By default, stamping is disabled for all tests. Specifying
1605 <code class='flag'>--stamp</code> does not force affected targets to be rebuilt,
1606 if their dependencies have not changed.
1607</p>
1608
1609<p>
1610 Stamping can be enabled or disabled explicitly in BUILD using
1611 the <code>stamp</code> attribute of certain rule types, please refer to
1612 the <a href="be/overview.html">build encyclopedia</a> for details. For
1613 rules that are neither explicitly or implicitly configured as <code>stamp =
1614 0</code> or <code>stamp = 1</code>, the <code class='flag'>--[no]stamp</code> option
1615 selects whether stamping is enabled. Bazel never stamps binaries that are
1616 built for the host configuration, regardless of the stamp attribute.
1617</p>
1618
brandjoncf0390b2020-02-20 10:37:40 -08001619<h3 id='platform_build_options'>Platform</h3>
jcaterbf57a0a2018-06-13 10:16:31 -07001620
1621<p>
1622 Use these options to control the host and target platforms that configure how builds work, and to
1623 control what execution platforms and toolchains are available to Bazel rules.
1624</p>
1625
1626<p>
1627 Please see background information on
1628 <a href="platforms.html">Platforms</a> and <a href="toolchains.html">Toolchains</a>.
1629</p>
1630
ranjanih6a1a09f2021-03-10 15:39:14 -08001631<h4 id="flag--platforms"><code class='flag'>--platforms=<var>labels</var></code></h4>
jcaterbf57a0a2018-06-13 10:16:31 -07001632<p>
1633 The labels of the platform rules describing the target platforms for the
1634 current command.
1635</p>
1636
ranjanih6a1a09f2021-03-10 15:39:14 -08001637<h4 id="flag--host_platform"><code class='flag'>--host_platform=<var>label</var></code></h4>
jcaterbf57a0a2018-06-13 10:16:31 -07001638<p>
1639 The label of a platform rule that describes the host system.
1640</p>
1641
ranjanih6a1a09f2021-03-10 15:39:14 -08001642<h4 id="flag--extra_execution_platforms"><code class='flag'>--extra_execution_platforms=<var>labels</var></code></h4>
jcaterbf57a0a2018-06-13 10:16:31 -07001643<p>
1644 The platforms that are available as execution platforms to run actions.
1645 Platforms can be specified by exact target, or as a target pattern. These
1646 platforms will be considered before those declared in the WORKSPACE file by
Jingwen Chen0f4544d2018-12-14 16:28:16 -08001647 <a href="skylark/lib/globals.html#register_execution_platforms">
jcaterbf57a0a2018-06-13 10:16:31 -07001648 register_execution_platforms()</a>.
1649</p>
1650
ranjanih6a1a09f2021-03-10 15:39:14 -08001651<h4 id="flag--extra_toolchains"><code class='flag'>--extra_toolchains=<var>labels</var></code></h4>
jcaterbf57a0a2018-06-13 10:16:31 -07001652<p>
1653 The toolchain rules to be considered during toolchain resolution. Toolchains
1654 can be specified by exact target, or as a target pattern. These toolchains will
1655 be considered before those declared in the WORKSPACE file by
Jingwen Chen0f4544d2018-12-14 16:28:16 -08001656 <a href="skylark/lib/globals.html#register_toolchains">
jcaterbf57a0a2018-06-13 10:16:31 -07001657 register_toolchains()</a>.
1658</p>
1659
John Caterfbf9f9d2021-03-11 17:22:48 -08001660<h4 id="flag--toolchain_resolution_debug"><code class='flag'>--toolchain_resolution_debug=<var>regex</var></code></h4>
jcaterbf57a0a2018-06-13 10:16:31 -07001661<p>
John Caterfbf9f9d2021-03-11 17:22:48 -08001662 Print debug information while finding toolchains if the toolchain type matches
1663 the regex. Multiple regexes can be separated by commas. The regex can be
1664 negated by using a <code>-</code> at the beginning. This might help developers
1665 of Bazel or Starlark rules with debugging failures due to missing toolchains.
jcaterbf57a0a2018-06-13 10:16:31 -07001666</p>
1667
brandjoncf0390b2020-02-20 10:37:40 -08001668<h3 id='misc_build_options'>Miscellaneous</h3>
David Chen8fe82a32016-08-24 10:55:41 +00001669
ranjanih6a1a09f2021-03-10 15:39:14 -08001670<h4 id='flag--flag_alias'><code class='flag'>--flag_alias=<var>alias_name=target_path</var></code></h4>
warkahscott057ae962020-10-16 13:21:25 -07001671<p>
1672 A convenience flag used to bind longer Starlark build settings to a shorter name. For more
1673 details, see the
1674 <a href=https://docs.bazel.build/versions/master/skylark/config.html#using-build-setting-aliases">Starlark Configurations</a>.
1675</p>
1676
ranjanih6a1a09f2021-03-10 15:39:14 -08001677<h4 id='flag--symlink_prefix'><code class='flag'>--symlink_prefix=<var>string</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001678<p>
1679 Changes the prefix of the generated convenience symlinks. The
1680 default value for the symlink prefix is <code>bazel-</code> which
1681 will create the symlinks <code>bazel-bin</code>, <code>bazel-testlogs</code>, and
1682 <code>bazel-genfiles</code>.
1683</p>
1684<p>
1685 If the symbolic links cannot be created for any reason, a warning is
Googler0e692fb2021-01-22 18:38:24 +01001686 issued but the build is still considered a success. In particular,
David Chen8fe82a32016-08-24 10:55:41 +00001687 this allows you to build in a read-only directory or one that you have no
Googler0e692fb2021-01-22 18:38:24 +01001688 permission to write into. Any paths printed in informational
David Chen8fe82a32016-08-24 10:55:41 +00001689 messages at the conclusion of a build will only use the
1690 symlink-relative short form if the symlinks point to the expected
1691 location; in other words, you can rely on the correctness of those
1692 paths, even if you cannot rely on the symlinks being created.
1693</p>
1694<p>
1695 Some common values of this option:
1696</p>
1697<ul>
1698
1699 <li>
1700 <p><b>Suppress symlink creation:</b>
1701 <code class='flag'>--symlink_prefix=/</code> will cause Bazel to not
1702 create or update any symlinks, including the <code>bazel-out</code> and
1703
1704 <code>bazel-&lt;workspace&gt;</code>
Googler0e692fb2021-01-22 18:38:24 +01001705 symlinks. Use this option to suppress symlink creation entirely.
David Chen8fe82a32016-08-24 10:55:41 +00001706 </p>
1707 </li>
1708 <li>
1709 <p><b>Reduce clutter:</b>
1710 <code class='flag'>--symlink_prefix=.bazel/</code> will cause Bazel to create
1711 symlinks called <code>bin</code> (etc) inside a hidden directory <code>.bazel</code>.
1712 </p>
1713 </li>
1714</ul>
1715
ranjanih6a1a09f2021-03-10 15:39:14 -08001716<h4 id='flag--platform_suffix'><code class='flag'>--platform_suffix=<var>string</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001717<p>
1718 Adds a suffix to the configuration short name, which is used to determine the
1719 output directory. Setting this option to different values puts the files into
1720 different directories, for example to improve cache hit rates for builds that
1721 otherwise clobber each others output files, or to keep the output files around
1722 for comparisons.
1723</p>
1724
1725<h4 id='flag--default_visibility'><code class='flag'>--default_visibility=<var>(private|public)</var></code></h4>
1726<p>
Googler0e692fb2021-01-22 18:38:24 +01001727 Temporary flag for testing bazel default visibility changes. Not intended for general use
David Chen8fe82a32016-08-24 10:55:41 +00001728 but documented for completeness' sake.
1729</p>
1730
Googler23471692017-06-02 11:26:16 -04001731<h4 id='flag--use_action_cache'><code class='flag'>--[no]use_action_cache</code></h4>
1732<p>
Googler0e692fb2021-01-22 18:38:24 +01001733 This option is enabled by default. If disabled, Bazel will not use its local action cache.
Googler23471692017-06-02 11:26:16 -04001734 Disabling the local action cache saves memory and disk space for clean builds, but will make
1735 incremental builds slower.
1736</p>
1737
adonovan329ec6d2020-02-06 15:34:49 -08001738<h4 id='flag--starlark_cpu_profile'><code class='flag'>--starlark_cpu_profile=<i>file</i></code></h4>
1739<p>
1740 This flag, whose value is the name of a file, causes Bazel to gather
1741 statistics about CPU usage by all Starlark threads,
1742 and write the profile, in <a href='https://github.com/google/pprof'>pprof</a> format,
1743 to the named file.
1744
1745 Use this option to help identify Starlark functions that
1746 make loading and analysis slow due to excessive computation. For example:
1747</p>
1748<pre>
1749$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
1750$ pprof /tmp/pprof.gz
1751(pprof) top
1752Type: CPU
1753Time: Feb 6, 2020 at 12:06pm (PST)
1754Duration: 5.26s, Total samples = 3.34s (63.55%)
1755Showing nodes accounting for 3.34s, 100% of 3.34s total
1756 flat flat% sum% cum cum%
1757 1.86s 55.69% 55.69% 1.86s 55.69% sort_source_files
1758 1.02s 30.54% 86.23% 1.02s 30.54% expand_all_combinations
1759 0.44s 13.17% 99.40% 0.44s 13.17% range
1760 0.02s 0.6% 100% 3.34s 100% sorted
1761 0 0% 100% 1.38s 41.32% my/project/main/BUILD
1762 0 0% 100% 1.96s 58.68% my/project/library.bzl
1763 0 0% 100% 3.34s 100% main
1764</pre>
1765<p>
1766 For different views of the same data, try the <code>pprof</code> commands <code>svg</code>,
1767 <code>web</code>, and <code>list</code>.
1768</p>
1769
David Chen8fe82a32016-08-24 10:55:41 +00001770<h2 id='bazel-releng'>Using Bazel for releases</h2>
1771<p>
1772 Bazel is used both by software engineers during the development
1773 cycle, and by release engineers when preparing binaries for deployment
Googler0e692fb2021-01-22 18:38:24 +01001774 to production. This section provides a list of tips for release
David Chen8fe82a32016-08-24 10:55:41 +00001775 engineers using Bazel.
1776
1777</p>
1778
1779<h3>Significant options</h3>
1780
1781<p>
1782 When using Bazel for release builds, the same issues arise as for
1783 other scripts that perform a build, so you should read
Googler59830672019-01-03 10:33:49 -08001784 the <a href='guide.html#scripting'>scripting</a> section of this manual.
David Chen8fe82a32016-08-24 10:55:41 +00001785 In particular, the following options are strongly recommended:
1786</p>
1787<ul>
Vladimir Chebotarev66885ff2018-12-04 14:08:16 -08001788 <li><a href='guide.html#bazelrc'><code class='flag'>--bazelrc=/dev/null</code></a></li>
ccalvarinaf8b7722018-06-06 11:54:00 -07001789 <li><a href='#flag--keep_state_after_build'><code class='flag'>--nokeep_state_after_build</code></a></li>
David Chen8fe82a32016-08-24 10:55:41 +00001790</ul>
1791
1792<p>
brandjoncf0390b2020-02-20 10:37:40 -08001793 These options are also important:
David Chen8fe82a32016-08-24 10:55:41 +00001794</p>
1795
1796<ul>
1797
1798 <li><a href='#flag--package_path'><code class='flag'>--package_path</code></a></li>
1799 <li><a href='#flag--symlink_prefix'><code class='flag'>--symlink_prefix</code></a>:
1800 for managing builds for multiple configurations,
1801 it may be convenient to distinguish each build
Googler0e692fb2021-01-22 18:38:24 +01001802 with a distinct identifier, e.g. "64bit" vs. "32bit". This option
David Chen8fe82a32016-08-24 10:55:41 +00001803 differentiates the <code>bazel-bin</code> (etc.) symlinks.
1804 </li>
1805</ul>
1806
brandjoncf0390b2020-02-20 10:37:40 -08001807<h2 id='test'>Running tests</h2>
David Chen8fe82a32016-08-24 10:55:41 +00001808<p>
1809 To build and run tests with bazel, type <code>bazel test</code> followed by
1810 the name of the test targets.
1811</p>
1812<p>
1813 By default, this command performs simultaneous build and test
1814 activity, building all specified targets (including any non-test
1815 targets specified on the command line) and testing
1816 <code>*_test</code> and <code>test_suite</code> targets as soon as
1817 their prerequisites are built, meaning that test execution is
1818 interleaved with building. Doing so usually results in significant
1819 speed gains.
1820
1821</p>
1822
1823<h3>Options for <code>bazel test</code></h3>
1824
1825<h4 id="flag--cache_test_results"><code class='flag'>--cache_test_results=(yes|no|auto)</code> (<code>-t</code>)</h4>
1826<p>
1827 If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the
1828 following conditions applies:
1829</p>
1830<ul>
1831 <li>Bazel detects changes in the test or its dependencies</li>
1832 <li>the test is marked as <code>external</code></li>
1833 <li>multiple test runs were requested with <code class='flag'>--runs_per_test</code></li>
1834 <li>the test failed.</li>
1835</ul>
1836<p>
1837 If 'no', all tests will be executed unconditionally.
1838</p>
1839<p>
1840 If 'yes', the caching behavior will be the same as auto
1841 except that it may cache test failures and test runs with
1842 <code class='flag'>--runs_per_test</code>.
1843</p>
1844<p>
1845 Note that test results are <em>always</em> saved in Bazel's output tree,
1846 regardless of whether this option is enabled, so
1847 you needn't have used <code class='flag'>--cache_test_results</code> on the
1848 prior run(s) of <code>bazel test</code> in order to get cache hits.
1849 The option only affects whether Bazel will <em>use</em> previously
1850 saved results, not whether it will save results of the current run.
1851</p>
1852<p>
1853 Users who have enabled this option by default in
1854 their <code>.bazelrc</code> file may find the
1855 abbreviations <code>-t</code> (on) or <code>-t-</code> (off)
1856 convenient for overriding the default on a particular run.
1857</p>
1858
1859<h4 id="flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></h4>
1860<p>
1861 This option tells Bazel not to run the tests, but to merely check and report
Googler0e692fb2021-01-22 18:38:24 +01001862 the cached test results. If there are any tests which have not been
David Chen8fe82a32016-08-24 10:55:41 +00001863 previously built and run, or whose tests results are out-of-date (e.g. because
1864 the source code or the build options have changed), then Bazel will report
1865 an error message ("test result is not up-to-date"), will record the test's
1866 status as "NO STATUS" (in red, if color output is enabled), and will return
1867 a non-zero exit code.
1868</p>
1869<p>
1870 This option also implies
1871 <code><a href="#flag--check_up_to_date">--check_up_to_date</a></code> behavior.
1872</p>
1873<p>
1874 This option may be useful for pre-submit checks.
1875</p>
1876
1877<h4 id="flag--test_verbose_timeout_warnings"><code class='flag'>--test_verbose_timeout_warnings</code></h4>
1878<p>
1879 This option tells Bazel to explicitly warn the user if a test's timeout is
Googler0e692fb2021-01-22 18:38:24 +01001880significantly longer than the test's actual execution time. While a test's
David Chen8fe82a32016-08-24 10:55:41 +00001881timeout should be set such that it is not flaky, a test that has a highly
1882over-generous timeout can hide real problems that crop up unexpectedly.
1883</p>
1884<p>
1885For instance, a test that normally executes in a minute or two should not have
1886a timeout of ETERNAL or LONG as these are much, much too generous.
1887
1888 This option is useful to help users decide on a good timeout value or
1889 sanity check existing timeout values.
1890</p>
1891<p>
1892Note that each test shard is allotted the timeout of the entire
Googler0e692fb2021-01-22 18:38:24 +01001893<code>XX_test</code> target. Using this option does not affect a test's timeout
David Chen8fe82a32016-08-24 10:55:41 +00001894value, merely warns if Bazel thinks the timeout could be restricted further.
1895</p>
1896
1897<h4 id='flag--test_keep_going'><code class='flag'>--[no]test_keep_going</code></h4>
1898<p>
1899 By default, all tests are run to completion. If this flag is disabled,
1900 however, the build is aborted on any non-passing test. Subsequent build steps
1901 and test invocations are not run, and in-flight invocations are canceled.
1902 Do not specify both <code class='flag'>--notest_keep_going</code> and
1903 <code class='flag'>--keep_going</code>.
1904</p>
1905
ranjanih6a1a09f2021-03-10 15:39:14 -08001906<h4 id='flag--flaky_test_attempts'><code class='flag'>--flaky_test_attempts=<var>attempts</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001907<p>
1908 This option specifies the maximum number of times a test should be attempted
1909 if it fails for any reason. A test that initially fails but eventually
1910 succeeds is reported as <code>FLAKY</code> on the test summary. It is,
1911 however, considered to be passed when it comes to identifying Bazel exit code
1912 or total number of passed tests. Tests that fail all allowed attempts are
1913 considered to be failed.
1914</p>
1915<p>
1916 By default (when this option is not specified, or when it is set to
1917 &quot;default&quot;), only a single attempt is allowed for regular tests, and
1918 3 for test rules with the <code>flaky</code> attribute set. You can specify
1919 an integer value to override the maximum limit of test attempts. Bazel allows
1920 a maximum of 10 test attempts in order to prevent abuse of the system.
1921</p>
1922
ranjanih6a1a09f2021-03-10 15:39:14 -08001923<h4 id='flag--runs_per_test'><code class='flag'>--runs_per_test=<var>[regex@]number</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001924<p>
1925 This option specifies the number of times each test should be executed. All
1926 test executions are treated as separate tests (e.g. fallback functionality
1927 will apply to each of them independently).
1928</p>
1929<p>
1930 The status of a target with failing runs depends on the value of the
1931 <code>--runs_per_test_detects_flakes</code> flag:
1932</p>
1933<ul>
1934 <li>If absent, any failing run causes the entire test to fail.</li>
1935 <li>If present and two runs from the same shard return PASS and FAIL, the test
1936 will receive a status of flaky (unless other failing runs cause it to
1937 fail).</li>
1938</ul>
1939
1940<p>
1941 If a single number is specified, all tests will run that many times.
1942 Alternatively, a regular expression may be specified using the syntax
1943 regex@number. This constrains the effect of --runs_per_test to targets
1944 which match the regex (e.g. "--runs_per_test=^//pizza:.*@4" runs all tests
1945 under //pizza/ 4 times).
1946 This form of --runs_per_test may be specified more than once.
1947</p>
1948
1949<h4 id='flag--runs_per_test_detects_flakes'><code
1950 class='flag'>--[no]runs_per_test_detects_flakes</code></h4>
1951<p>
1952 If this option is specified (by default it is not), Bazel will detect flaky
1953 test shards through --runs_per_test. If one or more runs for a single shard
1954 fail and one or more runs for the same shard pass, the target will be
1955 considered flaky with the flag. If unspecified, the target will report a
1956 failing status.
1957</p>
1958
ranjanih6a1a09f2021-03-10 15:39:14 -08001959<h4 id='flag--test_summary'><code class='flag'>--test_summary=<var>output_style</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001960<p>
1961 Specifies how the test result summary should be displayed.
1962</p>
1963<ul>
1964 <li><code>short</code> prints the results of each test along with the name of
1965 the file containing the test output if the test failed. This is the default
1966 value.
1967 </li>
1968 <li><code>terse</code> like <code>short</code>, but even shorter: only print
1969 information about tests which did not pass.
1970 </li>
1971 <li><code>detailed</code> prints each individual test case that failed, not
1972 only each test. The names of test output files are omitted.
1973 </li>
1974 <li><code>none</code> does not print test summary.
1975 </li>
1976</ul>
1977
ranjanih6a1a09f2021-03-10 15:39:14 -08001978<h4 id='flag--test_output'><code class='flag'>--test_output=<var>output_style</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00001979<p>
1980 Specifies how test output should be displayed:
1981</p>
1982<ul>
1983 <li><code>summary</code> shows a summary of whether each test passed or
1984 failed. Also shows the output log file name for failed tests. The summary
1985 will be printed at the end of the build (during the build, one would see
1986 just simple progress messages when tests start, pass or fail).
1987 This is the default behavior.
1988 </li>
1989 <li><code>errors</code> sends combined stdout/stderr output from failed tests
1990 only into the stdout immediately after test is completed, ensuring that
1991 test output from simultaneous tests is not interleaved with each other.
1992 Prints a summary at the build as per summary output above.
1993 </li>
1994 <li><code>all</code> is similar to <code>errors</code> but prints output for
1995 all tests, including those which passed.
1996 </li>
1997 <li><code>streamed</code> streams stdout/stderr output from each test in
1998 real-time.
1999
2000 </li>
2001</ul>
2002
2003<h4 id='flag--java_debug'><code class='flag'>--java_debug</code></h4>
2004<p>
2005 This option causes the Java virtual machine of a java test to wait for a connection from a
2006 JDWP-compliant debugger before starting the test. This option implies --test_output=streamed.
2007</p>
2008
2009<h4 id='flag--verbose_test_summary'><code class='flag'>--[no]verbose_test_summary</code></h4>
2010<p>
2011 By default this option is enabled, causing test times and other additional
2012 information (such as test attempts) to be printed to the test summary. If
2013 <code class='flag'>--noverbose_test_summary</code> is specified, test summary will
2014 include only test name, test status and cached test indicator and will
2015 be formatted to stay within 80 characters when possible.
2016</p>
2017
ranjanih6a1a09f2021-03-10 15:39:14 -08002018<h4 id='flag--test_tmpdir'><code class='flag'>--test_tmpdir=<var>path</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00002019<p>
2020 Specifies temporary directory for tests executed locally. Each test will be
2021 executed in a separate subdirectory inside this directory. The directory will
2022 be cleaned at the beginning of the each <code>bazel test</code> command.
2023 By default, bazel will place this directory under Bazel output base directory.
2024 Note that this is a directory for running tests, not storing test results
2025 (those are always stored under the <code>bazel-out</code> directory).
2026</p>
2027
2028<h4 id='flag--test_timeout'>
ranjanih6a1a09f2021-03-10 15:39:14 -08002029 <code class='flag'>--test_timeout=
David Chen8fe82a32016-08-24 10:55:41 +00002030 <var>seconds</var></code>
2031 OR
ranjanih6a1a09f2021-03-10 15:39:14 -08002032 <code class='flag'>--test_timeout=
David Chen8fe82a32016-08-24 10:55:41 +00002033 <var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var>
2034 </code>
2035</h4>
2036<p>
2037 Overrides the timeout value for all tests by using specified number of
2038 seconds as a new timeout value. If only one value is provided, then it will
2039 be used for all test timeout categories.
2040 </p>
2041 <p>
2042 Alternatively, four comma-separated values may be provided, specifying
2043 individual timeouts for short, moderate, long and eternal tests (in that
2044 order).
2045 In either form, zero or a negative value for any of the test sizes will
2046 be substituted by the default timeout for the given timeout categories as
2047 defined by the page
2048 <a href="test-encyclopedia.html">Writing Tests</a>.
2049 By default, Bazel will use these timeouts for all tests by
2050 inferring the timeout limit from the test's size whether the size is
2051 implicitly or explicitly set.
2052</p>
2053<p>
2054 Tests which explicitly state their timeout category as distinct from their
2055 size will receive the same value as if that timeout had been implicitly set by
Googler0e692fb2021-01-22 18:38:24 +01002056 the size tag. So a test of size 'small' which declares a 'long' timeout will
David Chen8fe82a32016-08-24 10:55:41 +00002057 have the same effective timeout that a 'large' tests has with no explicit
2058 timeout.
2059</p>
2060
ranjanih6a1a09f2021-03-10 15:39:14 -08002061<h4 id='flag--test_arg'><code class='flag'>--test_arg=<var>arg</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00002062<p>
Michael Staib3df106e2017-02-23 23:08:40 +00002063 Passes command-line options/flags/arguments to each test process. This
David Chen8fe82a32016-08-24 10:55:41 +00002064 option can be used multiple times to pass several arguments, e.g.
2065 <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>.
2066</p>
2067
ranjanih6a1a09f2021-03-10 15:39:14 -08002068<h4 id='flag--test_env'><code class='flag'>--test_env=<var>variable</var>=<i>value</i></code>
David Chen8fe82a32016-08-24 10:55:41 +00002069 OR
ranjanih6a1a09f2021-03-10 15:39:14 -08002070 <code class='flag'>--test_env=<var>variable</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00002071<p>
2072 Specifies additional variables that must be injected into the test
2073 environment for each test. If <var>value</var> is not specified it will be
2074 inherited from the shell environment used to start the <code>bazel test</code>
2075 command.
2076</p>
2077<p>
2078 The environment can be accessed from within a test by using
2079 <code>System.getenv("var")</code> (Java),
2080 <code>getenv("var")</code> (C or C++),
2081
2082</p>
2083
2084<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
2085<p>
2086 This specifies a prefix that the test runner will insert in front
Googler0e692fb2021-01-22 18:38:24 +01002087 of the test command before running it. The
David Chen8fe82a32016-08-24 10:55:41 +00002088 <var>command-prefix</var> is split into words using Bourne shell
2089 tokenization rules, and then the list of words is prepended to the
2090 command that will be executed.
2091</p>
2092<p>
Googlera0f79b12018-11-29 06:31:16 -08002093 If the first word is a fully-qualified label (i.e. starts with
David Chen8fe82a32016-08-24 10:55:41 +00002094 <code>//</code>) it is built. Then the label is substituted by the
2095 corresponding executable location that is prepended to the command
2096 that will be executed along with the other words.
2097</p>
2098
2099<p>
2100Some caveats apply:
2101</p>
2102<ul>
2103 <li>
2104 The PATH used for running tests may be different than the PATH in your environment,
2105 so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code>
2106 command (the first word in <var>command-prefix</var>).
2107 </li>
2108 <li>
2109 <b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code>
2110 can't be used for interactive commands.
2111 </li>
2112
2113</ul>
2114<p>
2115Examples:
2116</p>
2117<pre>
David Chen8fe82a32016-08-24 10:55:41 +00002118 --run_under=/usr/bin/strace
2119 --run_under='/usr/bin/strace -c'
ckennellyaee19e12020-04-15 10:15:47 -07002120 --run_under=/usr/bin/valgrind
David Chen8fe82a32016-08-24 10:55:41 +00002121 --run_under='/usr/bin/valgrind --quiet --num-callers=20'
David Chen8fe82a32016-08-24 10:55:41 +00002122</pre>
2123
2124<h4>Test selection</h4>
2125<p>
2126 As documented under <a href='#output-selection-options'>Output selection options</a>,
2127 you can filter tests by <a href='#flag--test_size_filters'>size</a>,
2128 <a href='#flag--test_timeout_filters'>timeout</a>,
2129 <a href='#flag--test_tag_filters'>tag</a>, or
2130 <a href='#flag--test_lang_filters'>language</a>. A convenience
2131 <a href='#flag--test_filter'>general name filter</a> can forward particular
2132 filter args to the test runner.
2133</p>
2134
kchodorowfae5c742017-03-28 16:53:24 +00002135<h4 id="other_options_for_bazel_test">Other options for <code>bazel test</code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00002136<p>
2137 The syntax and the remaining options are exactly like
Googler59830672019-01-03 10:33:49 -08002138 <a href='guide.html#build'>bazel build</a>.
David Chen8fe82a32016-08-24 10:55:41 +00002139</p>
2140
2141
brandjoncf0390b2020-02-20 10:37:40 -08002142<h3 id='clean'>Cleaning build outputs</h3>
laurentlbc85de9c2018-11-05 08:30:36 -08002143
2144<h4>The <code>clean</code> command</h4>
2145
2146<p>
2147 Bazel has a <code>clean</code> command, analogous to that of Make.
2148 It deletes the output directories for all build configurations performed
2149 by this Bazel instance, or the entire working tree created by this
2150 Bazel instance, and resets internal caches. If executed without any
2151 command-line options, then the output directory for all configurations
2152 will be cleaned.
2153</p>
2154
2155<p>Recall that each Bazel instance is associated with a single workspace, thus the
2156 <code>clean</code> command will delete all outputs from all builds you've done
2157 with that Bazel instance in that workspace.
2158</p>
2159<p>
2160 To completely remove the entire working tree created by a Bazel
2161 instance, you can specify the <code class='flag'>--expunge</code> option. When
2162 executed with <code class='flag'>--expunge</code>, the clean command simply
2163 removes the entire output base tree which, in addition to the build
2164 output, contains all temp files created by Bazel. It also
2165 stops the Bazel server after the clean, equivalent to the <a
2166 href='#shutdown'><code>shutdown</code></a> command. For example, to
2167 clean up all disk and memory traces of a Bazel instance, you could
2168 specify:
2169</p>
2170<pre>
2171 % bazel clean --expunge
2172</pre>
2173<p>
2174 Alternatively, you can expunge in the background by using
2175 <code class='flag'>--expunge_async</code>. It is safe to invoke a Bazel command
2176 in the same client while the asynchronous expunge continues to run.
2177 Note, however, that this may introduce IO contention.
2178</p>
2179
2180<p>
2181 The <code>clean</code> command is provided primarily as a means of
2182 reclaiming disk space for workspaces that are no longer needed.
Googler03fd5412021-03-11 18:57:14 -08002183 Bazel's incremental rebuilds may not be
2184 perfect so <code>clean</code> can be used to recover a consistent
laurentlbc85de9c2018-11-05 08:30:36 -08002185 state when problems arise.
2186</p>
2187<p>
Googler03fd5412021-03-11 18:57:14 -08002188 Bazel's design is such that these problems are fixable and
2189 these bugs are a high priority to be fixed. If you
2190 ever find an incorrect incremental build, file a bug report, and report bugs in the tools
2191 rather than using <code>clean</code>.
laurentlbc85de9c2018-11-05 08:30:36 -08002192</p>
2193
brandjoncf0390b2020-02-20 10:37:40 -08002194<h2 id='run'>Running executables</h2>
David Chen8fe82a32016-08-24 10:55:41 +00002195<p>
2196 The <code>bazel run</code> command is similar to <code>bazel build</code>, except
Googler0e692fb2021-01-22 18:38:24 +01002197 it is used to build <em>and run</em> a single target. Here is a typical session:
David Chen8fe82a32016-08-24 10:55:41 +00002198</p>
2199<pre>
2200 % bazel run -- java/myapp:myapp --arg1 --arg2
2201 Welcome to Bazel
2202 INFO: Loading package: java/myapp
2203 INFO: Loading package: foo/bar
2204 INFO: Loading complete. Analyzing...
2205 INFO: Found 1 target...
2206 ...
2207 Target //java/myapp:myapp up-to-date:
2208 bazel-bin/java/myapp:myapp
2209 INFO: Elapsed time: 0.638s, Critical Path: 0.34s
2210
2211 INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2
2212 Hello there
2213 $EXEC_ROOT/java/myapp/myapp
2214 --arg1
2215 --arg2
2216</pre>
2217
2218<p>
Googler0e692fb2021-01-22 18:38:24 +01002219 Note the use of the <code>--</code>. This is needed so that Bazel
David Chen8fe82a32016-08-24 10:55:41 +00002220 does not interpret <code>--arg1</code> and <code>--arg2</code> as
2221 Bazel options, but rather as part of the command line for running the binary.
2222 (The program being run simply says hello and prints out its args.)
2223</p>
2224
diamondme42913a2019-01-24 16:11:30 -08002225<p><code>bazel run</code> is similar, but not identical, to directly invoking
lberki749e8052019-02-12 04:23:43 -08002226the binary built by Bazel and its behavior is different depending on whether the
2227binary to be invoked is a test or not.
2228
2229When the binary is not a test, the current working directory will be the
2230runfiles tree of the binary.
2231
2232When the binary is a test, the current working directory will be the exec root
2233and a good-faith attempt is made to replicate the environment tests are usually
2234run in. The emulation is not perfect, though, and tests that have multiple
2235shards cannot be run this way (the
2236<code>--test_sharding_strategy=disabled</code> command line option can be used
2237to work around this)
2238
2239The following extra environment variables are also available to the binary:
2240<ul>
2241 <li>
2242 <code>BUILD_WORKSPACE_DIRECTORY</code>: the root of the workspace where the
2243 build was run.
2244 </li>
2245 <li>
2246 <code>BUILD_WORKING_DIRECTORY</code>: the current working directory where
2247 Bazel was run from.
2248 </li>
2249</ul>
2250
2251These can be used, for example, to interpret file names on the command line in
2252a user-friendly way.
diamondme42913a2019-01-24 16:11:30 -08002253
David Chen8fe82a32016-08-24 10:55:41 +00002254<h3>Options for <code>bazel run</code></h3>
2255
2256<h4 id='flag--run_under_run'><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
2257<p>
2258 This has the same effect as the <code class='flag'>--run_under</code> option for
2259 <code>bazel test</code> (<a href='#flag--run_under'>see above</a>),
2260 except that it applies to the command being run by <code>bazel
2261 run</code> rather than to the tests being run by <code>bazel test</code>
2262 and cannot run under label.
2263</p>
2264
2265<h3>Executing tests</h3>
2266
2267<p>
2268 <code>bazel run</code> can also execute test binaries, which has the effect of
lberki5a2238d2018-05-18 03:15:32 -07002269 running the test in a close approximation of the environment described at
2270 <a href='test-encyclopedia.html'>Writing Tests</a>. Note that none of the
Googlere5197f72020-02-25 16:38:17 -08002271 <code>--test_*</code> arguments have an effect when running a test in this manner except
lberki5a2238d2018-05-18 03:15:32 -07002272 <code>--test_arg</code> .
David Chen8fe82a32016-08-24 10:55:41 +00002273</p>
2274
brandjoncf0390b2020-02-20 10:37:40 -08002275<h2 id='query'>Querying the dependency graph</h2>
David Chen8fe82a32016-08-24 10:55:41 +00002276
2277<p>
2278 Bazel includes a query language for asking questions about the
Googler0e692fb2021-01-22 18:38:24 +01002279 dependency graph used during the build. The query language is used
juliexxiaa8082fc2018-03-15 09:58:51 -07002280 by two commands: query and cquery. The major difference between the
Googler59830672019-01-03 10:33:49 -08002281 two commands is that query runs after the <a href='guide.html#loading-phase'>loading phase</a>
2282 and cquery runs after the <a href='guide.html#analysis-phase'>analysis phase</a>. These tools are an
David Chen8fe82a32016-08-24 10:55:41 +00002283 invaluable aid to many software engineering tasks.
2284</p>
2285<p>
2286 The query language is based on the idea of
2287 algebraic operations over graphs; it is documented in detail in
2288
2289 <a href="query.html">Bazel Query Reference</a>.
2290 Please refer to that document for reference, for
2291 examples, and for query-specific command-line options.
2292</p>
2293
2294<p>
2295 The query tool accepts several command-line
Googler0e692fb2021-01-22 18:38:24 +01002296 option. <code class='flag'>--output</code> selects the output format.
David Chen8fe82a32016-08-24 10:55:41 +00002297 <code class='flag'>--[no]keep_going</code> (disabled by default) causes the query
2298 tool to continue to make progress upon errors; this behavior may be
2299 disabled if an incomplete result is not acceptable in case of errors.
2300</p>
2301<p>
wtroberts5a0cf9b2019-09-06 07:55:15 -07002302 The <code class='flag'>--[no]tool_deps</code> option,
2303 enabled by default, causes dependencies in non-target configurations to be included in the
2304 dependency graph over which the query operates.
David Chen8fe82a32016-08-24 10:55:41 +00002305
2306</p>
2307<p>
2308 The <code class='flag'>--[no]implicit_deps</code> option, enabled by default, causes
2309 implicit dependencies to be included in the dependency graph over which the query operates. An
2310 implicit dependency is one that is not explicitly specified in the BUILD file
2311 but added by bazel.
2312</p>
2313<p>
2314 Example: "Show the locations of the definitions (in BUILD files) of
2315 all genrules required to build all the tests in the PEBL tree."
2316</p>
2317<pre>
2318 bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
2319</pre>
2320
brandjoncf0390b2020-02-20 10:37:40 -08002321<h2 id='aquery'>Querying the action graph</h2>
twerthe7fcab32018-08-09 08:03:41 -07002322
2323<b>Caution</b>: The aquery command is still experimental and its API will change.
2324
2325<p>
2326 The <code>aquery</code> command allows you to query for actions in your build graph.
2327 It operates on the post-analysis configured target graph and exposes
2328 information about actions, artifacts and their relationships.
2329</p>
2330
2331<p>
2332 The tool accepts several command-line options.
twerth420b9532018-12-14 06:16:58 -08002333 <code class='flag'>--output</code> selects the output format. The default output format
2334 (<code>text</code>) is human-readable, use <code>proto</code> or <code>textproto</code> for
2335 machine-readable format.
twerthe7fcab32018-08-09 08:03:41 -07002336 Notably, the aquery command runs on top of a regular Bazel build and inherits
2337 the set of options available during a build.
2338</p>
2339
2340<p>
2341 It supports the same set of functions that is also available to traditional
2342 <code>query</code> but <code>siblings</code>, <code>buildfiles</code> and
2343 <code>tests</code>.
2344</p>
David Chen8fe82a32016-08-24 10:55:41 +00002345
leba367d42d2019-01-10 02:30:47 -08002346<p>
2347 More details on aquery can be found <a href="aquery.html">here</a>.
2348</p>
2349
brandjoncf0390b2020-02-20 10:37:40 -08002350<h2 id='misc'>Miscellaneous commands and options</h2>
David Chen8fe82a32016-08-24 10:55:41 +00002351
brandjoncf0390b2020-02-20 10:37:40 -08002352<h3 id='help'><code>help</code></h3>
David Chen8fe82a32016-08-24 10:55:41 +00002353
2354<p>
Googler0e692fb2021-01-22 18:38:24 +01002355 The <code>help</code> command provides on-line help. By default, it
David Chen8fe82a32016-08-24 10:55:41 +00002356 shows a summary of available commands and help topics, as shown in
Googler59830672019-01-03 10:33:49 -08002357 the <a href='guide.html#overview'><i>Bazel overview</i></a> section above.
David Chen8fe82a32016-08-24 10:55:41 +00002358 Specifying an argument displays detailed help for a particular
Googler0e692fb2021-01-22 18:38:24 +01002359 topic. Most topics are Bazel commands, e.g. <code>build</code>
David Chen8fe82a32016-08-24 10:55:41 +00002360 or <code>query</code>, but there are some additional help topics
2361 that do not correspond to commands.
2362</p>
2363
2364<h4 id='flag--long'><code class='flag'>--[no]long</code> (<code>-l</code>)</h4>
2365<p>
2366 By default, <code>bazel help [<var>topic</var>]</code> prints only a
Googler0e692fb2021-01-22 18:38:24 +01002367 summary of the relevant options for a topic. If
David Chen8fe82a32016-08-24 10:55:41 +00002368 the <code class='flag'>--long</code> option is specified, the type, default value
2369 and full description of each option is also printed.
2370</p>
2371
brandjoncf0390b2020-02-20 10:37:40 -08002372<h3 id='shutdown'><code>shutdown</code></h3>
David Chen8fe82a32016-08-24 10:55:41 +00002373
2374<p>
Googler59830672019-01-03 10:33:49 -08002375 Bazel server processes (see <a href='guide.html#client/server'>Client/server
David Chen8fe82a32016-08-24 10:55:41 +00002376 implementation</a>) may be stopped by using the <code>shutdown</code>
Googler0e692fb2021-01-22 18:38:24 +01002377 command. This command causes the Bazel server to exit as soon as it
David Chen8fe82a32016-08-24 10:55:41 +00002378 becomes idle (i.e. after the completion of any builds or other
2379 commands that are currently in progress).
2380
2381 Bazel servers stop themselves after an idle timeout, so this command
2382 is rarely necessary; however, it can be useful in scripts when it is
2383 known that no further builds will occur in a given workspace.
2384</p>
2385<p>
2386 <code>shutdown</code> accepts one
2387 option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which
Googler0e692fb2021-01-22 18:38:24 +01002388 requires an integer argument (in MB). If specified, this makes the shutdown
2389 conditional on the amount of memory already consumed. This is
David Chen8fe82a32016-08-24 10:55:41 +00002390 useful for scripts that initiate a lot of builds, as any memory
2391 leaks in the Bazel server could cause it to crash spuriously on
2392 occasion; performing a conditional restart preempts this condition.
2393</p>
2394
brandjoncf0390b2020-02-20 10:37:40 -08002395<h3 id='info'><code>info</code></h3>
David Chen8fe82a32016-08-24 10:55:41 +00002396
2397<p>
2398 The <code>info</code> command prints various values associated with
2399 the Bazel server instance, or with a specific build configuration.
2400 (These may be used by scripts that drive a build.)
2401</p>
2402
2403<p>
2404 The <code>info</code> command also permits a single (optional)
2405 argument, which is the name of one of the keys in the list below.
2406 In this case, <code>bazel info <var>key</var></code> will print only
Googler0e692fb2021-01-22 18:38:24 +01002407 the value for that one key. (This is especially convenient when
David Chen8fe82a32016-08-24 10:55:41 +00002408 scripting Bazel, as it avoids the need to pipe the result
2409 through <code>sed -ne /key:/s/key://p</code>:
2410</p>
2411
2412<h4>Configuration-independent data</h4>
2413<ul>
2414 <li><code>release</code>: the release label for this Bazel
2415 instance, or "development version" if this is not a released
2416 binary.
2417 </li>
2418 <li><code>workspace</code> the absolute path to the base workspace
2419 directory.
2420 </li>
2421 <li><code>install_base</code>: the absolute path to the installation
2422 directory used by this Bazel instance for the current user. Bazel
2423 installs its internally required executables below this directory.
2424
2425 </li>
2426 <li><code>output_base</code>: the absolute path to the base output
2427 directory used by this Bazel instance for the current user and
2428 workspace combination. Bazel puts all of its scratch and build
2429 output below this directory.
2430 </li>
2431 <li><code>execution_root</code>: the absolute path to the execution
2432 root directory under output_base. This directory is the root for all files
2433 accessible to commands executed during the build, and is the working
2434 directory for those commands. If the workspace directory is writable, a
2435 symlink named
2436
2437 <code>bazel-&lt;workspace&gt;</code>
2438 is placed there pointing to this directory.
2439 </li>
2440 <li><code>output_path</code>: the absolute path to the output
2441 directory beneath the execution root used for all files actually
2442 generated as a result of build commands. If the workspace directory is
2443 writable, a symlink named <code>bazel-out</code> is placed there pointing
2444 to this directory.
nharmataa3a7dad2020-03-30 10:42:05 -07002445 </li>
David Chen8fe82a32016-08-24 10:55:41 +00002446 <li><code>server_pid</code>: the process ID of the Bazel server
nharmataa3a7dad2020-03-30 10:42:05 -07002447 process.
2448 </li>
2449 <li><code>server_log</code>: the absolute path to the Bazel server's debug log file.
2450 This file contains debugging information for all commands over the lifetime of the
2451 Bazel server, and is intended for human consumption by Bazel developers and power users.
2452 </li>
David Chen8fe82a32016-08-24 10:55:41 +00002453 <li><code>command_log</code>: the absolute path to the command log file;
2454 this contains the interleaved stdout and stderr streams of the most recent
2455 Bazel command. Note that running <code>bazel info</code> will overwrite the
2456 contents of this file, since it then becomes the most recent Bazel command.
2457 However, the location of the command log file will not change unless you
2458 change the setting of the <code class='flag'>--output_base</code> or
2459 <code class='flag'>--output_user_root</code> options.
2460 </li>
2461
2462 <li><code>used-heap-size</code>,
Googler82085c42018-08-16 08:01:39 -07002463 <code>committed-heap-size</code>,
David Chen8fe82a32016-08-24 10:55:41 +00002464 <code>max-heap-size</code>: reports various JVM heap size
Googler0e692fb2021-01-22 18:38:24 +01002465 parameters. Respectively: memory currently used, memory currently
David Chen8fe82a32016-08-24 10:55:41 +00002466 guaranteed to be available to the JVM from the system, maximum
2467 possible allocation.
2468 </li>
2469 <li><code>gc-count</code>, <code>gc-time</code>: The cumulative count of
2470 garbage collections since the start of this Bazel server and the time spent
2471 to perform them. Note that these values are not reset at the start of every
2472 build.
2473 </li>
2474 <li><code>package_path</code>: A colon-separated list of paths which would be
2475 searched for packages by bazel. Has the same format as the
2476 <code class='flag'>--package_path</code> build command line argument.
2477 </li>
2478</ul>
2479<p>
2480 Example: the process ID of the Bazel server.
2481</p>
2482<pre>% bazel info server_pid
24831285
2484</pre>
2485
2486<h4>Configuration-specific data</h4>
2487<p>
2488 These data may be affected by the configuration options passed
2489 to <code>bazel info</code>, for
2490 example <code class='flag'>--cpu</code>, <code class='flag'>--compilation_mode</code>,
Googler0e692fb2021-01-22 18:38:24 +01002491 etc. The <code>info</code> command accepts all
David Chen8fe82a32016-08-24 10:55:41 +00002492 the <a href='#analysis-options'>options that control dependency
2493 analysis</a>, since some of these determine the location of the
2494 output directory of a build, the choice of compiler, etc.
2495</p>
2496<ul>
2497 <li>
2498 <code>bazel-bin</code>, <code>bazel-testlogs</code>,
2499 <code>bazel-genfiles</code>: reports the absolute path to
2500 the <code>bazel-*</code> directories in which programs generated by the
2501 build are located. This is usually, though not always, the same as
2502 the <code>bazel-*</code> symlinks created in the base workspace directory after a
2503 successful build. However, if the workspace directory is read-only,
2504 no <code>bazel-*</code> symlinks can be created. Scripts that use
2505 the value reported by <code>bazel info</code>, instead of assuming the
2506 existence of the symlink, will be more robust.
2507 </li>
2508 <li>
2509 The complete
2510 <a href='be/make-variables.html'
2511 >"Make" environment</a>. If the <code class='flag'>--show_make_env</code> flag is
2512 specified, all variables in the current configuration's "Make" environment
2513 are also displayed (e.g. <code>CC</code>, <code>GLIBC_VERSION</code>, etc).
2514 These are the variables accessed using the <code>$(CC)</code>
2515 or <code>varref("CC")</code> syntax inside BUILD files.
2516 </li>
2517</ul>
2518
2519<p>
2520 Example: the C++ compiler for the current configuration.
2521 This is the <code>$(CC)</code> variable in the "Make" environment,
2522 so the <code class='flag'>--show_make_env</code> flag is needed.
2523</p>
2524
2525<pre>
Ulf Adamse0437b12016-08-29 14:48:47 +00002526 % bazel info --show_make_env -c opt COMPILATION_MODE
2527 opt
David Chen8fe82a32016-08-24 10:55:41 +00002528</pre>
2529
2530<p>
2531 Example: the <code>bazel-bin</code> output directory for the current
Googler0e692fb2021-01-22 18:38:24 +01002532 configuration. This is guaranteed to be correct even in cases where
David Chen8fe82a32016-08-24 10:55:41 +00002533 the <code>bazel-bin</code> symlink cannot be created for some reason
2534 (e.g. you are building from a read-only directory).
2535</p>
2536
gregce29bc5802020-05-18 11:13:41 -07002537<pre>% bazel info --cpu=piii bazel-bin
2538/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
2539% bazel info --cpu=k8 bazel-bin
2540/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin
gregce2083aad2020-05-18 15:49:30 -07002541</pre>
brandjoncf0390b2020-02-20 10:37:40 -08002542<h3 id='version'><code>version</code> and <code>--version</code></h3>
David Chen8fe82a32016-08-24 10:55:41 +00002543
2544<p>
2545 The version command prints version details about the built Bazel
2546 binary, including the changelist at which it was built and the date.
2547 These are particularly useful in determining if you have the latest
2548 Bazel, or if you are reporting bugs. Some of the interesting values
2549 are:
2550</p>
2551<ul>
2552 <li><code>changelist</code>: the changelist at which this version of
2553 Bazel was released.
2554 </li>
2555 <li><code>label</code>: the release label for this Bazel
2556 instance, or "development version" if this is not a released
2557 binary. Very useful when reporting bugs.
2558 </li>
2559</ul>
2560
michajlo52a0bcf2019-08-29 08:55:21 -07002561<p>
2562 <code>bazel --version</code>, with no other args, will emit the same output as
2563 <code>bazel version --gnu_format</code>, except without the side-effect of potentially starting
brandjoncf0390b2020-02-20 10:37:40 -08002564 a Bazel server or unpacking the server archive. <code>bazel --version</code> can be run from
2565 anywhere - it does not require a workspace directory.
michajlo52a0bcf2019-08-29 08:55:21 -07002566</p>
2567
brandjoncf0390b2020-02-20 10:37:40 -08002568<h3 id='mobile-install'><code>mobile-install</code></h3>
David Chen8fe82a32016-08-24 10:55:41 +00002569<p>
2570 The <code>mobile-install</code> command installs apps to mobile devices.
2571 Currently only Android devices running ART are supported.
Alex Humesky105e6612017-01-06 19:03:10 +00002572
2573 See <a href="mobile-install.html">bazel mobile-install</a>
2574 for more information.
David Chen8fe82a32016-08-24 10:55:41 +00002575</p>
2576<p>
2577 Note that this command does not install the same thing that
2578 <code>bazel build</code> produces: Bazel tweaks the app so that it can be
2579 built, installed and re-installed quickly. This should, however, be mostly
2580 transparent to the app.
2581</p>
2582<p>
2583 The following options are supported:
2584</p>
2585<h4 id='flag--incremental'><code class='flag'>--incremental</code></h4>
2586<p>
2587 If set, Bazel tries to install the app incrementally, that is, only those
2588 parts that have changed since the last build. This cannot update resources
2589 referenced from <code>AndroidManifest.xml</code>, native code or Java
2590 resources (i.e. ones referenced by <code>Class.getResource()</code>). If these
2591 things change, this option must be omitted. Contrary to the spirit of Bazel
2592 and due to limitations of the Android platform, it is the
2593 <b>responsibility of the user</b> to know when this command is good enough and
Alex Humesky105e6612017-01-06 19:03:10 +00002594 when a full install is needed.
2595
2596 If you are using a device with Marshmallow or later, consider the
2597 <a href='#flag--split_apks'><code class='flag'>--split_apks</code></a> flag.
David Chen8fe82a32016-08-24 10:55:41 +00002598</p>
Alex Humesky105e6612017-01-06 19:03:10 +00002599<h4 id='flag--split_apks'><code class='flag'>--split_apks</code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00002600<p>
Alex Humesky105e6612017-01-06 19:03:10 +00002601 Whether to use split apks to install and update the application on the device.
2602 Works only with devices with Marshmallow or later. Note that the
2603 <a href='#flag--incremental'><code class='flag'>--incremental</code></a> flag
2604 is not necessary when using <code class='flag'>--split_apks</code>.
David Chen8fe82a32016-08-24 10:55:41 +00002605</p>
Alex Humesky105e6612017-01-06 19:03:10 +00002606<h4 id='flag--start_app'><code class='flag'>--start_app</code></h4>
2607<p>
2608 Starts the app in a clean state after installing. Equivalent to
2609 <code>--start=COLD</code>.
2610</p>
Googler2b88f622017-03-16 21:52:14 +00002611<h4 id='flag--debug_app'><code class='flag'>--debug_app</code></h4>
Alex Humesky105e6612017-01-06 19:03:10 +00002612<p>
Googler2b88f622017-03-16 21:52:14 +00002613 Waits for debugger to be attached before starting the app in a clean state after installing.
2614 Equivalent to <code>--start=DEBUG</code>.
2615</p>
2616<h4 id='flag--start'><code class='flag'>--start=<i>start_type</i></code></h4>
2617<p>
2618 How the app should be started after installing it. Supported <i>start_type</i>s are:
Ivo List2fb9f3c2020-12-17 10:19:09 -08002619</p>
2620<ul>
2621 <li><code>NO</code> Does not start the app. This is the default.</li>
2622 <li><code>COLD</code> Starts the app from a clean state after install.</li>
2623 <li><code>WARM</code> Preserves and restores the application state on incremental installs.</li>
2624 <li><code>DEBUG</code> Waits for the debugger before starting the app in a clean state after
2625 install.
2626 </li>
2627</ul>
2628<p>
Googler2b88f622017-03-16 21:52:14 +00002629 Note that if more than one of <code class='flag'>--start=<i>start_type</i></code>,
2630 <code class='flag'>--start_app</code> or
Ivo List2fb9f3c2020-12-17 10:19:09 -08002631 <code class='flag'>--debug_app</code> is set, the last value is used.
Alex Humesky105e6612017-01-06 19:03:10 +00002632</p>
ranjanih6a1a09f2021-03-10 15:39:14 -08002633<h4 id='flag--adb'><code class='flag'>--adb=<var>path</var></code></h4>
Alex Humesky105e6612017-01-06 19:03:10 +00002634<p>
2635 Indicates the <code>adb</code> binary to be used.
2636
2637 The default is to use the adb in the Android SDK specified by
2638 <a href='#flag--android_sdk'><code class='flag'>--android_sdk</code></a>.
2639
2640</p>
ranjanih6a1a09f2021-03-10 15:39:14 -08002641<h4 id='flag--adb_arg'><code class='flag'>--adb_arg=<var>serial</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00002642<p>
2643 Extra arguments to <code>adb</code>. These come before the subcommand in the
2644 command line and are typically used to specify which device to install to.
Alex Humesky105e6612017-01-06 19:03:10 +00002645 For example, to select the Android device or emulator to use:
Ivo List2fb9f3c2020-12-17 10:19:09 -08002646</p>
David Chen8fe82a32016-08-24 10:55:41 +00002647<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
2648</pre>
Ivo List2fb9f3c2020-12-17 10:19:09 -08002649<p>
2650 invokes <code>adb</code> as
2651</p>
David Chen8fe82a32016-08-24 10:55:41 +00002652<pre>
2653adb -s deadbeef install ...
2654</pre>
ranjanih6a1a09f2021-03-10 15:39:14 -08002655<h4 id='flag--incremental_install_verbosity'><code class='flag'>--incremental_install_verbosity=<var>number</var></code></h4>
Alex Humesky105e6612017-01-06 19:03:10 +00002656<p>
2657 The verbosity for incremental install. Set to 1 for debug logging to be
2658 printed to the console.
David Chen8fe82a32016-08-24 10:55:41 +00002659</p>
2660
gregceca8ee232018-03-08 11:35:22 -08002661
brandjoncf0390b2020-02-20 10:37:40 -08002662<h3 id='dump'><code>dump</code></h3>
gregceca8ee232018-03-08 11:35:22 -08002663
2664<p>
2665 The <code>dump</code> command prints to stdout a dump of the
Googler0e692fb2021-01-22 18:38:24 +01002666 internal state of the Bazel server. This command is intended
gregceca8ee232018-03-08 11:35:22 -08002667 primarily for use by Bazel developers, so the output of this command
2668 is not specified, and is subject to change.
2669</p>
2670
tomlu72642a22017-10-18 06:23:14 +02002671<p>
2672 By default, command will just print help message outlining possible
2673 options to dump specific areas of the Bazel state. In order to dump
2674 internal state, at least one of the options must be specified.
2675</p>
2676<p>
2677 Following options are supported:
2678</p>
2679<ul>
2680 <li><code class='flag'>--action_cache</code> dumps action cache content.</li>
2681 <li><code class='flag'>--packages</code> dumps package cache content.</li>
tomlu72642a22017-10-18 06:23:14 +02002682 <li><code class='flag'>--skyframe</code> dumps state of internal Bazel dependency graph.</li>
2683 <li><code class='flag'>--rules</code> dumps rule summary for each rule and aspect class,
gregceca48e9a2020-04-14 08:54:38 -07002684 including counts and action counts. This includes both native and Starlark rules.
tomlu72642a22017-10-18 06:23:14 +02002685 If memory tracking is enabled, then the rules' memory consumption is also printed.</li>
2686 <li><code class='flag'>--skylark_memory</code> dumps a
Ivo List2fb9f3c2020-12-17 10:19:09 -08002687 <a href=https://github.com/google/pprof>pprof</a> compatible .gz file to the specified path.
2688 You must enable memory tracking for this to work.
2689 </li>
twerth700bc132018-03-05 01:32:50 -08002690 <li><code class='flag'>--action_graph=/path/to/file</code> dumps the state of
2691 the internal Bazel action graph in proto format to
2692 <code>/path/to/file</code>. You have to run (at least) the analysis phase
2693 for the targets you are interested in (for example, <code>bazel build --nobuild
2694 //foo:bar</code>). Note that this feature is still experimental, subject to
2695 change and will probably be integrated into <code>cquery</code> in the
2696 future.
2697 <li><code class='flag'>--action_graph:targets=target1,target2,...</code>
2698 filters the actions to the comma-separated list of targets when dumping the
2699 action graph.</li>
ahumeskya0f3a652018-09-17 09:23:44 -07002700 <li><code class='flag'>--action_graph:include_cmdline</code> Include the command lines of actions
2701 in the action graph dump.</li>
tomlu72642a22017-10-18 06:23:14 +02002702</ul>
2703
tomlu5af61382017-10-30 18:01:48 -04002704 <h4 id='memory-tracking'>Memory tracking</h4>
2705 <p>
2706 Some <code>dump</code> commands require memory tracking. To turn this on, you have to pass
2707 startup flags to Bazel:
2708 </p>
2709 <ul>
2710 <li><code>--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar</code></li>
tomlu4cad14a2017-10-31 09:08:32 -04002711 <li><code>--host_jvm_args=-DRULE_MEMORY_TRACKER=1</code></li>
tomlu5af61382017-10-30 18:01:48 -04002712 </ul>
2713 <p>
Googlerbc321af2020-11-30 14:49:00 -08002714 The java-agent is checked into Bazel at
tomlu5af61382017-10-30 18:01:48 -04002715 third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar, so make
Googlerbc321af2020-11-30 14:49:00 -08002716 sure you adjust <code>$BAZEL</code> for where you keep your Bazel repository.
tomlu72642a22017-10-18 06:23:14 +02002717
tomlu5af61382017-10-30 18:01:48 -04002718 Do not forget to keep passing these options to Bazel for every command or the server will
2719 restart.
2720 </p>
2721 <p>Example:</p>
2722 <pre>
2723 % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
2724 --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
2725 build --nobuild &lt;targets&gt;
tomlu72642a22017-10-18 06:23:14 +02002726
tomlu5af61382017-10-30 18:01:48 -04002727 # Dump rules
2728 % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
2729 --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
2730 dump --rules
tomlu72642a22017-10-18 06:23:14 +02002731
gregceca48e9a2020-04-14 08:54:38 -07002732 # Dump Starlark heap and analyze it with pprof
tomlu5af61382017-10-30 18:01:48 -04002733 % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.0.1.jar \
2734 --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
2735 dump --skylark_memory=$HOME/prof.gz
2736 % pprof -flame $HOME/prof.gz
2737 </pre>
brandjoncf0390b2020-02-20 10:37:40 -08002738<h3 id='analyze-profile'><code>analyze-profile</code></h3>
tomlu72642a22017-10-18 06:23:14 +02002739
2740<p>
2741 The <code>analyze-profile</code> command analyzes data previously gathered
2742 during the build using <code class='flag'>--profile</code> option. It provides several
2743 options to either perform analysis of the build execution or export data in
2744 the specified format.
2745
2746</p>
2747<p>
2748 The following options are supported:
2749</p>
2750<ul>
Eric Cousineau334925f2020-10-14 07:12:30 -07002751 <li><code id='flag--dump'>--dump</code> displays all gathered data in a
2752 <a href='guide.html#dump-text-format'>human-readable format</a>. However,
2753 this it does not support other formats yet.</li>
tomlu72642a22017-10-18 06:23:14 +02002754</ul>
2755
2756<p>
Googler59830672019-01-03 10:33:49 -08002757 See the section on <a href='guide.html#profiling'>Troubleshooting performance by profiling</a> for
tomlu72642a22017-10-18 06:23:14 +02002758 format details and usage help.
2759
David Chen8fe82a32016-08-24 10:55:41 +00002760</p>
2761
brandjoncf0390b2020-02-20 10:37:40 -08002762<h3 id='canonicalize'><code>canonicalize-flags</code></h3>
David Chen8fe82a32016-08-24 10:55:41 +00002763
2764<p>
Eric Cousineaubb99f9d2020-10-19 18:07:27 -07002765 The <a href="https://docs.bazel.build/command-line-reference.html#canonicalize-flags-options">
2766 <code>canonicalize-flags</code></a> command, which takes a list of options for
David Chen8fe82a32016-08-24 10:55:41 +00002767 a Bazel command and returns a list of options that has the same effect. The
2768 new list of options is canonical, i.e., two lists of options with the same
2769 effect are canonicalized to the same new list.
2770</p>
2771<p>
2772 The <code class='flag'>--for_command</code> option can be used to select between different
2773 commands. At this time, only <code>build</code> and <code>test</code> are
2774 supported. Options that the given command does not support cause an error.
2775</p>
2776<p>
2777 Note that a small number of options cannot be reordered, because Bazel cannot
Eric Cousineaubb99f9d2020-10-19 18:07:27 -07002778 ensure that the effect is identical. Also note that this command
2779 <i>does not</i> expand flags from <code>--config</code>.
David Chen8fe82a32016-08-24 10:55:41 +00002780</p>
Eric Cousineaubb99f9d2020-10-19 18:07:27 -07002781<p>
2782 As an example:
2783</p>
2784<pre>
2785 % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint"
2786 --config=any_name
2787 --test_tag_filters=-lint
2788</pre>
David Chen8fe82a32016-08-24 10:55:41 +00002789
brandjoncf0390b2020-02-20 10:37:40 -08002790<h3 id='startup_options'>Startup options</h3>
David Chen8fe82a32016-08-24 10:55:41 +00002791
2792<p>
2793 The options described in this section affect the startup of the Java
2794 virtual machine used by Bazel server process, and they apply to all
2795 subsequent commands handled by that server. If there is an already
2796 running Bazel server and the startup options do not match, it will
2797 be restarted.
2798</p>
2799<p>
2800 All of the options described in this section must be specified using the
2801 <code class='flag'>--key=value</code> or <code class='flag'>--key value</code>
2802 syntax. Also, these options must appear <i>before</i> the name of the Bazel
larsrc63b9aef2021-04-14 05:43:16 -07002803 command. Use <code>startup --key=value</code> to list these in a <code>.bazelrc</code> file.
David Chen8fe82a32016-08-24 10:55:41 +00002804</p>
2805
2806<h4 id='flag--output_base'><code class='flag'>--output_base=<var>dir</var></code></h4>
2807<p>
2808 This option requires a path argument, which must specify a
Googler0e692fb2021-01-22 18:38:24 +01002809 writable directory. Bazel will use this location to write all its
2810 output. The output base is also the key by which the client locates
2811 the Bazel server. By changing the output base, you change the server
David Chen8fe82a32016-08-24 10:55:41 +00002812 which will handle the command.
2813</p>
2814<p>
2815 By default, the output base is derived from the user's login name,
2816 and the name of the workspace directory (actually, its MD5 digest),
2817 so a typical value looks like:
2818
lberkif071a232017-12-07 04:21:34 -08002819 <code>/var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e</code>.
David Chen8fe82a32016-08-24 10:55:41 +00002820 Note that the client uses the output base to find the Bazel server
2821 instance, so if you specify a different output base in a Bazel
2822 command, a different server will be found (or started) to handle the
Googler0e692fb2021-01-22 18:38:24 +01002823 request. It's possible to perform two concurrent builds in the same
David Chen8fe82a32016-08-24 10:55:41 +00002824 workspace directory by varying the output base.
2825</p>
2826
2827<p>For example:</p>
sxlijin90f244f2020-05-12 06:08:15 -07002828<pre><code>
2829 OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
laurentlbdad21ed2020-05-13 16:00:41 -07002830 % bazel --output_base $OUTPUT_BASE build //foo &amp; bazel --output_base $OUTPUT_BASE build //bar
2831</code></pre>
2832<p>
2833 In this command, the two Bazel commands run concurrently (because of
2834 the shell <code>&amp;</code> operator), each using a different Bazel
2835 server instance (because of the different output bases).
2836 In contrast, if the default output base was used in both commands,
2837 then both requests would be sent to the same server, which would
2838 handle them sequentially: building <code>//foo</code> first, followed
2839 by an incremental build of <code>//bar</code>.
2840</p>
2841<p>
larsrc63b9aef2021-04-14 05:43:16 -07002842 <b>Tip:</b>We recommend you do not use an NFS or similar networked file system for the root
2843 directory, as the higher access latency will cause noticeably slower builds.
laurentlbdad21ed2020-05-13 16:00:41 -07002844</p>
2845
David Chen8fe82a32016-08-24 10:55:41 +00002846<h4 id='flag--output_user_root'><code class='flag'>--output_user_root=<var>dir</var></code></h4>
2847<p>
larsrc63b9aef2021-04-14 05:43:16 -07002848 Points to the root directory where output and install bases are created. The directory
jmmv0f8cecf2020-05-15 07:54:17 -07002849 must either not exist or be owned by the calling user. In the past,
2850 this was allowed to point to a directory shared among various users
larsrc63b9aef2021-04-14 05:43:16 -07002851 but it's not allowed any longer. This may be allowed once
2852 <a href='https://github.com/bazelbuild/bazel/issues/11100'>issue #11100</a> is addressed.
David Chen8fe82a32016-08-24 10:55:41 +00002853</p>
2854<p>
2855 If the <code class='flag'>--output_base</code> option is specified, it overrides
2856 using <code class='flag'>--output_user_root</code> to calculate the output base.
2857</p>
2858<p>
larsrc63b9aef2021-04-14 05:43:16 -07002859 The install base location is calculated based on
David Chen8fe82a32016-08-24 10:55:41 +00002860 <code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded
2861 binaries.
2862</p>
2863<p>
larsrc63b9aef2021-04-14 05:43:16 -07002864 You can use the <code class='flag'>--output_user_root</code> option to choose an
David Chen8fe82a32016-08-24 10:55:41 +00002865 alternate base location for all of Bazel's output (install base and output
larsrc63b9aef2021-04-14 05:43:16 -07002866 base) if there is a better location in your filesystem layout.</p>
2867<p>
2868 <b>Tip:</b>We recommend you do not use an NFS or similar networked file system for the root
2869 directory, as the higher access latency will cause noticeably slower builds.
David Chen8fe82a32016-08-24 10:55:41 +00002870</p>
2871
cushon2a8b6572018-07-25 10:33:40 -07002872<a name="startup_flag--host_javabase"></a>
2873<h4 id='startup_flag--server_javabase'><code class='flag'>--server_javabase=<var>dir</var></code></h4>
Googlerba66e722017-12-04 12:15:36 -08002874<p>
2875 Specifies the Java virtual machine in which <i>Bazel itself</i> runs. The value must be a path to
2876 the directory containing a JDK or JRE. It should not be a label.
Googlera37711b2018-09-11 10:25:01 -07002877 This option should appear before any Bazel command, for example:
Googlerba66e722017-12-04 12:15:36 -08002878</p>
2879<pre>
Googler1523e3b2020-04-17 09:31:34 -07002880 % bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo
Googlerba66e722017-12-04 12:15:36 -08002881</pre>
2882<p>
2883 This flag does <i>not</i> affect the JVMs used by Bazel subprocesses such as applications, tests,
2884 tools, and so on. Use build options <a href='#flag--javabase'>--javabase</a> or
2885 <a href='#flag--host_javabase'>--host_javabase</a> instead.
2886</p>
cushon2a8b6572018-07-25 10:33:40 -07002887<p>
2888 This flag was previously named <code>--host_javabase</code> (sometimes referred to as the
2889 'left-hand side' <code>--host_javabase</code>), but was renamed to avoid confusion with the
2890 build flag <a href='#flag--host_javabase'>--host_javabase</a> (sometimes referred to as the
2891 'right-hand side' <code>--host_javabase</code>).
2892</p>
Googlerba66e722017-12-04 12:15:36 -08002893
David Chen8fe82a32016-08-24 10:55:41 +00002894<h4 id='flag--host_jvm_args'><code class='flag'>--host_jvm_args=<var>string</var></code></h4>
2895<p>
2896 Specifies a startup option to be passed to the Java virtual machine in which <i>Bazel itself</i>
Googler0e692fb2021-01-22 18:38:24 +01002897 runs. This can be used to set the stack size, for example:
David Chen8fe82a32016-08-24 10:55:41 +00002898</p>
2899<pre>
2900 % bazel --host_jvm_args="-Xss256K" build //foo
2901</pre>
2902<p>
2903 This option can be used multiple times with individual arguments. Note that
2904 setting this flag should rarely be needed. You can also pass a space-separated list of strings,
2905 each of which will be interpreted as a separate JVM argument, but this feature will soon be
2906 deprecated.
2907
2908</p>
2909<p>
2910 That this does <i>not</i> affect any JVMs used by
Googler0e692fb2021-01-22 18:38:24 +01002911 subprocesses of Bazel: applications, tests, tools, and so on. To pass
David Chen8fe82a32016-08-24 10:55:41 +00002912 JVM options to executable Java programs, whether run by <code>bazel
2913 run</code> or on the command-line, you should use
2914 the <code>--jvm_flags</code> argument which
2915 all <code>java_binary</code> and <code>java_test</code> programs
Googler0e692fb2021-01-22 18:38:24 +01002916 support. Alternatively for tests, use <code>bazel
David Chen8fe82a32016-08-24 10:55:41 +00002917 test --test_arg=--jvm_flags=foo ...</code>.
2918</p>
2919
2920<h4 id='flag--host_jvm_debug'><code class='flag'>--host_jvm_debug</code></h4>
2921<p>
2922 This option causes the Java virtual machine to wait for a connection
2923 from a JDWP-compliant debugger before
Googler0e692fb2021-01-22 18:38:24 +01002924 calling the main method of <i>Bazel itself</i>. This is primarily
David Chen8fe82a32016-08-24 10:55:41 +00002925 intended for use by Bazel developers.
2926</p>
2927<p>
2928 (Please note that this does <i>not</i> affect any JVMs used by
2929 subprocesses of Bazel: applications, tests, tools, etc.)
2930</p>
2931
Austin Schuh07400c02020-12-14 10:12:31 -08002932<h4 id='flag--autodetect_server_javabase'><code class='flag'>--autodetect_server_javabase</code></h4>
2933<p>
2934 This option causes Bazel to automatically search for an installed JDK on startup,
2935 and to fall back to the installed JRE if the embedded JRE isn't available.
2936 <code>--explicit_server_javabase</code> can be used to pick an explicit JRE to
2937 run bazel with.
2938</p>
2939
David Chen8fe82a32016-08-24 10:55:41 +00002940<h4 id='flag--batch'><code class='flag'>--batch</code></h4>
ccalvarinaf8b7722018-06-06 11:54:00 -07002941
David Chen8fe82a32016-08-24 10:55:41 +00002942<p>
ccalvarinaf8b7722018-06-06 11:54:00 -07002943 Batch mode causes Bazel to not use the standard client/server mode described
Googler59830672019-01-03 10:33:49 -08002944 <a href='guide.html#client/server'>above</a>, instead running a bazel java process for a
ccalvarinaf8b7722018-06-06 11:54:00 -07002945 single command, which has been used for more predictable semantics with respect
2946 to signal handling, job control, and environment variable inheritance, and is
2947 necessary for running bazel in a chroot jail.
David Chen8fe82a32016-08-24 10:55:41 +00002948</p>
2949
2950<p>
2951 Batch mode retains proper queueing semantics within the same output_base.
2952 That is, simultaneous invocations will be processed in order, without overlap.
ccalvarinaf8b7722018-06-06 11:54:00 -07002953 If a batch mode Bazel is run on a client with a running server, it first
David Chen8fe82a32016-08-24 10:55:41 +00002954 kills the server before processing the command.
2955</p>
2956
2957<p>
ccalvarinaf8b7722018-06-06 11:54:00 -07002958 Bazel will run slower in batch mode, or with the alternatives described above.
2959 This is because, among other things, the build file cache is memory-resident, so it is not
David Chen8fe82a32016-08-24 10:55:41 +00002960 preserved between sequential batch invocations.
2961 Therefore, using batch mode often makes more sense in cases where performance
2962 is less critical, such as continuous builds.
2963</p>
2964
michajlod72eb8d2019-11-19 10:58:53 -08002965<p>
2966 <i>WARNING:</i> <code class='flag'>--batch</code> is sufficiently slower than standard
2967 client/server mode. Additionally it might not support all of the features and optimizations which
2968 are made possible by a persistent Bazel server. If you're using <code class='flag'>--batch</code>
Googler03fd5412021-03-11 18:57:14 -08002969 for the purpose of build isolation, you should use the command option
michajlod72eb8d2019-11-19 10:58:53 -08002970 <code class='flag'>--nokeep_state_after_build</code>, which guarantees that no incremental
2971 in-memory state is kept between builds. In order to restart the Bazel server and JVM after a
2972 build, please explicitly do so using the "shutdown" command.
2973</p>
2974
2975
ranjanih6a1a09f2021-03-10 15:39:14 -08002976<h4 id='flag--max_idle_secs'><code class='flag'>--max_idle_secs=<var>n</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00002977<p>
2978 This option specifies how long, in seconds, the Bazel server process
Googler0e692fb2021-01-22 18:38:24 +01002979 should wait after the last client request, before it exits. The
dchaicf988cd2019-08-23 06:35:03 -07002980 default value is 10800 (3 hours). <code class='flag'>--max_idle_secs=0</code> will cause the
diamondm2decd3e2020-07-21 16:54:59 -07002981 Bazel server process to persist indefinitely. <i>NOTE:</i> this flag is only read if Bazel needs
2982 to start a new server. Changing this option will not cause the server to restart.
David Chen8fe82a32016-08-24 10:55:41 +00002983</p>
2984<p>
2985 This option may be used by scripts that invoke Bazel to ensure that
2986 they do not leave Bazel server processes on a user's machine when they
2987 would not be running otherwise.
2988 For example, a presubmit script might wish to
2989 invoke <code>bazel query</code> to ensure that a user's pending
Googler0e692fb2021-01-22 18:38:24 +01002990 change does not introduce unwanted dependencies. However, if the
David Chen8fe82a32016-08-24 10:55:41 +00002991 user has not done a recent build in that workspace, it would be
2992 undesirable for the presubmit script to start a Bazel server just
2993 for it to remain idle for the rest of the day.
2994 By specifying a small value of <code class='flag'>--max_idle_secs</code> in the
2995 query request, the script can ensure that <i>if</i> it caused a new
2996 server to start, that server will exit promptly, but if instead
2997 there was already a server running, that server will continue to run
Googler0e692fb2021-01-22 18:38:24 +01002998 until it has been idle for the usual time. Of course, the existing
David Chen8fe82a32016-08-24 10:55:41 +00002999 server's idle timer will be reset.
3000</p>
shreyax5f2d5642018-10-29 15:01:24 -07003001<h4 id='flag--shutdown_on_low_sys_mem'><code class='flag'>--[no]shutdown_on_low_sys_mem</code></h4>
3002<p>
3003 If enabled and <code class='flag'>--max_idle_secs</code> is set to a positive duration,
3004 after the build server has been idle for a while, shut down the server when the system is
3005 low on memory. Linux only.
3006</p>
3007<p>
3008 In addition to running an idle check corresponding to max_idle_secs, the build server will
3009 starts monitoring available system memory after the server has been idle for some time.
3010 If the available system memory becomes critically low, the server will exit.
3011</p>
David Chen8fe82a32016-08-24 10:55:41 +00003012
3013<h4 id='flag--block_for_lock'><code class='flag'>--[no]block_for_lock</code></h4>
3014<p>
3015 If enabled, Bazel will wait for other Bazel commands holding the
3016 server lock to complete before progressing. If disabled, Bazel will
3017 exit in error if it cannot immediately acquire the lock and
3018 proceed.
3019
3020 Developers might use this in presubmit checks to avoid long waits caused
3021 by another Bazel command in the same client.
3022</p>
3023
ranjanih6a1a09f2021-03-10 15:39:14 -08003024<h4 id='flag--io_nice_level'><code class='flag'>--io_nice_level=<var>n</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00003025<p>
3026 Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority,
3027 7 is lowest. The anticipatory scheduler may only honor up to priority 4.
3028 Negative values are ignored.
3029</p>
3030
3031<h4 id='flag--batch_cpu_scheduling'><code class='flag'>--batch_cpu_scheduling</code></h4>
3032<p>
3033 Use <code>batch</code> CPU scheduling for Bazel. This policy is useful for
3034 workloads that are non-interactive, but do not want to lower their nice value.
3035 See 'man 2 sched_setscheduler'. This policy may provide for better system
3036 interactivity at the expense of Bazel throughput.
3037</p>
3038
3039<h3 id='misc_options'>Miscellaneous options</h3>
3040
3041<h4 id='flag--announce_rc'><code class='flag'>--[no]announce_rc</code></h4>
3042<p>
3043 Controls whether Bazel announces command options read from the bazelrc file when
3044 starting up. (Startup options are unconditionally announced.)
3045</p>
3046
3047<h4 id='flag--color'><code class='flag'>--color (yes|no|auto)</code></h4>
3048<p>
3049 This option determines whether Bazel will use colors to highlight
3050 its output on the screen.
3051</p>
3052<p>
3053 If this option is set to <code>yes</code>, color output is enabled.
3054 If this option is set to <code>auto</code>, Bazel will use color output only if
3055 the output is being sent to a terminal and the TERM environment variable
3056 is set to a value other than <code>dumb</code>, <code>emacs</code>, or <code>xterm-mono</code>.
3057 If this option is set to <code>no</code>, color output is disabled,
3058 regardless of whether the output is going to a terminal and regardless
3059 of the setting of the TERM environment variable.
3060</p>
3061
ranjanih6a1a09f2021-03-10 15:39:14 -08003062<h4 id='flag--config'><code class='flag'>--config=<var>name</var></code></h4>
David Chen8fe82a32016-08-24 10:55:41 +00003063<p>
Googlerf4ad83a2021-05-10 13:10:55 -07003064 Selects additional config section from
3065 <a href="guide#where-are-the-bazelrc-files">the rc files</a>; for the current <code>command</code>,
3066 it also pulls in the options from <code>command:name</code> if such a section exists. Can be
3067 specified multiple times to add flags from several config sections. Expansions can refer to other
Googlerc848bf32017-02-14 12:15:42 +00003068 definitions (i.e. expansions can be chained).
David Chen8fe82a32016-08-24 10:55:41 +00003069</p>
3070
3071<h4 id='flag--curses'><code class='flag'>--curses (yes|no|auto)</code></h4>
3072<p>
3073 This option determines whether Bazel will use cursor controls
3074 in its screen output. This results in less scrolling data, and a more
3075 compact, easy-to-read stream of output from Bazel. This works well with
3076 <code class='flag'>--color</code>.
3077</p>
3078<p>
3079 If this option is set to <code>yes</code>, use of cursor controls is enabled.
3080 If this option is set to <code>no</code>, use of cursor controls is disabled.
3081 If this option is set to <code>auto</code>, use of cursor controls will be
3082 enabled under the same conditions as for <code class='flag'>--color=auto</code>.
3083</p>
3084
3085<h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4>
3086<p>
3087 If specified, a timestamp is added to each message generated by
3088 Bazel specifying the time at which the message was displayed.
3089</p>