forked from bazelbuild/bazel
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathbazel-user-manual.html
More file actions
3638 lines (3294 loc) · 146 KB
/
bazel-user-manual.html
File metadata and controls
3638 lines (3294 loc) · 146 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>A User's Guide to Bazel</title>
<style type="text/css">
body {
background-color: #ffffff;
color: black;
margin-right: 10%;
margin-left: 10%;
}
h1, h2, h3, h4, h5, h6 {
color: #dd7755;
font-family: sans-serif;
}
@media print {
/* Darker version for printing */
h1, h2, h3, h4, h5, h6 {
color: #008000;
font-family: helvetica, sans-serif;
}
}
h1 {
text-align: center;
}
h2 {
margin-left: -0.5in;
}
h3 {
margin-left: -0.25in;
}
h4 {
margin-left: -0.125in;
}
hr {
margin-left: -1in;
}
address {
text-align: right;
}
/* A compact unordered list */
ul.tight > li {
margin-bottom: 0;
}
/* Use the <code></code> tag for bits of code and <var></var> for variable and object names. */
code,pre,samp,var {
color: #006000;
}
/* Use the <file></file> tag for file and directory paths and names. */
file {
color: #905050;
font-family: monospace;
}
/* Use the <kbd></kbd> tag for stuff the user should type. */
kbd {
color: #600000;
}
div.note p {
float: right;
width: 3in;
margin-right: 0%;
padding: 1px;
border: 2px solid #60a060;
background-color: #fffff0;
}
table.grid {
background-color: #ffffee;
border: 1px solid black;
border-collapse: collapse;
margin-left: 2mm;
margin-right: 2mm;
}
table.grid th,
table.grid td {
border: 1px solid black;
padding: 0 2mm 0 2mm;
}
/* Use pre.code for code listings.
Use pre.interaction for "Here's what you see when you run a.out.".
(Within pre.interaction, use <kbd></kbd> things the user types)
*/
pre.code {
background-color: #FFFFEE;
border: 1px solid black;
color: #004000;
font-size: 10pt;
margin-left: 2mm;
margin-right: 2mm;
padding: 2mm;
-moz-border-radius: 12px 0px 0px 0px;
}
pre.interaction {
background-color: #EEFFEE;
color: #004000;
padding: 2mm;
}
pre.interaction kbd {
font-weight: bold;
color: #000000;
}
/* legacy style */
pre.interaction b.astyped {
color: #000000;
}
pre {
margin-left: 5em;
color: #008000;
}
.tt td {
font-family: courier;
}
.deprecated { text-decoration: line-through; }
.discouraged { text-decoration: line-through; }
table.layout { width: 980px; }
table.layout td { vertical-align: top; }
#maintainer { text-align: right; }
</style>
</head>
<body>
<h1>A User's Guide to Bazel</h1>
<h2 id='overview'>Bazel overview</h2>
<p>
Running Bazel is easy. Simply go to
your base workspace directory
or any of its subdirectories and type <code>bazel</code>.
</p>
<pre>
% bazel help
[Bazel release bazel-<<i>version</i>>]
Usage: bazel <command> <options> ...
Available commands:
<a href='#analyze-profile'>analyze-profile</a> Analyzes build profile data.
<a href='#build'>build</a> Builds the specified targets.
<a href='#canonicalize'>canonicalize-flags</a> Canonicalize Bazel flags.
<a href='#clean'>clean</a> Removes output files and optionally stops the server.
<a href='#help'>help</a> Prints help for commands, or the index.
<a href='#info'>info</a> Displays runtime info about the bazel server.
<a href='#query'>query</a> Executes a dependency graph query.
<a href='#run'>run</a> Runs the specified target.
<a href='#shutdown'>shutdown</a> Stops the Bazel server.
<a href='#test'>test</a> Builds and runs the specified test targets.
Getting more help:
bazel help <command>
Prints help and options for <command>.
bazel help <a href='#startup_options'>startup_options</a>
Options for the JVM hosting Bazel.
bazel help <a href='#target-patterns'>target-syntax</a>
Explains the syntax for specifying targets.
bazel help info-keys
Displays a list of keys used by the info command.
</pre>
<p>
The <code>bazel</code> tool performs many functions, called
commands; users of CVS and Subversion will be familiar
with this "Swiss army knife" arrangement. The most commonly used one is of
course <code>bazel build</code>. You can browse the online help
messages using <code>bazel help</code>.
</p>
<h3 id='client/server'>Client/server implementation</h3>
<p>
The Bazel system is implemented as a long-lived server process.
This allows it to perform many optimizations not possible with a
batch-oriented implementation, such as caching of BUILD files,
dependency graphs, and other metadata from one build to the
next. This improves the speed of incremental builds, and allows
different commands, such as <code>build</code>
and <code>query</code> to share the same cache of loaded packages,
making queries very fast.
</p>
<p>
When you run <code>bazel</code>, you're running the client. The
client finds the server based on the path of the base workspace directory
and your userid, so if you build in multiple workspaces, you'll have
multiple Bazel server processes. Multiple users on the same
workstation can build concurrently in the same workspace. If the
client cannot find a running server instance, it starts a new one.
The server process will stop after a period of inactivity (3 hours,
by default).
</p>
<p>
For the most part, the fact that there is a server running is
invisible to the user, but sometimes it helps to bear this in mind.
For example, if you're running scripts that perform a lot of
automated builds in different directories, it's important to ensure
that you don't accumulate a lot of idle servers; you can do this by
explicitly shutting them down when you're finished with them, or by
specifying a short timeout period.
</p>
<p>
The name of a Bazel server process appears in the output of <code>ps
x</code> or <code>ps -e f</code> as
<code>bazel(<i>dirname</i>)</code>, where <i>dirname</i> is the
basename of the directory enclosing the root your workspace directory.
For example:
</p>
<pre>
% ps -e f
16143 ? Sl 3:00 bazel(src-jrluser2) -server -Djava.library.path=...
</pre>
<p>
This makes it easier to find out which server process belongs to a
given workspace. (Beware that with certain other options
to <code>ps</code>, Bazel server processes may be named just
<code>java</code>.) Bazel servers can be stopped using
the <a href='#shutdown'>shutdown</a> command.
</p>
<p>
You can also run Bazel in batch mode using the <code>--batch</code>
startup flag. This will immediately shut down the process after the
command (build, test, etc.) has finished and not keep a server process
around.
</p>
<p>
When running <code>bazel</code>, the client first checks that the
server is the appropriate version; if not, the server is stopped and
a new one started. This ensures that the use of a long-running
server process doesn't interfere with proper versioning.
</p>
<h3 id='bazelrc'><code>.bazelrc</code>, the Bazel configuration file,
the <code class='flag'>--bazelrc=<var>file</var></code> option, and the
<code class='flag'>--config=<var>value</var></code> option</h3>
<p>
Bazel accepts many options. Typically, some of these are varied
frequently (e.g. <code class='flag'>--subcommands</code>) while others stay the
same across several builds (e.g. <code class='flag'>--package_path</code>).
To avoid having to specify these constant options every time you do
a build or run some other Bazel command, Bazel allows you to
specify options in a configuration file.
</p>
<p>
Bazel looks for an optional configuration file in the location
specified by the <code class='flag'>--bazelrc=<var>file</var></code> option. If
this option is not specified then, by default, Bazel looks for the
file called <code>.bazelrc</code> in one of two directories: first,
in your base workspace directory, then in your home directory. If
it finds a file in the first (workspace-specific) location, it will
not look at the second (global) location.
</p>
<p>
The <code class='flag'>--bazelrc=<var>file</var></code> option must
appear <em>before</em> the command name (e.g. <code>build</code>),
and must use the <code>=</code> syntax—a space is not allowed.
</p>
<p>
The option <code class='flag'>--bazelrc=/dev/null</code> effectively disables the
use of a configuration file. We strongly recommend that you use
this option when performing release builds, or automated tests that
invoke Bazel.
</p>
<p>
Aside from the configuration file described above, Bazel also looks
for a master configuration file next to the binary. The name of this
file is the same as the name of the binary with the
string <code>.bazelrc</code> attached. This file is not intended to
be user-modifiable; its purpose is for the Bazel team to be able to
turn experimental features on or off immediately without releasing a
new Bazel version, should an urgent need arise. Reading of this file
can be disabled using the <code class='flag'>--nomaster_bazelrc</code> option.
</p>
<p>
Like all UNIX "rc" files, the <code>.bazelrc</code> file is a text
file with a line-based grammar. Lines starting <code>#</code> are
considered comments and are ignored, as are blank lines. Each line
contains a sequence of words, which are tokenized according to the
same rules as the Bourne shell.
The first word on each line is the name of a Bazel command, such
as <code>build</code> or <code>query</code>. The remaining words
are the default options that apply to that command.
More than one line may be used for a command; the options are combined
as if they had appeared on a single line.
(Users of CVS, another tool with a "Swiss army knife" command-line
interface, will find the syntax familiar to that of <code>.cvsrc</code>.)
</p>
<p>
Startup options may be specified in the
<code>.bazelrc</code> file using the command <code>startup</code>.
These options are described in the interactive help
at <code>bazel help startup_options</code>.
</p>
<p>
Options specified in the command line always take precedence over
those from a configuration file, and options in the user-specific
configuration file always take precedence over the master one.
</p>
<p>
Options may include words other than flags, such as the names of
build targets, etc; these are always prepended to the explicit
argument list provided on the command-line, if any.
</p>
<p>
Common command options may be specified in the
<code>.bazelrc</code> file using the command <code>common</code>.
</p>
<p>
In addition, commands may have <code>:name</code> suffixes. These
options are ignored by default, but can be pulled in through the
<code>--config=<var>name</var></code> option, either on the command line or in
a <code>.bazelrc</code> file. The intention is that these bundle command line
options that are commonly used together, for example
<code>--config=memcheck</code>.
</p>
<p>
Note that some config sections are defined in the master bazelrc file.
To avoid conflicts, user-defined sections
should start with the '_' (underscore) character.
</p>
<p>
The command named <code>import</code> is special: if Bazel encounters such
a line in a <code>.bazelrc</code> file, it parses the contents of the file
referenced by the import statement, too. Options specified in an imported file
take precedence over ones specified before the import statement, options
specified after the import statement take precedence over the ones in the
imported file, and options in files imported later take precedence over files
imported earlier.
</p>
<p>
Here's an example <code>~/.bazelrc</code> file:
</p>
<pre>
# Bob's Bazel option defaults
startup --batch --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going
build:memcheck --strip=never --test_timeout=3600
</pre>
<h2 id='build'>Building programs with Bazel</h2>
<h3>The <code>build</code> command</h3>
<p>
The most important function of Bazel is, of course, building code. Type
<code>bazel build</code> followed by the name of the
<a href="#target-patterns">target</a> you wish to build. Here's a typical
session:
</p>
<pre>
% bazel build //foo
____Loading package: foo
____Loading package: bar
____Loading package: baz
____Loading complete. Analyzing...
____Building 1 target...
____[0 / 3] Executing Genrule //bar:helper_rule
____[1 / 3] Executing Genrule //baz:another_helper_rule
____[2 / 3] Building foo/foo.bin
Target //foo:foo up-to-date:
bazel-bin/foo/foo.bin
bazel-bin/foo/foo
____Elapsed time: 9.905s
</pre>
<p>
Bazel prints the progress messages as it loads all the
packages in the transitive closure of dependencies of the requested
target, then analyzes them for correctness and to create the build actions,
finally executing the compilers and other tools of the build.
</p>
<p>
Bazel prints progress messages during
the <a href='#phases'>execution phase</a> of the build, showing the
current build step (compiler, linker, etc.) that is being started,
and the number of completed over total number of build actions. As the
build starts the number of total actions will often increase as Bazel
discovers the entire action graph, but the number will usually stabilize
within a few seconds.
</p>
<p>
At the end of the build Bazel
prints which targets were requested, whether or not they were
successfully built, and if so, where the output files can be found.
Scripts that run builds can reliably parse this output; see <a
href='#flag--show_result'><code class='flag'>--show_result</code></a> for more
details.
</p>
<p>
Typing the same command again:
</p>
<pre>
% bazel build //foo
____Loading...
____Found 1 target...
____Building complete.
Target //foo:foo up-to-date:
bazel-bin/foo/foo.bin
bazel-bin/foo/foo
____Elapsed time: 0.280s
</pre>
<p>
we see a "null" build: in this case, there are no packages to
re-load, since nothing has changed, and no build steps to execute.
(If something had changed in "foo" or some of its dependencies, resulting in the
reexecution of some build actions, we would call it an "incremental" build, not a
"null" build.)
</p>
<p>
Before you can start a build, you will need a Bazel workspace. This is
simply a directory tree that contains all the source files needed to build
your application.
Bazel allows you to perform a build from a completely read-only volume.
</p>
<h4 id='flag--package_path'>Setting up a <code class='flag'>--package_path</code></h4>
<p>
Bazel finds its packages by searching the package path. This is a colon
separated ordered list of bazel directories, each being the root of a
partial source tree.
</p>
<p>
<i>To specify a custom package path</i> using the
<code class='flag'>--package_path</code> option:
</p>
<pre>
% bazel build --package_path %workspace%:/some/other/root
</pre>
<p>
Package path elements may be specified in three formats:
</p>
<ol>
<li>
If the first character is <code>/</code>, the path is absolute.
</li>
<li>
If the path starts with <code>%workspace%</code>, the path is taken relative
to the nearest enclosing bazel directory.<br>
For instance, if your working directory
is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the
string <code>%workspace%</code> in the package-path is expanded
to <code>/home/bob/clients/bob_client/bazel</code>.
</li>
<li>
Anything else is taken relative to the working directory.<br> This is usually not what you mean to do,
and may behave unexpectedly if you use Bazel from directories below the bazel workspace.
For instance, if you use the package-path element <code>.</code>,
and then cd into the directory
<code>/home/bob/clients/bob_client/bazel/foo</code>, packages
will be resolved from the
<code>/home/bob/clients/bob_client/bazel/foo</code> directory.
</li>
</ol>
<p>
If you use a non-default package path, we recommend that you specify
it in your <a href='#bazelrc'>Bazel configuration file</a> for
convenience.
</p>
<p>
<i>Bazel doesn't require any packages to be in the
current directory</i>, so you can do a build from an empty bazel
workspace if all the necessary packages can be found somewhere else
on the package path.
</p>
<p>
<i>Example</i>: Building from an empty client
</p>
<pre>
% mkdir -p foo/bazel
% cd foo/bazel
% bazel build --package_path /some/other/path //foo
</pre>
<h3 id='target-patterns'>Specifying targets to build</h3>
<p>
Bazel allows a number of ways to specify the targets to be built.
Collectively, these are known as <i>target patterns</i>.
The on-line help displays a summary of supported patterns:
</p>
<pre>
% bazel help target-syntax
Target pattern syntax
=====================
The BUILD file label syntax is used to specify a single target. Target
patterns generalize this syntax to sets of targets, and also support
working-directory-relative forms, recursion, subtraction and filtering.
Examples:
Specifying a single target:
//foo/bar:wiz The single target '//foo/bar:wiz'.
foo/bar/wiz Equivalent to:
'//foo/bar/wiz:wiz' if foo/bar/wiz is a package,
'//foo/bar:wiz' if foo/bar is a package,
'//foo:bar/wiz' otherwise.
//foo/bar Equivalent to '//foo/bar:bar'.
Specifying all rules in a package:
//foo/bar:all Matches all rules in package 'foo/bar'.
Specifying all rules recursively beneath a package:
//foo/...:all Matches all rules in all packages beneath directory 'foo'.
//foo/... (ditto)
Working-directory relative forms: (assume cwd = 'workspace/foo')
Target patterns which do not begin with '//' are taken relative to
the working directory. Patterns which begin with '//' are always
absolute.
...:all Equivalent to '//foo/...:all'.
... (ditto)
bar/...:all Equivalent to '//foo/bar/...:all'.
bar/... (ditto)
bar:wiz Equivalent to '//foo/bar:wiz'.
:foo Equivalent to '//foo:foo'.
bar Equivalent to '//foo/bar:bar'.
foo/bar Equivalent to '//foo/bar/bar:bar'.
bar:all Equivalent to '//foo/bar:all'.
:all Equivalent to '//foo:all'.
Summary of target wildcards:
:all, Match all rules in the specified packages.
:*, :all-targets Match all targets (rules and files) in the specified
packages, including ones not built by default, such
as _deploy.jar files.
Subtractive patterns:
Target patterns may be preceded by '-', meaning they should be
subtracted from the set of targets accumulated by preceding
patterns. (Note that this means order matters.) For example:
% bazel build -- foo/... -foo/contrib/...
builds everything in 'foo', except 'contrib'. In case a target not
under 'contrib' depends on something under 'contrib' though, in order to
build the former bazel has to build the latter too. As usual, the '--' is
required to prevent '-f' from being interpreted as an option.
</pre>
<p>
Whereas <a href="build-ref.html#labels">labels</a> are used
to specify individual targets, e.g. for declaring dependencies in
BUILD files, Bazel's target patterns are a syntax for specifying
multiple targets: they are a generalization of the label syntax
for <i>sets</i> of targets, using wildcards. In the simplest case,
any valid label is also a valid target pattern, identifying a set of
exactly one target.
</p>
<p>
<code>foo/...</code> is a wildcard over <em>packages</em>,
indicating all packages recursively beneath
directory <code>foo</code> (for all roots of the package
path). <code>:all</code> (or <code>:all-rules</code>) is a wildcard
over <em>targets</em>, matching all rules within a package. These two may be
combined, as in <code>foo/...:all</code>, and when both wildcards
are used, this may be abbreviated to <code>foo/...</code>.
</p>
<p>
In addition, <code>:*</code> (or <code>:all-targets</code>) is a
wildcard that matches <em>every target</em> in the matched packages,
including files that aren't normally built by any rule, such
as <code>_deploy.jar</code> files associated
with <code>java_binary</code> rules.
</p>
<p>
This implies that <code>:*</code> denotes a <em>superset</em>
of <code>:all</code>; while potentially confusing, this syntax does
allow the familiar <code>:all</code> wildcard to be used for
typical builds, where building targets like the <code>_deploy.jar</code>
is not desired.
</p>
<p>
In addition, Bazel allows a slash to be used instead of the colon
required by the label syntax; this is often convenient when using
Bash filename expansion. For example, <code>foo/bar/wiz</code> is
equivalent to <code>//foo/bar:wiz</code> (if there is a
package <code>foo/bar</code>) or to <code>//foo:bar/wiz</code> (if
there is a package <code>foo</code>).
</p>
<p>
Many Bazel commands accept a list of target patterns as arguments,
and they all honor the prefix negation operator `<code>-</code>'.
This can be used to subtract a set of targets from the set specified
by the preceding arguments. (Note that this means order matters.)
For example,
</p>
<pre>
bazel build foo/... bar/...
</pre>
<p>
means "build all
targets beneath <code>foo</code> <i>and</i> all targets
beneath <code>bar</code>", whereas
</p>
<pre>
bazel build -- foo/... -foo/bar/...
</pre>
<p>
means "build all targets beneath <code>foo</code> <i>except</i>
those beneath <code>foo/bar</code>".
(The <code>--</code> argument is required to prevent the subsequent
arguments starting with <code>-</code> from being interpreted as
additional options.)
</p>
<p>
It's important to point out though that subtracting targets this way will not
guarantee that they are not built, since they may be dependencies of targets
that weren't subtracted. For example, if there were a target
<code>//foo:all-apis</code> that among others depended on
<code>//foo/bar:api</code>, then the latter would be built as part of
building the former.
</p>
<p>
Targets with <code>tags=["manual"]</code> will be ignored by all command line
wildcards (..., :*, :all, etc). The only way to run such targets is to
specify them explicitly on the command line.
</p>
<h3 id='configurations'>Build configurations and cross-compilation</h3>
<p>
All the inputs that specify the behavior and result of a given
build can be divided into two distinct categories.
The first kind is the intrinsic information stored in the BUILD
files of your project: the build rule, the values of its attributes,
and the complete set of its transitive dependencies.
The second kind is the external or environmental data, supplied by
the user or by the build tool: the choice of target architecture,
compilation and linking options, and other toolchain configuration
options. We refer to a complete set of environmental data as
a <b>configuration</b>.
</p>
<p>
In any given build, there may be more than one configuration.
Consider a cross-compile, in which you build
a <code>//foo:bin</code> executable for a 64-bit architecture,
but your workstation is a 32-bit machine. Clearly, the build
will require building <code>//foo:bin</code> using a toolchain
capable of creating 64-bit executables, but the build system must
also build various tools used during the build itself—for example
tools that are built from source, then subsequently used in, say, a
genrule—and these must be built to run on your workstation.
Thus we can identify two configurations: the <b>host
configuration</b>, which is used for building tools that run during
the build, and the <b>target configuration</b> (or <i>request
configuration</i>, but we say "target configuration" more often even
though that word already has many meanings), which is
used for building the binary you ultimately requested.
</p>
<p>
Typically, there are many libraries that are prerequisites of both
the requested build target (<code>//foo:bin</code>) and one or more of
the host tools, for example some base libraries. Such libraries must be built
twice, once for the host configuration, and once for the target
configuration.<br/>
Bazel takes care of ensuring that both variants are built, and that
the derived files are kept separate to avoid interference; usually
such targets can be built concurrently, since they are independent
of each other. If you see progress messages indicating that a given
target is being built twice, this is most likely the explanation.
</p>
<p>
Bazel uses one of two ways to select the host configuration, based
on the <code class='flag'>--distinct_host_configuration</code> option. This
boolean option is somewhat subtle, and the setting may improve (or
worsen) the speed of your builds.
</p>
<h4><code class='flag'>--distinct_host_configuration=false</code></h4>
<p>
When this option is false, the host and
request configurations are identical: all tools required during the
build will be built in exactly the same way as target programs.
This setting means that no libraries need to be built twice during a
single build, so it keeps builds short.
However, it does mean that any change to your request configuration
also affects your host configuration, causing all the tools to be
rebuilt, and then anything that depends on the tool output to be
rebuilt too. Thus, for example, simply changing a linker option
between builds might cause all tools to be re-linked, and then all
actions using them reexecuted, and so on, resulting in a very large rebuild.
Also, please note: if your host architecture is not capable of
running your target binaries, your build will not work.
</p>
<p>
If you frequently make changes to your request configuration, such
as alternating between <code>-c opt</code> and <code>-c dbg</code>
builds, or between simple- and cross-compilation, we do not
recommend this option, as you will typically rebuild the majority of
your codebase each time you switch.
</p>
<h4><code class='flag'>--distinct_host_configuration=true</code> <i>(default)</i></h4>
<p>
If this option is true, then instead of using the same configuration
for the host and request, a completely distinct host configuration
is used. The host configuration is derived from the target
configuration as follows:
</p>
<ul>
<li>Use the same version of Crosstool
(<code class='flag'>--crosstool_top</code>) as specified in the request
configuration.
</li>
<li>
Use the value of <code class="flag">--host_cpu</code> for
<code class='flag'>--cpu</code>
and <code class='flag'>--java_cpu</code> (default: <code>k8</code>).
</li>
<li>Use the same values of these options as specified in the request
configuration:
<code class='flag'>--compiler</code>,
<code class='flag'>--thin_archives</code>,
<code class='flag'>--use_ijars</code>,
<code class='flag'>--java_langtools</code>,
<code class='flag'>--javabuilder_top</code>.
</li>
<li>Use optimized builds for C++ code (<code>-c opt</code>).
</li>
<li>Generate no debugging information (<code class='flag'>--copt=-g0</code>).
</li>
<li>Strip debug information from executables and shared libraries
(<code class='flag'>--strip=always</code>).
</li>
<li>Place all derived files in a special location, distinct from
that used by any possible request configuration.
</li>
<li>Suppress stamping of binaries with build data
(see <code class='flag'>--embed_*</code> options).
</li>
<li>All other values remain at their defaults.
</li>
</ul>
<p>
There are many reasons why it might be preferable to select a
distinct host configuration from the request configuration.
Some are too esoteric to mention here, but two of them are worth
pointing out.
</p>
<p>
Firstly, by using stripped, optimized binaries, you reduce the time
spent linking and executing the tools, the disk space occupied by
the tools, and the network I/O time in distributed builds.
</p>
<p>
Secondly, by decoupling the host and request configurations in all
builds, you avoid very expensive rebuilds that would result from
minor changes to the request configuration (such as changing a linker options
does), as described earlier.
</p>
<p>
That said, for certain builds, this option may be a hindrance. In
particular, builds in which changes of configuration are infrequent
(especially certain Java builds), and builds where the amount of code that
must be built in both host and target configurations is large, may
not benefit.
</p>
<h3 id='correctness'>Correct incremental rebuilds</h3>
<p>
One of the primary goals of the Bazel project is to ensure correct
incremental rebuilds. Previous build tools, especially those based
on Make, make several unsound assumptions in their implementation of
incremental builds.
</p>
<p>
Firstly, that timestamps of files increase monotonically. While
this is the typical case, it is very easy to fall afoul of this
assumption; syncing to an earlier revision of a file causes that file's
modification time to decrease; Make-based systems will not rebuild.
</p>
<p>
More generally, while Make detects changes to files, it does
not detect changes to commands. If you alter the options passed to
the compiler in a given build step, Make will not re-run the
compiler, and it is necessary to manually discard the invalid
outputs of the previous build using <code>make clean</code>.
</p>
<p>
Also, Make is not robust against the unsuccessful termination of one
of its subprocesses after that subprocess has started writing to
its output file. While the current execution of Make will fail, the
subsequent invocation of Make will blindly assume that the truncated
output file is valid (because it is newer than its inputs), and it
will not be rebuilt. Similarly, if the Make process is killed, a
similar situation can occur.
</p>
<p>
Bazel avoids these assumptions, and others. Bazel maintains a database
of all work previously done, and will only omit a build step if it
finds that the set of input files (and their timestamps) to that
build step, and the compilation command for that build step, exactly
match one in the database, and, that the set of output files (and
their timestamps) for the database entry exactly match the
timestamps of the files on disk. Any change to the input files or
output files, or to the command itself, will cause re-execution of
the build step.
</p>
<p>
The benefit to users of correct incremental builds is: less time
wasted due to confusion. (Also, less time spent waiting for
rebuilds caused by use of <code>make clean</code>, whether necessary
or pre-emptive.)
</p>
<h4>Build consistency and incremental builds</h4>
<p>
Formally, we define the state of a build as <i>consistent</i> when
all the expected output files exist, and their contents are correct,
as specified by the steps or rules required to create them. When
you edit a source file, the state of the build is said to
be <i>inconsistent</i>, and remains inconsistent until you next run
the build tool to successful completion. We describe this situation
as <i>unstable inconsistency</i>, because it is only temporary, and
consistency is restored by running the build tool.
</p>
<p>
There is another kind of inconsistency that is pernicious: <i>stable
inconsistency</i>. If the build reaches a stable inconsistent
state, then repeated successful invocation of the build tool does
not restore consistency: the build has gotten "stuck", and the
outputs remain incorrect. Stable inconsistent states are the main
reason why users of Make (and other build tools) type <code>make
clean</code>. Discovering that the build tool has failed in this
manner (and then recovering from it) can be time consuming and very
frustrating.
</p>
<p>
Conceptually, the simplest way to achieve a consistent build is to
throw away all the previous build outputs and start again: make
every build a clean build. This approach is obviously too
time-consuming to be practical (except perhaps for release
engineers), and therefore to be useful, the build tool must be able
to perform incremental builds without compromising consistency.
</p>
<p>
Correct incremental dependency analysis is hard, and as described
above, many other build tools do a poor job of avoiding stable
inconsistent states during incremental builds. In contrast, Bazel
offers the following guarantee: after a successful invocation of the
build tool during which you made no edits, the build will be in a
consistent state. (If you edit your source files during a build,
Bazel makes no guarantee about the consistency of the result of the
current build. But it does guarantee that the results of
the <i>next</i> build will restore consistency.)
</p>
<p>
As with all guarantees, there comes some fine print: there are some
known ways of getting into a stable inconsistent state with Bazel.
We won't guarantee to investigate such problems arising from deliberate
attempts to find bugs in the incremental dependency analysis, but we
will investigate and do our best to fix all stable inconsistent
states arising from normal or "reasonable" use of the build tool.
</p>
<p>
If you ever detect a stable inconsistent state with Bazel, please report a bug.
</p>
<h3 id='clean'>Deleting the outputs of a build</h3>
<h4>The <code>clean</code> command</h4>
<p>
Bazel has a <code>clean</code> command, analogous to that of Make.
It deletes the output directories for all build configurations performed
by this Bazel instance, or the entire working tree created by this
Bazel instance, and resets internal caches. If executed without any
command-line options, then the output directory for all configurations
will be cleaned.
</p>
<p>Recall that each Bazel instance is associated with a single workspace, thus the
<code>clean</code> command will delete all outputs from all builds you've done
with that Bazel instance in that workspace.
</p>
<p>
To completely remove the entire working tree created by a Bazel
instance, you can specify the <code class='flag'>--expunge</code> option. When
executed with <code class='flag'>--expunge</code>, the clean command simply
removes the entire output base tree which, in addition to the build
output, contains all temp files created by Bazel. It also
stops the Bazel server after the clean, equivalent to the <a
href='#shutdown'><code>shutdown</code></a> command. For example, to
clean up all disk and memory traces of a Bazel instance, you could
specify:
</p>
<pre>
% bazel clean --expunge
</pre>
<p>
Alternatively, you can expunge in the background by using
<code class='flag'>--expunge_async</code>. It is safe to invoke a Bazel command
in the same client while the asynchronous expunge continues to run.
Note, however, that this may introduce IO contention.
</p>
<p>
The <code>clean</code> command is provided primarily as a means of
reclaiming disk space for workspaces that are no longer needed.
However, we recognize that Bazel's incremental rebuilds might not be
perfect; <code>clean</code> may be used to recover a consistent
state when problems arise.
</p>
<p>
Bazel's design is such that these problems are fixable; we consider
such bugs a high priority, and will do our best fix them. If you
ever find an incorrect incremental build, please file a bug report.
We encourage developers to get out of the habit of
using <code>clean</code> and into that of reporting bugs in the
tools.
</p>
<h4 id='rm'><code>bazel rm</code></h4>
<p>
<code>bazel rm</code> is a more limited form of <code>clean</code>,
that deletes only the named files. For example:
</p>
<pre>
% bazel rm bazel-bin/foo/libfoo.a
</pre>
<p>
Some users use <code>bazel rm</code> when performing timing
experiments of a particular build step: by deleting a single file
and running a build, only that file (and others that depend on it)
will be rebuilt.
</p>
<h3 id='phases'>Phases of a build</h3>
<p>
In Bazel, a build occurs in three distinct phases; as a user,
understanding the difference between them provides insight into the
options which control a build (see below).
</p>
<h4 id='loading-phase'>Loading phase</h4>
<p>
The first is <b>loading</b> during which all the necessary BUILD
files for the initial targets, and their transitive closure of
dependencies, are loaded, parsed, evaluated and cached.
</p>
<p>
For the first build after a Bazel server is started, the loading
phase typically takes many seconds as many BUILD files are loaded
from the file system. In subsequent builds, especially if no BUILD
files have changed, loading occurs very quickly.
</p>
<p>
Errors reported during this phase include: package not found, target
not found, lexical and grammatical errors in a BUILD file,
and evaluation errors.
</p>
<h4 id='analysis-phase'>Analysis phase</h4>
<p>
The second phase, <b>analysis</b>, involves the semantic analysis
and validation of each build rule, the construction of a build
dependency graph, and the determination of exactly what work is to
be done in each step of the build.
</p>