Generate Build Encyclopedia and Skylark API doc for Bazel.
--
MOS_MIGRATED_REVID=87515939
diff --git a/docs/historical/bazel-query-v2.html b/docs/bazel-query-v2.html
similarity index 61%
rename from docs/historical/bazel-query-v2.html
rename to docs/bazel-query-v2.html
index 8403915..815ad85 100644
--- a/docs/historical/bazel-query-v2.html
+++ b/docs/bazel-query-v2.html
@@ -4,6 +4,7 @@
<head>
<meta charset="utf-8" />
<title>Bazel Query Reference</title>
+
<style type="text/css">
body {
@@ -133,8 +134,6 @@
#maintainer { text-align: right; }
</style>
</head>
-
-
<body>
<h1>The Bazel Query Reference</h1>
@@ -147,9 +146,6 @@
formats <code>bazel query</code> supports.
</p>
-
-<div id="nav" class="nav-2-levels"></div>
-
<h2>Examples</h2>
<p>
@@ -157,15 +153,15 @@
</p>
<p>
- Why does the <code>foo</code> tree depend on <code>bar</code>?
+ Why does the <code>//foo</code> tree depend on <code>//bar/baz</code>?
Show a path:</p>
- <pre>somepath(foo/..., some_parent/bar:all)</pre>
+ <pre>somepath(foo/..., //bar/baz:all)</pre>
<p>
- What C++ libraries do the <code>foo</code> tests depend upon that
- the <code>foo</code> binary does not?</p>
- <pre>kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))</pre>
+ What C++ libraries do all the <code>foo</code> tests depend on that
+ the <code>foo_bin</code> target does not?</p>
+ <pre>kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))</pre>
<h2>Tokens: the lexical syntax</h2>
@@ -180,31 +176,31 @@
language, and each of them is described below. The complete set
of keywords is:
-<pre><!-- keep this alphabetically sorted -->
-<a href="#path-operators">allpaths</a>
-<a href="#attr">attr</a>
-<a href="#buildfiles">buildfiles</a>
-<a href="#component">component</a>
-<a href="#deps">deps</a>
-<a href="#set-operations">except</a>
-<a href="#filter">filter</a>
-<a href="#variables">in</a>
-<a href="#set-operations">intersect</a>
-<a href="#kind">kind</a>
-<a href="#labels">labels</a>
-<a href="#variables">let</a>
-<a href="#rdeps">rdeps</a>
-<a href="#set">set</a>
-<a href="#some">some</a>
-<a href="#path-operators">somepath</a>
-<a href="#tests">tests</a>
-<a href="#set-operations">union</a>
-</pre>
+<code><!-- keep this alphabetically sorted -->
+<a href="#path-operators">allpaths</a><br/>
+<a href="#attr">attr</a><br/>
+<a href="#buildfiles">buildfiles</a><br/>
+
+<a href="#deps">deps</a><br/>
+<a href="#set-operations">except</a><br/>
+<a href="#filter">filter</a><br/>
+<a href="#variables">in</a><br/>
+<a href="#set-operations">intersect</a><br/>
+<a href="#kind">kind</a><br/>
+<a href="#labels">labels</a><br/>
+<a href="#variables">let</a><br/>
+<a href="#rdeps">rdeps</a><br/>
+<a href="#set">set</a><br/>
+<a href="#some">some</a><br/>
+<a href="#path-operators">somepath</a><br/>
+<a href="#tests">tests</a><br/>
+<a href="#set-operations">union</a><br/>
+</code>
</li>
- <li><b>Words</b>, such as <code>foo/...</code> or <!--sic, for
- clarity--> <code>".*test rule"</code> or
- <code>some_parent/bar:all</code>.
+ <li><b>Words</b>, such as <code>foo/...</code> or
+ <code>".*test rule"</code> or
+ <code>//bar/baz:all</code>.
If a character sequence is "quoted" (begins and ends with a
single-quote <code>'</code>, or begins and ends with a
double-quote <code>"</code>), it is a word.
@@ -224,6 +220,7 @@
<p>
Quoting <em>is</em> necessary when writing scripts that
construct Bazel query expressions from user-supplied values.
+
</p>
<pre>
//foo:bar+wiz # WRONG: scanned as //foo:bar + wiz.
@@ -270,8 +267,9 @@
<h3>Cycles in the dependency graph</h3>
<p>
- Build dependency graphs should be acyclic, but in fact cycles do
- occur. The algorithms used by the query language are intended for use in
+ Build dependency graphs should be acyclic, but in fact cycles do occur.
+
+ The algorithms used by the query language are intended for use in
acyclic graphs, but are robust against cycles. The details of how
cycles are treated are not specified and should not be relied upon.
</p>
@@ -279,6 +277,15 @@
<h3 id='implicit_deps'>Implicit dependencies</h3>
<p>
+ In addition to build dependencies that are defined explicitly in BUILD files,
+ Bazel adds additional <em>implicit</em> dependencies to rules. For example
+ every Java rule implicitly depends on the JavaBuilder. Implicit dependencies
+ are established using attributes that start with <code>$</code> and they
+ cannot overridden in BUILD files.
+
+</p>
+
+<p>
Per default <code>bazel query</code> takes implicit dependencies into account
when computing the query result. This behavior can be changed with
the <code>--[no]implicit_deps</code> option.
@@ -287,6 +294,17 @@
<h3 id='soundness'>Soundness</h3>
<p>
+ Bazel query language expressions operate over the build
+ dependency graph, which is the graph implicitly defined by all
+ rule declarations in all BUILD files. It is important to understand
+ that this graph is somewhat abstract, and does not constitute a
+ complete description of how to perform all the steps of a build. In
+ order to perform a build, a <em>configuration</em> is required too;
+ see the <a href='bazel-user-manual.html#configurations'>configurations</a>
+ section of the User's Guide for more detail.
+</p>
+
+<p>
The result of evaluating an expression in the Bazel query language
is true <em>for all configurations</em>, which means that it may be
a conservative over-approximation, and not exactly precise. If you
@@ -305,6 +323,7 @@
set of files mentioned in the Makefile obtained
from <a href='bazel-user-manual.html#--dump_makefile'><code>bazel
build --dump_makefile</code></a>.
+
</p>
<h3 id='graph-order'>On the preservation of graph order</h3>
@@ -396,8 +415,8 @@
is interpreted as an (unordered) set of targets. The simplest
target pattern is a label,
which identifies a single target (file or rule). For example, the
- target pattern <code>//abc:xyz</code> evaluates to a set
- containing one element, the target, the <code>xyz</code>
+ target pattern <code>//foo:bar</code> evaluates to a set
+ containing one element, the target, the <code>bar</code>
rule.
</p>
@@ -407,18 +426,18 @@
just <code>foo/...</code>) is a target pattern that evaluates to a
set containing all <em>rules</em> in every package recursively
beneath the <code>foo</code> directory;
- <code>some_parent/bar:all</code> is a target pattern that
+ <code>bar/baz:all</code> is a target pattern that
evaluates to a set containing all the rules in the
- <code>some_parent/bar</code> package, but not its subpackages.
+ <code>bar/baz</code> package, but not its subpackages.
</p>
<p>
Similarly, <code>foo/...:*</code> is a target pattern that evaluates
to a set containing all <em>targets</em> (rules <em>and</em> files) in
every package recursively beneath the <code>foo</code> directory;
- <code>some_parent/bar:*</code> evaluates to a set containing
+ <code>bar/baz:*</code> evaluates to a set containing
all the targets in the
- <code>some_parent/bar</code> package, but not its subpackages.
+ <code>bar/baz</code> package, but not its subpackages.
</p>
<p>
@@ -435,6 +454,7 @@
refer to <a href='bazel-user-manual.html#target-patterns'>Target Patterns</a>
in the Bazel User Manual for further details, or type <code>bazel
help target-syntax</code>.
+
</p>
<p>
@@ -538,13 +558,13 @@
this manual uses the nominal forms.) For example,
</p>
-<pre>xyz/... except xyz/contrib/...</pre>
+<pre>foo/... except foo/bar/...</pre>
evaluates to the set of targets that match
- <code>xyz/...</code> but not
- <code>xyz/contrib/...</code> . Equivalently:
+ <code>foo/...</code> but not
+ <code>foo/bar/...</code> . Equivalently:
-<pre>xyz/... - xyz/contrib/...</pre>
+<pre>foo/... - foo/bar/...</pre>
The <code>intersect</code> (<code>^</code>)
and <code>union</code> (<code>+</code>) operations are commutative
@@ -581,18 +601,18 @@
further processing. For example:
</p>
<pre>
- % bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
+ % bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
% bazel query "kind(cc_binary, set($(<foo)))"
</pre>
<p>
In the next example, <code>kind(cc_library,
- deps(//dir1/bazel/main:bazel, 5))</code> is effectively computed
+ deps(//some_dir/foo:main, 5))</code> is effectively computed
by filtering on the <code>maxrank</code> values using
an <code>awk</code> program.
</p>
<pre>
- % bazel query 'deps(//dir1/bazel/main:bazel)' --output maxrank |
- awk '($1 < 5) { print $2;} ' > foo
+ % bazel query 'deps(//some_dir/foo:main)' --output maxrank |
+ awk '($1 < 5) { print $2;} ' > foo
% bazel query "kind(cc_library, set($(<foo)))"
</pre>
<p>
@@ -662,7 +682,7 @@
search. The resulting graph will only include nodes within a distance of the
specified depth from any node in the argument set. So
<code>rdeps(//foo, //common, 1)</code> evaluates to all nodes in the
- transitive closure of <code>//foo</code> that directly depend on
+ transitive closure of <code>//common</code> that directly depend on
<code>//common</code>. (These numbers correspond to the ranks shown in the
<a href='#output-ranked'><code>minrank</code></a> output format.) If the
<var>depth</var> parameter is omitted, the search is unbounded.
@@ -674,19 +694,18 @@
The <code>some(<var>x</var>)</code> operator selects one target
arbitrarily from its argument set <var>x</var>, and evaluates to a
singleton set containing only that target. For example, the
- expression <code>some(//foo:foo union //xyz:abc)</code>
- evaluates to a set containing either <code>//foo:foo</code> or
- <code>//xyz:abc</code>—though which one is not defined.
+ expression <code>some(//foo:main union //bar:baz)</code>
+ evaluates to a set containing either <code>//foo:main</code> or
+ <code>//bar:baz</code>—though which one is not defined.
</p>
<p>
If the argument is a singleton, then <code>some</code>
- computes the identity function: <code>some(//foo:foo)</code> is
- equivalent to <code>//foo:foo</code>.
+ computes the identity function: <code>some(//foo:main)</code> is
+ equivalent to <code>//foo:main</code>.
It is an error if the specified argument set is empty, as in the
- expression <code>some(//foo:foo intersect
- //xyz:abc)</code>.
+ expression <code>some(//foo:main intersect //bar:baz)</code>.
</p>
<h3 id="path-operators">Path operators: somepath, allpaths</h3>
@@ -711,91 +730,358 @@
</p>
<table style='margin: auto'><tr>
-<td style='text-align: center'><div class='graphviz dot'><!--
-digraph somepath1 {
- graph [size="4,4"]
- node [label="",shape=circle];
- n1;
- n2 [fillcolor="pink",style=filled];
- n3 [fillcolor="pink",style=filled];
- n4 [fillcolor="pink",style=filled,label="E"];
- n5; n6;
- n7 [fillcolor="pink",style=filled,label="S1"];
- n8 [label="S2"];
- n9;
- n10 [fillcolor="pink",style=filled];
-
- n1 -> n2;
- n2 -> n3;
- n7 -> n5;
- n7 -> n2;
- n5 -> n6;
- n6 -> n4;
- n8 -> n6;
- n6 -> n9;
- n2 -> n10;
- n3 -> n10;
- n10 -> n4;
- n10 -> n11;
-}--></div>
+<td style='text-align: center'>
+<!-- Title: somepath1 Pages: 1 -->
+<svg width="154pt" height="288pt"
+ viewBox="0.00 0.00 153.82 288.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(0.818182 0.818182) rotate(0) translate(4 348)">
+<title>somepath1</title>
+<polygon style="fill:white;stroke:white;" points="-4,4 -4,-348 184,-348 184,4 -4,4"/>
+<!-- n1 -->
+<g id="node1" class="node"><title>n1</title>
+<ellipse style="fill:none;stroke:black;" cx="39" cy="-321" rx="18" ry="18"/>
+</g>
+<!-- n2 -->
+<g id="node2" class="node"><title>n2</title>
+<ellipse style="fill:pink;stroke:black;" cx="41" cy="-239" rx="18" ry="18"/>
+</g>
+<!-- n1->n2 -->
+<g id="edge2" class="edge"><title>n1->n2</title>
+<path style="fill:none;stroke:black;" d="M39,-303C40,-292 40,-279 40,-267"/>
+<polygon style="fill:black;stroke:black;" points="43.4875,-267.299 41,-257 36.5222,-266.602 43.4875,-267.299"/>
+</g>
+<!-- n3 -->
+<g id="node3" class="node"><title>n3</title>
+<ellipse style="fill:pink;stroke:black;" cx="18" cy="-162" rx="18" ry="18"/>
+</g>
+<!-- n2->n3 -->
+<g id="edge4" class="edge"><title>n2->n3</title>
+<path style="fill:none;stroke:black;" d="M36,-222C33,-212 29,-200 26,-190"/>
+<polygon style="fill:black;stroke:black;" points="29.2259,-188.573 23,-180 22.5212,-190.584 29.2259,-188.573"/>
+</g>
+<!-- n10 -->
+<g id="node10" class="node"><title>n10</title>
+<ellipse style="fill:pink;stroke:black;" cx="37" cy="-90" rx="18" ry="18"/>
+</g>
+<!-- n2->n10 -->
+<g id="edge18" class="edge"><title>n2->n10</title>
+<path style="fill:none;stroke:black;" d="M43,-221C45,-202 47,-171 45,-144 44,-136 43,-126 42,-118"/>
+<polygon style="fill:black;stroke:black;" points="45.3933,-117.119 40,-108 38.5292,-118.492 45.3933,-117.119"/>
+</g>
+<!-- n3->n10 -->
+<g id="edge20" class="edge"><title>n3->n10</title>
+<path style="fill:none;stroke:black;" d="M23,-145C25,-136 27,-126 30,-117"/>
+<polygon style="fill:black;stroke:black;" points="33.4708,-117.492 32,-107 26.6067,-116.119 33.4708,-117.492"/>
+</g>
+<!-- n4 -->
+<g id="node4" class="node"><title>n4</title>
+<ellipse style="fill:pink;stroke:black;" cx="87" cy="-18" rx="18" ry="18"/>
+<text text-anchor="middle" x="87" y="-13.4" style="font-family:arial;font-size:14.00;">E</text>
+</g>
+<!-- n5 -->
+<g id="node5" class="node"><title>n5</title>
+<ellipse style="fill:none;stroke:black;" cx="98" cy="-239" rx="18" ry="18"/>
+</g>
+<!-- n6 -->
+<g id="node6" class="node"><title>n6</title>
+<ellipse style="fill:none;stroke:black;" cx="123" cy="-162" rx="18" ry="18"/>
+</g>
+<!-- n5->n6 -->
+<g id="edge10" class="edge"><title>n5->n6</title>
+<path style="fill:none;stroke:black;" d="M104,-222C107,-212 111,-200 114,-189"/>
+<polygon style="fill:black;stroke:black;" points="117.479,-189.584 117,-179 110.774,-187.573 117.479,-189.584"/>
+</g>
+<!-- n6->n4 -->
+<g id="edge12" class="edge"><title>n6->n4</title>
+<path style="fill:none;stroke:black;" d="M117,-145C114,-134 109,-120 106,-108 100,-87 95,-64 92,-46"/>
+<polygon style="fill:black;stroke:black;" points="95.3933,-45.1194 90,-36 88.5292,-46.4922 95.3933,-45.1194"/>
+</g>
+<!-- n9 -->
+<g id="node9" class="node"><title>n9</title>
+<ellipse style="fill:none;stroke:black;" cx="133" cy="-90" rx="18" ry="18"/>
+</g>
+<!-- n6->n9 -->
+<g id="edge16" class="edge"><title>n6->n9</title>
+<path style="fill:none;stroke:black;" d="M126,-144C127,-136 128,-127 129,-118"/>
+<polygon style="fill:black;stroke:black;" points="132.488,-118.299 130,-108 125.522,-117.602 132.488,-118.299"/>
+</g>
+<!-- n7 -->
+<g id="node7" class="node"><title>n7</title>
+<ellipse style="fill:pink;stroke:black;" cx="98" cy="-321" rx="22.8079" ry="22.8079"/>
+<text text-anchor="middle" x="98" y="-316.4" style="font-family:arial;font-size:14.00;">S1</text>
+</g>
+<!-- n7->n2 -->
+<g id="edge8" class="edge"><title>n7->n2</title>
+<path style="fill:none;stroke:black;" d="M85,-302C77,-290 66,-275 57,-262"/>
+<polygon style="fill:black;stroke:black;" points="59.8,-259.9 51,-254 54.2,-264.1 59.8,-259.9"/>
+</g>
+<!-- n7->n5 -->
+<g id="edge6" class="edge"><title>n7->n5</title>
+<path style="fill:none;stroke:black;" d="M98,-298C98,-288 98,-277 98,-267"/>
+<polygon style="fill:black;stroke:black;" points="101.5,-267 98,-257 94.5001,-267 101.5,-267"/>
+</g>
+<!-- n8 -->
+<g id="node8" class="node"><title>n8</title>
+<ellipse style="fill:none;stroke:black;" cx="157" cy="-239" rx="22.8079" ry="22.8079"/>
+<text text-anchor="middle" x="157" y="-234.4" style="font-family:arial;font-size:14.00;">S2</text>
+</g>
+<!-- n8->n6 -->
+<g id="edge14" class="edge"><title>n8->n6</title>
+<path style="fill:none;stroke:black;" d="M148,-218C144,-209 139,-198 135,-188"/>
+<polygon style="fill:black;stroke:black;" points="138.26,-186.717 131,-179 131.863,-189.56 138.26,-186.717"/>
+</g>
+<!-- n10->n4 -->
+<g id="edge22" class="edge"><title>n10->n4</title>
+<path style="fill:none;stroke:black;" d="M47,-75C54,-66 63,-52 71,-41"/>
+<polygon style="fill:black;stroke:black;" points="73.8,-43.1 77,-33 68.2,-38.9 73.8,-43.1"/>
+</g>
+<!-- n11 -->
+<g id="node23" class="node"><title>n11</title>
+<ellipse style="fill:none;stroke:black;" cx="33" cy="-18" rx="18" ry="18"/>
+</g>
+<!-- n10->n11 -->
+<g id="edge24" class="edge"><title>n10->n11</title>
+<path style="fill:none;stroke:black;" d="M36,-72C35,-64 35,-55 35,-46"/>
+<polygon style="fill:black;stroke:black;" points="38.4778,-45.6021 34,-36 31.5125,-46.2987 38.4778,-45.6021"/>
+</g>
+</g>
+</svg>
<p><code>somepath(S1 + S2, E)</code>,<br/>one possible result.</p>
</td>
-<td style='padding: 40px; text-align: center'><div class='graphviz dot'><!--
-digraph somepath2 {
- graph [size="4,4"]
- node [label="",shape=circle];
-
- n1; n2; n3;
- n4 [fillcolor="pink",style=filled,label="E"];
- n5;
- n6 [fillcolor="pink",style=filled];
- n7 [label="S1"];
- n8 [fillcolor="pink",style=filled,label="S2"];
- n9; n10;
-
- n1 -> n2;
- n2 -> n3;
- n7 -> n5;
- n7 -> n2;
- n5 -> n6;
- n6 -> n4;
- n8 -> n6;
- n6 -> n9;
- n2 -> n10;
- n3 -> n10;
- n10 -> n4;
- n10 -> n11;
-}--></div>
+<td style='padding: 40px; text-align: center'>
+<!-- Title: somepath2 Pages: 1 -->
+<svg width="154pt" height="288pt"
+ viewBox="0.00 0.00 153.82 288.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(0.818182 0.818182) rotate(0) translate(4 348)">
+<title>somepath2</title>
+<polygon style="fill:white;stroke:white;" points="-4,4 -4,-348 184,-348 184,4 -4,4"/>
+<!-- n1 -->
+<g id="node1" class="node"><title>n1</title>
+<ellipse style="fill:none;stroke:black;" cx="39" cy="-321" rx="18" ry="18"/>
+</g>
+<!-- n2 -->
+<g id="node2" class="node"><title>n2</title>
+<ellipse style="fill:none;stroke:black;" cx="41" cy="-239" rx="18" ry="18"/>
+</g>
+<!-- n1->n2 -->
+<g id="edge2" class="edge"><title>n1->n2</title>
+<path style="fill:none;stroke:black;" d="M39,-303C40,-292 40,-279 40,-267"/>
+<polygon style="fill:black;stroke:black;" points="43.4875,-267.299 41,-257 36.5222,-266.602 43.4875,-267.299"/>
+</g>
+<!-- n3 -->
+<g id="node3" class="node"><title>n3</title>
+<ellipse style="fill:none;stroke:black;" cx="18" cy="-162" rx="18" ry="18"/>
+</g>
+<!-- n2->n3 -->
+<g id="edge4" class="edge"><title>n2->n3</title>
+<path style="fill:none;stroke:black;" d="M36,-222C33,-212 29,-200 26,-190"/>
+<polygon style="fill:black;stroke:black;" points="29.2259,-188.573 23,-180 22.5212,-190.584 29.2259,-188.573"/>
+</g>
+<!-- n10 -->
+<g id="node10" class="node"><title>n10</title>
+<ellipse style="fill:none;stroke:black;" cx="37" cy="-90" rx="18" ry="18"/>
+</g>
+<!-- n2->n10 -->
+<g id="edge18" class="edge"><title>n2->n10</title>
+<path style="fill:none;stroke:black;" d="M43,-221C45,-202 47,-171 45,-144 44,-136 43,-126 42,-118"/>
+<polygon style="fill:black;stroke:black;" points="45.3933,-117.119 40,-108 38.5292,-118.492 45.3933,-117.119"/>
+</g>
+<!-- n3->n10 -->
+<g id="edge20" class="edge"><title>n3->n10</title>
+<path style="fill:none;stroke:black;" d="M23,-145C25,-136 27,-126 30,-117"/>
+<polygon style="fill:black;stroke:black;" points="33.4708,-117.492 32,-107 26.6067,-116.119 33.4708,-117.492"/>
+</g>
+<!-- n4 -->
+<g id="node4" class="node"><title>n4</title>
+<ellipse style="fill:pink;stroke:black;" cx="87" cy="-18" rx="18" ry="18"/>
+<text text-anchor="middle" x="87" y="-13.4" style="font-family:arial;font-size:14.00;">E</text>
+</g>
+<!-- n5 -->
+<g id="node5" class="node"><title>n5</title>
+<ellipse style="fill:none;stroke:black;" cx="98" cy="-239" rx="18" ry="18"/>
+</g>
+<!-- n6 -->
+<g id="node6" class="node"><title>n6</title>
+<ellipse style="fill:pink;stroke:black;" cx="123" cy="-162" rx="18" ry="18"/>
+</g>
+<!-- n5->n6 -->
+<g id="edge10" class="edge"><title>n5->n6</title>
+<path style="fill:none;stroke:black;" d="M104,-222C107,-212 111,-200 114,-189"/>
+<polygon style="fill:black;stroke:black;" points="117.479,-189.584 117,-179 110.774,-187.573 117.479,-189.584"/>
+</g>
+<!-- n6->n4 -->
+<g id="edge12" class="edge"><title>n6->n4</title>
+<path style="fill:none;stroke:black;" d="M117,-145C114,-134 109,-120 106,-108 100,-87 95,-64 92,-46"/>
+<polygon style="fill:black;stroke:black;" points="95.3933,-45.1194 90,-36 88.5292,-46.4922 95.3933,-45.1194"/>
+</g>
+<!-- n9 -->
+<g id="node9" class="node"><title>n9</title>
+<ellipse style="fill:none;stroke:black;" cx="133" cy="-90" rx="18" ry="18"/>
+</g>
+<!-- n6->n9 -->
+<g id="edge16" class="edge"><title>n6->n9</title>
+<path style="fill:none;stroke:black;" d="M126,-144C127,-136 128,-127 129,-118"/>
+<polygon style="fill:black;stroke:black;" points="132.488,-118.299 130,-108 125.522,-117.602 132.488,-118.299"/>
+</g>
+<!-- n7 -->
+<g id="node7" class="node"><title>n7</title>
+<ellipse style="fill:none;stroke:black;" cx="98" cy="-321" rx="22.8079" ry="22.8079"/>
+<text text-anchor="middle" x="98" y="-316.4" style="font-family:arial;font-size:14.00;">S1</text>
+</g>
+<!-- n7->n2 -->
+<g id="edge8" class="edge"><title>n7->n2</title>
+<path style="fill:none;stroke:black;" d="M85,-302C77,-290 66,-275 57,-262"/>
+<polygon style="fill:black;stroke:black;" points="59.8,-259.9 51,-254 54.2,-264.1 59.8,-259.9"/>
+</g>
+<!-- n7->n5 -->
+<g id="edge6" class="edge"><title>n7->n5</title>
+<path style="fill:none;stroke:black;" d="M98,-298C98,-288 98,-277 98,-267"/>
+<polygon style="fill:black;stroke:black;" points="101.5,-267 98,-257 94.5001,-267 101.5,-267"/>
+</g>
+<!-- n8 -->
+<g id="node8" class="node"><title>n8</title>
+<ellipse style="fill:pink;stroke:black;" cx="157" cy="-239" rx="22.8079" ry="22.8079"/>
+<text text-anchor="middle" x="157" y="-234.4" style="font-family:arial;font-size:14.00;">S2</text>
+</g>
+<!-- n8->n6 -->
+<g id="edge14" class="edge"><title>n8->n6</title>
+<path style="fill:none;stroke:black;" d="M148,-218C144,-209 139,-198 135,-188"/>
+<polygon style="fill:black;stroke:black;" points="138.26,-186.717 131,-179 131.863,-189.56 138.26,-186.717"/>
+</g>
+<!-- n10->n4 -->
+<g id="edge22" class="edge"><title>n10->n4</title>
+<path style="fill:none;stroke:black;" d="M47,-75C54,-66 63,-52 71,-41"/>
+<polygon style="fill:black;stroke:black;" points="73.8,-43.1 77,-33 68.2,-38.9 73.8,-43.1"/>
+</g>
+<!-- n11 -->
+<g id="node23" class="node"><title>n11</title>
+<ellipse style="fill:none;stroke:black;" cx="33" cy="-18" rx="18" ry="18"/>
+</g>
+<!-- n10->n11 -->
+<g id="edge24" class="edge"><title>n10->n11</title>
+<path style="fill:none;stroke:black;" d="M36,-72C35,-64 35,-55 35,-46"/>
+<polygon style="fill:black;stroke:black;" points="38.4778,-45.6021 34,-36 31.5125,-46.2987 38.4778,-45.6021"/>
+</g>
+</g>
+</svg>
<p><code>somepath(S1 + S2, E)</code>,<br/>another possible result.</p>
</td>
-<td style='text-align: center'><div class='graphviz dot'><!--
-digraph somepath1 {
- graph [size="4,4"]
- node [label="",shape=circle];
- n1;
- n2 [fillcolor="pink",style=filled];
- n3 [fillcolor="pink",style=filled];
- n4 [fillcolor="pink",style=filled,label="E"];
- n5 [fillcolor="pink",style=filled];
- n6 [fillcolor="pink",style=filled];
- n7 [fillcolor="pink",style=filled, label="S1"];
- n8 [fillcolor="pink",style=filled, label="S2"];
- n9;
- n10 [fillcolor="pink",style=filled];
-
- n1 -> n2;
- n2 -> n3;
- n7 -> n5;
- n7 -> n2;
- n5 -> n6;
- n6 -> n4;
- n8 -> n6;
- n6 -> n9;
- n2 -> n10;
- n3 -> n10;
- n10 -> n4;
- n10 -> n11;
-}--></div>
+<td style='text-align: center'>
+<!-- Title: allpaths Pages: 1 -->
+<svg width="154pt" height="288pt"
+ viewBox="0.00 0.00 153.82 288.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(0.818182 0.818182) rotate(0) translate(4 348)">
+<title>allpaths</title>
+<polygon style="fill:white;stroke:white;" points="-4,4 -4,-348 184,-348 184,4 -4,4"/>
+<!-- n1 -->
+<g id="node1" class="node"><title>n1</title>
+<ellipse style="fill:none;stroke:black;" cx="39" cy="-321" rx="18" ry="18"/>
+</g>
+<!-- n2 -->
+<g id="node2" class="node"><title>n2</title>
+<ellipse style="fill:pink;stroke:black;" cx="41" cy="-239" rx="18" ry="18"/>
+</g>
+<!-- n1->n2 -->
+<g id="edge2" class="edge"><title>n1->n2</title>
+<path style="fill:none;stroke:black;" d="M39,-303C40,-292 40,-279 40,-267"/>
+<polygon style="fill:black;stroke:black;" points="43.4875,-267.299 41,-257 36.5222,-266.602 43.4875,-267.299"/>
+</g>
+<!-- n3 -->
+<g id="node3" class="node"><title>n3</title>
+<ellipse style="fill:pink;stroke:black;" cx="18" cy="-162" rx="18" ry="18"/>
+</g>
+<!-- n2->n3 -->
+<g id="edge4" class="edge"><title>n2->n3</title>
+<path style="fill:none;stroke:black;" d="M36,-222C33,-212 29,-200 26,-190"/>
+<polygon style="fill:black;stroke:black;" points="29.2259,-188.573 23,-180 22.5212,-190.584 29.2259,-188.573"/>
+</g>
+<!-- n10 -->
+<g id="node10" class="node"><title>n10</title>
+<ellipse style="fill:pink;stroke:black;" cx="37" cy="-90" rx="18" ry="18"/>
+</g>
+<!-- n2->n10 -->
+<g id="edge18" class="edge"><title>n2->n10</title>
+<path style="fill:none;stroke:black;" d="M43,-221C45,-202 47,-171 45,-144 44,-136 43,-126 42,-118"/>
+<polygon style="fill:black;stroke:black;" points="45.3933,-117.119 40,-108 38.5292,-118.492 45.3933,-117.119"/>
+</g>
+<!-- n3->n10 -->
+<g id="edge20" class="edge"><title>n3->n10</title>
+<path style="fill:none;stroke:black;" d="M23,-145C25,-136 27,-126 30,-117"/>
+<polygon style="fill:black;stroke:black;" points="33.4708,-117.492 32,-107 26.6067,-116.119 33.4708,-117.492"/>
+</g>
+<!-- n4 -->
+<g id="node4" class="node"><title>n4</title>
+<ellipse style="fill:pink;stroke:black;" cx="87" cy="-18" rx="18" ry="18"/>
+<text text-anchor="middle" x="87" y="-13.4" style="font-family:arial;font-size:14.00;">E</text>
+</g>
+<!-- n5 -->
+<g id="node5" class="node"><title>n5</title>
+<ellipse style="fill:pink;stroke:black;" cx="98" cy="-239" rx="18" ry="18"/>
+</g>
+<!-- n6 -->
+<g id="node6" class="node"><title>n6</title>
+<ellipse style="fill:pink;stroke:black;" cx="123" cy="-162" rx="18" ry="18"/>
+</g>
+<!-- n5->n6 -->
+<g id="edge10" class="edge"><title>n5->n6</title>
+<path style="fill:none;stroke:black;" d="M104,-222C107,-212 111,-200 114,-189"/>
+<polygon style="fill:black;stroke:black;" points="117.479,-189.584 117,-179 110.774,-187.573 117.479,-189.584"/>
+</g>
+<!-- n6->n4 -->
+<g id="edge12" class="edge"><title>n6->n4</title>
+<path style="fill:none;stroke:black;" d="M117,-145C114,-134 109,-120 106,-108 100,-87 95,-64 92,-46"/>
+<polygon style="fill:black;stroke:black;" points="95.3933,-45.1194 90,-36 88.5292,-46.4922 95.3933,-45.1194"/>
+</g>
+<!-- n9 -->
+<g id="node9" class="node"><title>n9</title>
+<ellipse style="fill:none;stroke:black;" cx="133" cy="-90" rx="18" ry="18"/>
+</g>
+<!-- n6->n9 -->
+<g id="edge16" class="edge"><title>n6->n9</title>
+<path style="fill:none;stroke:black;" d="M126,-144C127,-136 128,-127 129,-118"/>
+<polygon style="fill:black;stroke:black;" points="132.488,-118.299 130,-108 125.522,-117.602 132.488,-118.299"/>
+</g>
+<!-- n7 -->
+<g id="node7" class="node"><title>n7</title>
+<ellipse style="fill:pink;stroke:black;" cx="98" cy="-321" rx="22.8079" ry="22.8079"/>
+<text text-anchor="middle" x="98" y="-316.4" style="font-family:arial;font-size:14.00;">S1</text>
+</g>
+<!-- n7->n2 -->
+<g id="edge8" class="edge"><title>n7->n2</title>
+<path style="fill:none;stroke:black;" d="M85,-302C77,-290 66,-275 57,-262"/>
+<polygon style="fill:black;stroke:black;" points="59.8,-259.9 51,-254 54.2,-264.1 59.8,-259.9"/>
+</g>
+<!-- n7->n5 -->
+<g id="edge6" class="edge"><title>n7->n5</title>
+<path style="fill:none;stroke:black;" d="M98,-298C98,-288 98,-277 98,-267"/>
+<polygon style="fill:black;stroke:black;" points="101.5,-267 98,-257 94.5001,-267 101.5,-267"/>
+</g>
+<!-- n8 -->
+<g id="node8" class="node"><title>n8</title>
+<ellipse style="fill:pink;stroke:black;" cx="157" cy="-239" rx="22.8079" ry="22.8079"/>
+<text text-anchor="middle" x="157" y="-234.4" style="font-family:arial;font-size:14.00;">S2</text>
+</g>
+<!-- n8->n6 -->
+<g id="edge14" class="edge"><title>n8->n6</title>
+<path style="fill:none;stroke:black;" d="M148,-218C144,-209 139,-198 135,-188"/>
+<polygon style="fill:black;stroke:black;" points="138.26,-186.717 131,-179 131.863,-189.56 138.26,-186.717"/>
+</g>
+<!-- n10->n4 -->
+<g id="edge22" class="edge"><title>n10->n4</title>
+<path style="fill:none;stroke:black;" d="M47,-75C54,-66 63,-52 71,-41"/>
+<polygon style="fill:black;stroke:black;" points="73.8,-43.1 77,-33 68.2,-38.9 73.8,-43.1"/>
+</g>
+<!-- n11 -->
+<g id="node23" class="node"><title>n11</title>
+<ellipse style="fill:none;stroke:black;" cx="33" cy="-18" rx="18" ry="18"/>
+</g>
+<!-- n10->n11 -->
+<g id="edge24" class="edge"><title>n10->n11</title>
+<path style="fill:none;stroke:black;" d="M36,-72C35,-64 35,-55 35,-46"/>
+<polygon style="fill:black;stroke:black;" points="38.4778,-45.6021 34,-36 31.5125,-46.2987 38.4778,-45.6021"/>
+</g>
+</g>
+</svg>
<p><code>allpaths(S1 + S2, E)</code>.</p>
</td>
</tr></table>
@@ -818,8 +1104,9 @@
<ul>
<li><code><var>ruletype</var> rule</code>
<li><code><var>ruletype</var></code><br>
- Where <var>ruletype</var> is a
- BUILD rule. The difference between these forms is that including "rule" causes the regular expression match for <var>ruletype</var> to be anchored.
+ Where <var>ruletype</var> is a build rule. The difference between these
+ forms is that including "rule" causes the regular expression match for
+ <var>ruletype</var> to be anchored.
</ul>
<li><b>package group</b> patterns should simply be:
<ul>
@@ -896,20 +1183,21 @@
<p>
This operator often provides a much faster and more robust alternative to the
- <code>intersect</code> operator. For example, in order to see all some_parent
- dependencies of the <code>//foo</code> target, one could evaluate
+ <code>intersect</code> operator. For example, in order to see all
+ <code>bar</code> dependencies of the <code>//foo:foo</code> target, one could
+ evaluate
</p>
-<pre>deps(//foo) intersect //some_parent/...</pre>
+<pre>deps(//foo) intersect //bar/...</pre>
<p>
This statement, however, will require parsing of all BUILD files in the
- <code>some_parent</code> tree, which will be slow and prone to errors in
+ <code>bar</code> tree, which will be slow and prone to errors in
irrelevant BUILD files. An alternative would be:
</p>
-<pre>filter(//some_parent, deps(//foo))</pre>
+<pre>filter(//bar, deps(//foo))</pre>
<p>
which would first calculate the set of <code>//foo</code> dependencies and
then would filter only targets matching the provided pattern—in other
- words, targets with names containing <code>//some_parent</code> as a
+ words, targets with names containing <code>//bar</code> as a
substring.
</p>
@@ -918,9 +1206,10 @@
<var>expr</var>)</code> operator is to filter specific files by their
name or extension. For example,
</p>
-<pre>filter("\.pl$", deps(//foo))</pre>
+<pre>filter("\.cc$", deps(//foo))</pre>
<p>
- will provide a list of all Perl files used to build <code>//foo</code>.
+ will provide a list of all <code>.cc</code> files used to build
+ <code>//foo</code>.
</p>
<h3 id="attr">Rule attribute filtering: attr</h3>
@@ -1008,7 +1297,9 @@
The <code>tests(<var>x</var>)</code> operator returns the set of all test
rules in set <var>x</var>, expanding any <code>test_suite</code> rules into
the set of individual tests that they refer to, and applying filtering by
- <code>tag</code> and <code>size</code>. By default, query evaluation
+ <code>tag</code> and <code>size</code>.
+
+ By default, query evaluation
ignores any non-test targets in all <code>test_suite</code> rules. This can be
changed to errors with the <code>--strict_test_suite</code> option.
</p>
@@ -1033,58 +1324,9 @@
of files that define the packages of each target in
set <var>x</var>; in other words, for each package, its BUILD file,
plus any files it references
- via <code>subinclude</code>.
-<p>
- This operator is typically used when determining what files or
- packages are required to build a specified target, often in conjunction with
- the <a href='#output-package'><code>--output package</code></a>
- option, below). For example,
-</p>
-<pre>bazel query 'buildfiles(deps(//foo))' --output package</pre>
-<p>
- returns the set of all packages on which <code>//foo</code> transitively
- depends.
-</p>
-
-<p>
- (Note: a naive attempt at the above query would omit
- the <code>buildfiles</code> operator and use only <code>deps</code>,
- but this yields an incorrect result: while the result contains the
- majority of needed packages, those packages that contain only
- subincluded files will be missing.)
-</p>
-
-<h3 id="component">All targets in a C++ component: component</h3>
-<pre>expr ::= component(<var>name</var>)</pre>
-<p>
- The <code>component(<var>name</var>)</code> operator returns the set
- of all targets belonging to the named C++ component. Components are
- defined by text files in the
- <code>//dir1/dir2:definitions_cpp/*</code> directory.
- You can use this operator to help resolve dependency problems when
- migrating code into a component.
-</p>
-<p>
- As an example, consider a package <code>foo</code> which we wish to
- move into the "abc" component. This means that all of its
- transitive prerequisites must come from only the "abc" and
- "core" components. To find out if any targets in <code>foo</code>
- violate this rule, use the following query:
-</p>
-<pre>
-bazel query --nohost_deps --noimplicit_deps '
- foo:* intersect (deps(foo:*) - (component(core) + component(abc)))'
-</pre>
-<p>
- To show the subgraph starting from one of the violating targets (say
- <code>//foo:main</code>) whose edges are all outside the component, use:
-</p>
-<pre>
-bazel query --nohost_deps --noimplicit_deps '
- allpaths(//foo:main, deps(foo:*) - (component(core) + component(abc)))' --output=graph
-</pre>
-
+ via <code>load</code>. Note that this also returns the BUILD files of the
+ packages containing these <code>load</code>ed files.
<h2>Output formats</h2>
<p>
@@ -1105,12 +1347,42 @@
is being used.
</p>
+<h3 id='result-order'>On the ordering of results</h3>
+
+<p>
+ Although query expressions always follow the "<a href='#graph-order'>law of
+ conservation of graph order</a>", <i>presenting</i> the results may be done
+ in either a dependency-ordered or unordered manner. This does <b>not</b>
+ influence the targets in the result set or how the query is computed. It only
+ affects how the results are printed to stdout. The
+ <code>--[no]order_results</code> flag can be used to control this behavior.
+</p>
+<p>
+ When <code>--order_results</code> is used (this is the default), then the
+ graph order will be preserved in the output. For example the query
+ <code>deps(x)</code> will print the dependencies of target <code>x</code>
+ before printing <code>x</code> itself.
+</p>
+<p>
+ When <code>--noorder_results</code> is used and <code>--order</code> is one
+ of <code>label</code>, <code>label_kind</code>, <code>location</code>,
+ <code>package</code>, <code>proto</code>, <code>record</code> or
+ <code>xml</code>, the outputs will be printed in arbitrary order. <b>This is
+ generally faster than using <code>--order_results</code></b>. It is not
+ supported though when <code>--order</code> is one of <code>graph</code>,
+ <code>min_rank</code> or <code>max_rank</code>: with these formats, bazel will
+ ignore the <code>--[no]order_results</code> flag and always print ordered
+ results.
+</p>
+
<h3 id="output-label">Print the label of each target</h3>
<pre>--output label</pre>
<p>
With this option, the set of names (or <em>labels</em>) of each target
in the resulting graph is printed, one label per line, in
- topological order. (A topological ordering, is one in which a graph
+ topological order (unless <code>--noorder_results</code> is specified, see
+ <a href='#result-order'>notes on the ordering of results</a>).
+ (A topological ordering is one in which a graph
node appears earlier than all of its successors.) Of course there
are many possible topological orderings of a graph (<em>reverse
postorder</em> is just one); which one is chosen is not specified.
@@ -1145,10 +1417,12 @@
--output maxrank</pre>
<p>
Like <code>label</code>, the <code>minrank</code>
- and <code>maxrank</code> output formats print the labels of each
- target in the resulting graph, but instead of appearing in
- topological order, they appear in rank order, preceded by their
- rank number.
+ and <code>maxrank</code> output formats print the labels of each
+ target in the resulting graph, but instead of appearing in
+ topological order, they appear in rank order, preceded by their
+ rank number. These are unaffected by the result ordering
+ <code>--[no]order_results</code> flag (see <a href='#result-order'>notes on
+ the ordering of results</a>).
</p>
<p>
@@ -1168,7 +1442,8 @@
<p>
All nodes in a cycle are considered of equal rank. (Most graphs are
- acyclic, but cycles do occur, sometimes
+ acyclic, but cycles do occur
+
simply because BUILD files contain erroneous cycles.)
</p>
@@ -1197,17 +1472,64 @@
</p>
<table style='margin: auto'><tr><td>
-<div class='graphviz dot'><!--
-digraph mygraph {
- graph [size="0.4"]
- node [shape=box];
-"//a:a" -> "//a:a.cc"
-"//b:b" -> "//a:a"
-"//b:b" -> "//b:b.cc"
-"//c:c" -> "//b:b"
-"//c:c" -> "//a:a"
-}
---></div>
+<!-- Title: mygraph Pages: 1 -->
+<svg width="146pt" height="260pt"
+ viewBox="0.00 0.00 146.00 260.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 256)">
+<title>mygraph</title>
+<polygon style="fill:white;stroke:white;" points="-4,4 -4,-256 142,-256 142,4 -4,4"/>
+<!-- //a:a -->
+<g id="node1" class="node"><title>//a:a</title>
+<polygon style="fill:none;stroke:black;" points="58,-108 4,-108 4,-72 58,-72 58,-108"/>
+<text text-anchor="middle" x="31" y="-85.4" style="font-family:arial;font-size:14.00;">//a:a</text>
+</g>
+<!-- //a:a.cc -->
+<g id="node3" class="node"><title>//a:a.cc</title>
+<polygon style="fill:none;stroke:black;" points="62,-36 2.84217e-14,-36 0,-1.77636e-14 62,-3.55271e-15 62,-36"/>
+<text text-anchor="middle" x="31" y="-13.4" style="font-family:arial;font-size:14.00;">//a:a.cc</text>
+</g>
+<!-- //a:a->//a:a.cc -->
+<g id="edge2" class="edge"><title>//a:a->//a:a.cc</title>
+<path style="fill:none;stroke:black;" d="M31,-72C31,-64 31,-55 31,-46"/>
+<polygon style="fill:black;stroke:black;" points="34.5001,-46 31,-36 27.5001,-46 34.5001,-46"/>
+</g>
+<!-- //b:b -->
+<g id="node4" class="node"><title>//b:b</title>
+<polygon style="fill:none;stroke:black;" points="113,-180 59,-180 59,-144 113,-144 113,-180"/>
+<text text-anchor="middle" x="86" y="-157.4" style="font-family:arial;font-size:14.00;">//b:b</text>
+</g>
+<!-- //b:b->//a:a -->
+<g id="edge4" class="edge"><title>//b:b->//a:a</title>
+<path style="fill:none;stroke:black;" d="M72,-144C66,-136 58,-125 51,-116"/>
+<polygon style="fill:black;stroke:black;" points="53.8,-113.9 45,-108 48.2,-118.1 53.8,-113.9"/>
+</g>
+<!-- //b:b.cc -->
+<g id="node7" class="node"><title>//b:b.cc</title>
+<polygon style="fill:none;stroke:black;" points="138,-108 76,-108 76,-72 138,-72 138,-108"/>
+<text text-anchor="middle" x="107" y="-85.4" style="font-family:arial;font-size:14.00;">//b:b.cc</text>
+</g>
+<!-- //b:b->//b:b.cc -->
+<g id="edge6" class="edge"><title>//b:b->//b:b.cc</title>
+<path style="fill:none;stroke:black;" d="M91,-144C94,-136 97,-127 99,-118"/>
+<polygon style="fill:black;stroke:black;" points="102.479,-118.584 102,-108 95.7741,-116.573 102.479,-118.584"/>
+</g>
+<!-- //c:c -->
+<g id="node8" class="node"><title>//c:c</title>
+<polygon style="fill:none;stroke:black;" points="85,-252 31,-252 31,-216 85,-216 85,-252"/>
+<text text-anchor="middle" x="58" y="-229.4" style="font-family:arial;font-size:14.00;">//c:c</text>
+</g>
+<!-- //c:c->//a:a -->
+<g id="edge10" class="edge"><title>//c:c->//a:a</title>
+<path style="fill:none;stroke:black;" d="M55,-216C50,-191 41,-147 36,-118"/>
+<polygon style="fill:black;stroke:black;" points="39.3933,-117.119 34,-108 32.5292,-118.492 39.3933,-117.119"/>
+</g>
+<!-- //c:c->//b:b -->
+<g id="edge8" class="edge"><title>//c:c->//b:b</title>
+<path style="fill:none;stroke:black;" d="M65,-216C68,-208 72,-198 75,-190"/>
+<polygon style="fill:black;stroke:black;" points="78.5357,-190.585 79,-180 72.0364,-187.985 78.5357,-190.585"/>
+</g>
+</g>
+</svg>
</td><td>
<pre>
minrank
@@ -1330,26 +1652,27 @@
form. The output starts with an XML header such as this
</p>
<pre>
- <?xml version="1.0" encoding="UTF-8"?>
- <query version="2">
+ <?xml version="1.0" encoding="UTF-8"?>
+ <query version="2">
</pre>
<!-- The docs should continue to document version 2 into perpetuity,
even if we add new formats, to handle clients synced to old CLs. -->
<p>
and then continues with an XML element for each target
- in the result graph, in topological order,
+ in the result graph, in topological order (unless
+ <a href='#result-order'>unordered results</a> are requested),
and then finishes with a terminating
</p>
<pre>
-</query>
+</query>
</pre>
<p>
Simple entries are emitted for targets of <code>file</code>
kind:
</p>
<pre>
- <source-file name='//foo:bar_main.cc' .../>
- <generated-file name='//foo:libbar.so' .../>
+ <source-file name='//foo:foo_main.cc' .../>
+ <generated-file name='//foo:libfoo.so' .../>
</pre>
<p>
But for rules, the XML is structured and contains definitions of all
@@ -1372,7 +1695,7 @@
<rule class='cc_binary rule' name='//foo:foo' ...>
<list name='srcs'>
<label value='//foo:foo_main.cc'/>
- <label value='//foo:foo.cc'/>
+ <label value='//foo:bar.cc'/>
...
</list>
<list name='deps'>
@@ -1392,7 +1715,7 @@
<rule-input name="//common:common" />
<rule-input name="//collections:collections" />
<rule-input name="//foo:foo_main.cc" />
- <rule-input name="//foo:foo.cc" />
+ <rule-input name="//foo:bar.cc" />
...
</rule>
</pre>
diff --git a/docs/historical/build-ref.html b/docs/build-ref.html
similarity index 75%
rename from docs/historical/build-ref.html
rename to docs/build-ref.html
index 5f58b87..05641e5 100644
--- a/docs/historical/build-ref.html
+++ b/docs/build-ref.html
@@ -3,6 +3,7 @@
<html>
<head>
<meta charset="utf-8" />
+
<title>Bazel Concepts and Terminology</title>
<style type="text/css" id="internalStyle">
@@ -127,22 +128,21 @@
#maintainer { text-align: right; }
</style>
</head>
+<body>
-<body onload="GV_renderAllGraphs(); prettyPrint(); processSourcerLinks();">
-<h1>Bazel Concepts and Terminology</h1>
-
+<h1>Bazel: Concepts and Terminology</h1>
<p>
This document provides an overview of concepts and terminology used
in Bazel.
</p>
-
<h2>Related Documentation</h2>
<ul class="toc">
<li><a href="write_build_file.html">Getting Started with BUILD files</a></li>
- <li><a href="build-ref.html">Bazel Concept Reference</a></li>
+ <li><a href="build-ref.html">BUILD Concept Reference</a></li>
<li><a href="build-encyclopedia.html">Build Encyclopedia</a></li>
- <li><a href="bazel-user-manual.html">User Manual</a></li>
+ <li><a href="bazel-user-manual.html">Bazel User Manual</a></li>
<li><a href="bazel-query-v2.html">Bazel Query Reference</a></li>
+
</ul>
<h2>Table of Contents</h2>
@@ -172,28 +172,20 @@
</ul>
</li>
</ul>
-
-<div class="nav-2-levels" id="nav"></div>
-
<h2 id='intro'>Introduction</h2>
<p>Bazel can build and test software from source
code stored in any source tree that is organized as described
in this document. This source tree descends from a single top-level
directory and contains a nested hierarchy of packages, each of which contain
- source files and metadata that specifies what software targets -- for
- example, compiled executables or libraries -- can be built from the source.
-
-<h2 id="packages_targets"">Packages and Targets</h2>
-
-<h3 id="packages">Packages</h3>
-
+ source files and metadata that specifies what software targets, for
+ example, compiled executables or libraries, can be built from the source.
+</p>
<p>
The primary unit of code organization in the source tree is
the <i>package</i>. A package is collection of related files and a
specification of the dependencies among them.
</p>
-
<p>
A package is defined as a directory containing a file
named <code>BUILD</code>, residing beneath the top-level directory in the
@@ -201,10 +193,6 @@
subdirectories beneath it, except those which themselves contain a BUILD
file.
</p>
-
-<p>
- For example, in the following directory tree:
-</p>
<pre>
src/my/app/BUILD
src/my/app/app.cc
@@ -218,8 +206,7 @@
<code>my/app/data</code> is not a package, but a directory belonging to package
<code>my/app</code>.
</p>
-
-<h3 id="targets">Targets</h3>
+<h3>Targets</h3>
<p>
A package is a container. The elements of a package are called
@@ -230,15 +217,107 @@
</p>
<div style='margin:auto; text-align: center'>
-<img src="images/package_targets.png" />
+<!-- Title: G1 Pages: 1 -->
+<svg width="550pt" height="188pt"
+ viewBox="0.00 0.00 550.00 188.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 184)">
+<title>G1</title>
+<polygon style="fill:white;stroke:white;" points="-4,4 -4,-184 546,-184 546,4 -4,4"/>
+<!-- Target -->
+<g id="node1" class="node"><title>Target</title>
+<ellipse style="fill:none;stroke:black;" cx="349" cy="-162" rx="36.8951" ry="18"/>
+<text text-anchor="middle" x="349" y="-157.4" style="font-family:arial;font-size:14.00;">Target</text>
+</g>
+<!-- Rule -->
+<g id="node3" class="node"><title>Rule</title>
+<ellipse style="fill:none;stroke:black;" cx="216" cy="-90" rx="30.1869" ry="18"/>
+<text text-anchor="middle" x="216" y="-85.4" style="font-family:arial;font-size:14.00;">Rule</text>
+</g>
+<!-- Target->Rule -->
+<g id="edge2" class="edge"><title>Target->Rule</title>
+<path style="fill:none;stroke:black;" d="M324,-148C302,-137 271,-120 248,-107"/>
+<polygon style="fill:black;stroke:black;" points="249.441,-103.797 239,-102 246.042,-109.916 249.441,-103.797"/>
+</g>
+<!-- File -->
+<g id="node11" class="node"><title>File</title>
+<ellipse style="fill:none;stroke:black;" cx="349" cy="-90" rx="27" ry="18"/>
+<text text-anchor="middle" x="349" y="-85.4" style="font-family:arial;font-size:14.00;">File</text>
+</g>
+<!-- Target->File -->
+<g id="edge10" class="edge"><title>Target->File</title>
+<path style="fill:none;stroke:black;" d="M349,-144C349,-136 349,-127 349,-118"/>
+<polygon style="fill:black;stroke:black;" points="352.5,-118 349,-108 345.5,-118 352.5,-118"/>
+</g>
+<!-- Package group -->
+<g id="node17" class="node"><title>Package group</title>
+<ellipse style="fill:none;stroke:black;" cx="468" cy="-90" rx="73.7902" ry="18"/>
+<text text-anchor="middle" x="468" y="-85.4" style="font-family:arial;font-size:14.00;">Package group</text>
+</g>
+<!-- Target->Package group -->
+<g id="edge16" class="edge"><title>Target->Package group</title>
+<path style="fill:none;stroke:black;" d="M372,-148C389,-138 412,-124 431,-112"/>
+<polygon style="fill:black;stroke:black;" points="432.958,-114.916 440,-107 429.559,-108.797 432.958,-114.916"/>
+</g>
+<!-- cc_library -->
+<g id="node5" class="node"><title>cc_library</title>
+<ellipse style="fill:none;stroke:black;" cx="51" cy="-18" rx="50.9823" ry="18"/>
+<text text-anchor="middle" x="51" y="-13.4" style="font-family:arial;font-size:14.00;">cc_library</text>
+</g>
+<!-- Rule->cc_library -->
+<g id="edge4" class="edge"><title>Rule->cc_library</title>
+<path style="fill:none;stroke:black;" d="M192,-79C166,-68 124,-50 92,-36"/>
+<polygon style="fill:black;stroke:black;" points="93.5596,-32.8631 83,-32 90.7166,-39.2598 93.5596,-32.8631"/>
+</g>
+<!-- java_test -->
+<g id="node7" class="node"><title>java_test</title>
+<ellipse style="fill:none;stroke:black;" cx="169" cy="-18" rx="48.9699" ry="18"/>
+<text text-anchor="middle" x="169" y="-13.4" style="font-family:arial;font-size:14.00;">java_test</text>
+</g>
+<!-- Rule->java_test -->
+<g id="edge6" class="edge"><title>Rule->java_test</title>
+<path style="fill:none;stroke:black;" d="M205,-73C200,-65 193,-54 186,-44"/>
+<polygon style="fill:black;stroke:black;" points="188.8,-41.9 180,-36 183.2,-46.1 188.8,-41.9"/>
+</g>
+<!-- ... -->
+<g id="node9" class="node"><title>...</title>
+<ellipse style="fill:none;stroke:black;" cx="263" cy="-18" rx="27" ry="18"/>
+<text text-anchor="middle" x="263" y="-13.4" style="font-family:arial;font-size:14.00;">...</text>
+</g>
+<!-- Rule->... -->
+<g id="edge8" class="edge"><title>Rule->...</title>
+<path style="fill:none;stroke:black;" d="M227,-73C233,-65 240,-53 246,-44"/>
+<polygon style="fill:black;stroke:black;" points="249.365,-45.262 252,-35 243.541,-41.3791 249.365,-45.262"/>
+</g>
+<!-- Source -->
+<g id="node13" class="node"><title>Source</title>
+<ellipse style="fill:none;stroke:black;" cx="349" cy="-18" rx="40.92" ry="18"/>
+<text text-anchor="middle" x="349" y="-13.4" style="font-family:arial;font-size:14.00;">Source</text>
+</g>
+<!-- File->Source -->
+<g id="edge12" class="edge"><title>File->Source</title>
+<path style="fill:none;stroke:black;" d="M349,-72C349,-64 349,-55 349,-46"/>
+<polygon style="fill:black;stroke:black;" points="352.5,-46 349,-36 345.5,-46 352.5,-46"/>
+</g>
+<!-- Generated -->
+<g id="node15" class="node"><title>Generated</title>
+<ellipse style="fill:none;stroke:black;" cx="463" cy="-18" rx="55.0073" ry="18"/>
+<text text-anchor="middle" x="463" y="-13.4" style="font-family:arial;font-size:14.00;">Generated</text>
+</g>
+<!-- File->Generated -->
+<g id="edge14" class="edge"><title>File->Generated</title>
+<path style="fill:none;stroke:black;" d="M369,-77C385,-67 409,-52 429,-39"/>
+<polygon style="fill:black;stroke:black;" points="430.958,-41.916 438,-34 427.559,-35.7969 430.958,-41.916"/>
+</g>
+</g>
+</svg>
<p><i>Hierarchy of targets.</i></p>
</div>
<p>
Files are further divided into two kinds.
<i>Source files</i> are usually written by the efforts of people,
- and checked in to
- the repository. <i>Generated files</i>, sometimes called derived files,
+ and checked in to the repository.
+ <i>Generated files</i>, sometimes called derived files,
are not checked in, but are generated by the build tool from source
files according to specific rules.
</p>
@@ -304,13 +383,18 @@
</p>
<pre>
- //my/app/main:app
+ //my/app/main:app_binary
</pre>
<p>
- Each label has two parts, a package name (my/app/main) and a
- target name (app). Every label uniquely identifies a target.
- Labels sometimes appear in other forms; when
+
+ (Don't let the similarity with Piper filespecs confuse you; both
+ start with a leading <code>//</code> but they are quite different
+ things.)
+
+ Each label has two parts, a package name (<code>my/app/main</code>)
+ and a target name (<code>app_binary</code>). Every label uniquely
+ identifies a target. Labels sometimes appear in other forms; when
the colon is omitted, the target name is assumed to be the same as
the last component of the package name, so these two labels are
equivalent:
@@ -335,8 +419,8 @@
<p>
Within a BUILD file, the package-name part of label may be omitted,
and optionally the colon too. So within the BUILD file for package
- my/app (i.e. <code>//my/app:BUILD</code>), the
- following "relative" labels are all equivalent:
+ <code>my/app</code> (i.e. <code>//my/app:BUILD</code>),
+ the following "relative" labels are all equivalent:
</p>
<pre>
@@ -420,8 +504,9 @@
of a file is its pathname relative to the directory containing
the BUILD file.
Target names must be composed entirely of
- characters drawn from the set a-z, A-Z, 0-9, and the punctuation
- symbols <code>_/.+-=,@~</code>.
+ characters drawn from the set <code>a</code>–<code>z</code>,
+ <code>A</code>–<code>Z</code>, <code>0</code>–<code>9</code>,
+ and the punctuation symbols <code>_/.+-=,@~</code>.
Do not use <code>..</code> to refer to files in other packages; use
<code>//<var>packagename</var>:<var>filename</var></code> instead.
Filenames must be relative pathnames in normal form, which means
@@ -452,33 +537,23 @@
<h4>Package names, <code>//<b>package-name</b>:...</code></h4>
<p>
The name of a package is the name of the directory containing its
+
BUILD file, relative to the top-level directory of the source tree.
For example: <code>my/app</code>.
- Package names must start with a lower-case ASCII letter (a-z),
+ Package names must start with a lower-case ASCII letter
+ (<code>a</code>–<code>z</code>),
and must be composed entirely of characters drawn from the set
- a-z, 0-9, '_', and '/'.
+ <code>a</code>–<code>z</code>, <code>0</code>–<code>9</code>,
+ '<code>_</code>', and '<code>/</code>'.
</p>
-<p>
- For a language with a directory structure that is significant
- to its module system, it is important to choose directory names
- that are valid identifiers in the language.
-</p>
-
-<p>
- The limited exceptions above were permitted because those trees
- contain other programming languages with incompatible naming
- requirements, or because the owners of that tree
- committed to use only a particular programming language within that
- tree.
-</p>
<p>
Package names may not contain the substring <code>//</code>, nor
end with a slash.
</p>
-<h3 id="rules">Rules</h3>
+<h3>Rules</h3>
<p>
A rule specifies the relationship between inputs and output, and the
@@ -493,9 +568,8 @@
Every rule has a name, specified by the <code>name</code> attribute,
of type string. The name must be a syntactically valid target name,
as specified <a href='#name'>above</a>. In some cases, the name is
- somewhat
- arbitrary, and more interesting are the names of the files generated
- by the rule; this is true of genrule rules in particular. In other
+ somewhat arbitrary, and more interesting are the names of the files
+ generated by the rule; this is true of genrules. In other
cases, the name is significant: for <code>*_binary</code>
and <code>*_test</code> rules, for example, the rule name determines
the name of the executable produced by the build.
@@ -546,7 +620,89 @@
</p>
<div style="margin:auto; text-align:center">
-<img src="images/source_rules_generated_files.png" />
+<!-- Title: G1 Pages: 1 -->
+<svg width="154pt" height="244pt"
+ viewBox="0.00 0.00 154.00 244.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 240)">
+<title>G1</title>
+<polygon style="fill:white;stroke:white;" points="-4,4 -4,-240 150,-240 150,4 -4,4"/>
+<!-- r1 -->
+<g id="node1" class="node"><title>r1</title>
+<polygon style="fill:none;stroke:black;" points="87,-172 33,-172 33,-136 87,-136 87,-172"/>
+<text text-anchor="middle" x="60" y="-151" style="font-family:arial;font-size:10.00;fill:#006000;">rule</text>
+</g>
+<!-- s1 -->
+<g id="node3" class="node"><title>s1</title>
+<ellipse style="fill:none;stroke:black;" cx="14" cy="-222" rx="14" ry="14"/>
+<text text-anchor="middle" x="14" y="-219" style="font-family:arial;font-size:10.00;fill:#006000;">in</text>
+</g>
+<!-- r1->s1 -->
+<g id="edge2" class="edge"><title>r1->s1</title>
+<path style="fill:none;stroke:black;" d="M48,-172C42,-181 34,-192 28,-202"/>
+<polygon style="fill:black;stroke:black;" points="25.2,-199.9 22,-210 30.8,-204.1 25.2,-199.9"/>
+</g>
+<!-- s2 -->
+<g id="node4" class="node"><title>s2</title>
+<ellipse style="fill:none;stroke:black;" cx="60" cy="-222" rx="14" ry="14"/>
+<text text-anchor="middle" x="60" y="-219" style="font-family:arial;font-size:10.00;fill:#006000;">in</text>
+</g>
+<!-- r1->s2 -->
+<g id="edge4" class="edge"><title>r1->s2</title>
+<path style="fill:none;stroke:black;" d="M60,-172C60,-180 60,-189 60,-198"/>
+<polygon style="fill:black;stroke:black;" points="56.5001,-198 60,-208 63.5001,-198 56.5001,-198"/>
+</g>
+<!-- s3 -->
+<g id="node5" class="node"><title>s3</title>
+<ellipse style="fill:none;stroke:black;" cx="106" cy="-222" rx="14" ry="14"/>
+<text text-anchor="middle" x="106" y="-219" style="font-family:arial;font-size:10.00;fill:#006000;">in</text>
+</g>
+<!-- r1->s3 -->
+<g id="edge6" class="edge"><title>r1->s3</title>
+<path style="fill:none;stroke:black;" d="M72,-172C78,-181 86,-192 92,-202"/>
+<polygon style="fill:black;stroke:black;" points="89.2,-204.1 98,-210 94.8,-199.9 89.2,-204.1"/>
+</g>
+<!-- r2 -->
+<g id="node2" class="node"><title>r2</title>
+<polygon style="fill:none;stroke:black;" points="146,-100 92,-100 92,-64 146,-64 146,-100"/>
+<text text-anchor="middle" x="119" y="-79" style="font-family:arial;font-size:10.00;fill:#006000;">rule</text>
+</g>
+<!-- r2->r1 -->
+<g id="edge10" class="edge"><title>r2->r1</title>
+<path style="fill:none;stroke:black;" d="M104,-100C97,-109 89,-119 81,-128"/>
+<polygon style="fill:black;stroke:black;" points="78.2,-125.9 75,-136 83.8,-130.1 78.2,-125.9"/>
+</g>
+<!-- s4 -->
+<g id="node6" class="node"><title>s4</title>
+<ellipse style="fill:none;stroke:black;" cx="119" cy="-154" rx="14" ry="14"/>
+<text text-anchor="middle" x="119" y="-151" style="font-family:arial;font-size:10.00;fill:#006000;">in</text>
+</g>
+<!-- r2->s4 -->
+<g id="edge8" class="edge"><title>r2->s4</title>
+<path style="fill:none;stroke:black;" d="M119,-100C119,-109 119,-120 119,-130"/>
+<polygon style="fill:black;stroke:black;" points="115.5,-130 119,-140 122.5,-130 115.5,-130"/>
+</g>
+<!-- o1 -->
+<g id="node7" class="node"><title>o1</title>
+<ellipse style="fill:none;stroke:black;" cx="60" cy="-82" rx="14" ry="14"/>
+<text text-anchor="middle" x="60" y="-79" style="font-family:arial;font-size:10.00;fill:#006000;">out</text>
+</g>
+<!-- o1->r1 -->
+<g id="edge12" class="edge"><title>o1->r1</title>
+<path style="fill:none;stroke:black;" d="M60,-96C60,-104 60,-116 60,-126"/>
+<polygon style="fill:black;stroke:black;" points="56.5001,-126 60,-136 63.5001,-126 56.5001,-126"/>
+</g>
+<!-- o2 -->
+<g id="node8" class="node"><title>o2</title>
+<ellipse style="fill:none;stroke:black;" cx="119" cy="-14" rx="14" ry="14"/>
+<text text-anchor="middle" x="119" y="-11" style="font-family:arial;font-size:10.00;fill:#006000;">out</text>
+</g>
+<!-- o2->r2 -->
+<g id="edge14" class="edge"><title>o2->r2</title>
+<path style="fill:none;stroke:black;" d="M119,-28C119,-35 119,-45 119,-54"/>
+<polygon style="fill:black;stroke:black;" points="115.5,-54 119,-64 122.5,-54 115.5,-54"/>
+</g>
+</g>
+</svg>
<p><i>Source files, rules, and generated files.</i></p>
</div>
@@ -728,7 +884,7 @@
list.extend(sequence)
</pre>
-<h3 id="declaring_build_rules">Declaring build rules</h3>
+<h3>Declaring build rules</h3>
<p>
The build language is an imperative language, so in general, order
@@ -765,8 +921,8 @@
and <code>cc_test</code> are the build rules for C++ binaries,
libraries, and tests, respectively. Other languages use the same
naming scheme, with a different prefix, e.g. <code>java_*</code> for
- Java. These functions are all documented in
- the <a href="build-encyclopedia.html">Build Encyclopedia</a>.
+ Java. These functions are all documented in the
+ <a href="build-encyclopedia.html">Build Encyclopedia</a>.
</p>
<ul>
@@ -779,6 +935,7 @@
(e.g.) <code>$(BINDIR)/my/program</code>. </p>
<p>Such rules also create a runfiles directory
+
containing all the files mentioned in a <code>data</code>
attribute belonging to the rule, or any rule in its transitive
closure of dependencies; this set of files is gathered together in
@@ -787,19 +944,23 @@
<li><p>A <a href='build-encyclopedia.html#test'><code>*_test</code></a>
rule is a specialization of a *_binary rule, used for automated
- testing. Tests are simply programs that return zero on success.</p>
+ testing. Tests are simply programs that return zero on success.
+
+ </p>
<p>
Like binaries, tests also have runfiles trees, and the files
beneath it are the only files that a test may legitimately open
at runtime. For example, a program <code>cc_test(name='x',
data=['//foo:bar])</code> may open and
- read <code>$TEST_SRCDIR/path/foo/bar</code> during execution.
+
+ read <code>$TEST_SRCDIR/workspace/foo/bar</code> during execution.
(Each programming language has its own utility function for
accessing the value of <code>$TEST_SRCDIR</code>, but they are all
equivalent to using the environment variable directly.)
Failure to observe the rule will cause the test to fail when it is
executed on a remote testing host.
+
</p>
</li>
@@ -856,9 +1017,12 @@
be a subgraph of the graph of declared dependencies <i>D</i>. That
is, every pair of directly-connected nodes <code>x --> y</code>
in <i>A</i> must also be directly connected in <i>D</i>. We say
- <i>D</i> is an <em>overapproximation</em> of <i>A</i>. It is important
- that it not be too much of an overapproximation, though, since
- redundant declared dependencies can make builds slower and
+ <i>D</i> is an <em>overapproximation</em> of <i>A</i>.
+</p>
+
+<p>
+ It is important that it not be too much of an overapproximation,
+ though, since redundant declared dependencies can make builds slower and
binaries larger.
</p>
@@ -876,6 +1040,7 @@
</p>
<p>
+
You need not (and should not) attempt to list everything indirectly imported,
even if it is "needed" by A at execution time.
</p>
@@ -937,9 +1102,9 @@
</pre>
</div>
<pre style="clear: both;">
-Declared dependency graph: a --> b --> c
+Declared dependency graph: a --> b --> c
-Actual dependency graph: a --> b --> c
+Actual dependency graph: a --> b --> c
</pre>
The declared dependencies overapproximate the actual dependencies.
All is well.
@@ -962,9 +1127,9 @@
</div>
<pre style="clear: both;">
-Declared dependency graph: a --> b --> c
+Declared dependency graph: a --> b --> c
-Actual dependency graph: a --> b -->_c
+Actual dependency graph: a --> b -->_c
\_________/|
</pre>
The declared dependencies no longer overapproximate the actual
@@ -998,9 +1163,9 @@
</pre>
</div>
<pre style="clear: both;">
-Declared dependency graph: a --> b c
+Declared dependency graph: a --> b c
-Actual dependency graph: a --> b _c
+Actual dependency graph: a --> b _c
\_________/|
</pre>
<p>
@@ -1013,7 +1178,7 @@
2 was properly declared in the BUILD file.
</div>
-<h3 id="types_of_dependencies">Types of dependencies</h3>
+<h3>Types of dependencies</h3>
<p>
Most build rules have three attributes for specifying different kinds
@@ -1067,20 +1232,21 @@
name = "regtest",
srcs = ["regtest.sh"],
data = [
- "//data/find:file1.txt",
- "//data/find:file2.txt",
+ "//data:file1.txt",
+ "//data:file2.txt",
...
],
)
</pre>
<p>These files are available using the relative path
-<code>"./path/to/data/file"</code>. In tests, it is also possible to refer to
-them using
-<code>file::JoinPath(FLAGS_test_srcdir, "/path/to/data/file")</code> or
-<code>${TEST_SRCDIR}/path/to/data/file</code>. (The exact syntax
+<code>"path/to/data/file"</code>. In tests, it is also possible to refer to
+them by joining the paths of the test's source directory and the workspace-relative
+path, e.g. <code>${TEST_SRCDIR}/path/to/data/file</code>. (The exact syntax
depends on your programming language, of course.)</p>
+<p>
+
<h3 id="label_directory">Using Labels to Reference Directories</h3>
<p>As you look over our <code>BUILD</code> files, you might notice
@@ -1139,7 +1305,7 @@
<p>If you must use directory labels, keep in mind that you can't refer to the parent
package with a relative "<code>../</code>" path; instead, use an absolute path like
- "<code>//data/regression:insert_docs_unittest/.</code>".
+ "<code>//data/regression:unittest/.</code>".
</p>
<p>Note that directory labels are only valid for data dependencies. If you try to use
diff --git a/docs/concepts.md b/docs/concepts.md
new file mode 100644
index 0000000..72b4d59
--- /dev/null
+++ b/docs/concepts.md
@@ -0,0 +1,104 @@
+Concepts
+========
+
+Loading a Skylark module
+------------------------
+
+Use the `load` statement to import a symbol from a Skylark module.
+
+```python
+load("/build_tools/rules/maprule", "maprule")
+```
+
+This code will load the file `build_tools/rules/maprule.bzl` and add the
+`maprule` symbol to the environment. This can be used to load new rules,
+functions or constants (e.g. a string, a list, etc.). Multiple symbols can be
+imported by using additional arguments to the call to `load`. Arguments must
+be string literals (no variable) and `load` statements must appear at
+top-level, i.e. they cannot be in a function body.
+
+Visibility doesn't affect loading. You don't need to use `exports_files`
+to make a Skylark file visible.
+
+Symbols starting with `_` are private and cannot be loaded from other files.
+
+Macros and rules
+----------------
+
+A [macro](macros.md) in Skylark is a function that instantiates rules. The
+function is evaluated as soon as the BUILD file is read. Bazel has little
+information about macros: If your macro generates a genrule, Bazel will behave
+as if you wrote the genrule. As a result, `bazel query` will only list the
+generated genrule.
+
+A [rule](rules.md) in Skylark is more powerful than a macro, as it can access
+Bazel internals and have full control over what is going on. It may for example
+pass information to other rules. A rule defined in Skylark will behave in a
+similar way as a native rule.
+
+If a macro becomes complex, it is often a good idea to make it a rule.
+
+Evaluation model
+----------------
+
+A build consists of three phases.
+
+* **Loading phase**. First, we load and evaluate all Skylark modules and all BUILD
+ files that are needed for the build. The execution of the BUILD files simply
+ instantiates rules. This is where macros are evaluated.
+
+* **Analysis phase**. The code of the rules is executed (their `implementation`
+ function), and actions are instantiated. An action describes how to generate
+ a set of outputs from a set of inputs, e.g. "run gcc on hello.c and get
+ hello.o". It is important to note that we have to list explicitly which
+ files will be generated before executing the actual commands.
+
+* **Execution phase**. Actions are executed, when at least one of their outputs is
+ required. If a file is missing or if a command fails to generate one output,
+ the build fails. Tests are run during this phase, as they are actions.
+
+Language
+--------
+
+Skylark is a superset of the core build language and its syntax is a subset of
+Python. The following constructs have been added to the core build language:
+`if` statements, `for` loops, and function definitions.
+It is designed to be simple, thread-safe and integrated with the
+BUILD language. It is not a general-purpose language and most Python
+features are not included.
+
+
+Some differences with Python should be noted:
+
+* All data structures are immutable.
+
+* All global values are constant (they cannot be reassigned).
+
+* Heterogeneous lists and dictionaries are forbidden.
+
+* The type of a variable may not change, e.g. this is forbidden:
+ `a = 2; a = "str"`
+
+* `x += y` is syntactic sugar for `x = x + y`. Even if `x` and `y` are lists,
+ dicts or sets, the original value is not mutated, so references to `x`
+ that were assigned before the operation will see the old value.
+
+* The + operator is defined for dictionaries, returning an immutable
+ concatenated dictionary created from the entries of the original
+ dictionaries. In case of duplicate keys, we use values from the second
+ operand.
+
+* Dictionary assignment has slightly different semantics: `d["x"] = y` is
+ syntactic sugar for `d = d + {"x": y}` or `d += {"x": y}`.
+
+* Recursion is not allowed.
+
+The following Python features are not supported:
+
+* `class` (see `struct` function)
+* `import` (see `load` statement)
+* `while`, `yield`, `break`, `continue`
+* `lambda`
+* `try`, `raise`, `except`, `finally` (see `fail` for fatal errors).
+* `*args`, `**kwargs`
+* most builtin functions, most methods
diff --git a/docs/cookbook.md b/docs/cookbook.md
new file mode 100644
index 0000000..7d11190
--- /dev/null
+++ b/docs/cookbook.md
@@ -0,0 +1,560 @@
+Skylark cookbook
+================
+
+[TOC]
+
+## <a name="empty"></a>Empty
+
+Minimalist example of a rule that does nothing. If you build it, the target will
+succeed (with no generated file).
+
+`empty.bzl`:
+
+```python
+def impl(ctx):
+ # You may use print for debugging.
+ print("This rule does nothing")
+
+empty = rule(impl)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/empty", "empty")
+
+empty(name = "nothing")
+```
+
+## <a name="macro_native"></a>Macro creating a native rule
+
+An example of a macro creating a native rule. Native rules are accessed using
+the `native` module.
+
+`extension.bzl`:
+
+```python
+def macro(name, visibility=None):
+ # Creating a native genrule.
+ native.genrule(
+ name = name,
+ outs = [name + '.txt'],
+ cmd = 'echo hello > $@',
+ visibility = visibility,
+ )
+```
+
+`BUILD`:
+
+```build
+load("/pkg/extension", "macro")
+
+macro(name = "myrule")
+```
+
+## <a name="macro_skylark"></a>Macro creating a Skylark rule
+
+An example of a macro creating a Skylark rule.
+
+`empty.bzl`:
+
+```python
+def impl(ctx):
+ print("This rule does nothing")
+
+empty = rule(impl)
+```
+
+`extension.bzl`:
+
+```python
+# Loading the Skylark rule. The rule doesn't have to be in a separate file.
+load("/pkg/empty", "empty")
+
+def macro(name, visibility=None):
+ # Creating the Skylark rule.
+ empty(name = name, visibility=visibility)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/extension", "macro")
+
+macro(name = "myrule")
+```
+
+## <a name="shell"></a>Simple shell command
+
+Example of a rule that runs a shell command on an input file specified by
+the user. The output has the same name as the input, with a `.txt` suffix.
+
+`size.bzl`:
+
+```python
+def impl(ctx):
+ output = ctx.outputs.out
+ input = ctx.file.file
+ ctx.action(
+ inputs=[input],
+ outputs=[output],
+ command="stat -L -c%%s %s > %s" % (input.path, output.path))
+
+size = rule(
+ implementation=impl,
+ attrs={"file": attr.label(mandatory=True, allow_files=True, single_file=True)},
+ outputs={"out": "%{name}.size"},
+)
+```
+
+`foo.txt`:
+
+```
+Hello
+```
+
+`BUILD`:
+
+```build
+load("/pkg/size", "size")
+
+size(
+ name = "foo_size",
+ file = "foo.txt",
+)
+```
+
+## <a name="file"></a>Write string to a file
+
+Example of a rule that writes a string to a file.
+
+`file.bzl`:
+
+```python
+def impl(ctx):
+ output = ctx.outputs.out
+ ctx.file_action(output=output, content=ctx.attr.content)
+
+file = rule(
+ implementation=impl,
+ attrs={"content": attr.string()},
+ outputs={"out": "%{name}.txt"},
+)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/file", "file")
+
+file(
+ name = "hello",
+ content = "Hello world",
+)
+```
+
+
+## <a name="execute"></a>Execute an input binary
+
+This rule has a mandatory `binary` attribute. It is a label that can refer
+only to executable rules or files.
+
+`execute.bzl`:
+
+```python
+def impl(ctx):
+ # ctx.new_file is used for temporary files.
+ # If it should be visible for user, declare it in rule.outputs instead.
+ f = ctx.new_file(ctx.configuration.bin_dir, "hello")
+ # As with outputs, each time you declare a file,
+ # you need an action to generate it.
+ ctx.file_action(output=f, content=ctx.attr.input_content)
+
+ ctx.action(
+ inputs=[f],
+ outputs=[ctx.outputs.out],
+ executable=ctx.executable.binary,
+ arguments=[
+ f.path,
+ ctx.outputs.out.path, # Access the output file using
+ # ctx.outputs.<attribute name>
+ ]
+ )
+
+execute = rule(
+ implementation=impl,
+ attrs={
+ "binary": attr.label(cfg=HOST_CFG, mandatory=True, allow_files=True,
+ executable=True),
+ "input_content": attr.string(),
+ "out": attr.output(mandatory=True),
+ },
+)
+```
+
+`a.sh`:
+
+```shell
+#! /bin/bash
+
+tr 'a-z' 'A-Z' < $1 > $2
+```
+
+`BUILD`:
+
+```build
+load("/pkg/execute", "execute")
+
+execute(
+ name = "e",
+ input_content = "some text",
+ binary = "a.sh",
+ out = "foo",
+)
+```
+
+## <a name="runfiles"></a>Define simple runfiles
+
+`execute.bzl`:
+
+```python
+def impl(ctx):
+ executable = ctx.outputs.executable
+ # Create the output executable file with command as its content.
+ ctx.file_action(
+ output=executable,
+ content=ctx.attr.command,
+ executable=True)
+
+ return struct(
+ # Create runfiles from the files specified in the data attribute.
+ # The shell executable - the output of this rule - can use them at runtime.
+ # It is also possible to define data_runfiles and default_runfiles.
+ # However if runfiles is specified it's not possible to define the above
+ # ones since runfiles sets them both.
+ # Remember, that the struct returned by the implementation function needs
+ # to have a field named "runfiles" in order to create the actual runfiles
+ # symlink tree.
+ runfiles=ctx.runfiles(files=ctx.files.data)
+ )
+
+execute = rule(
+ implementation=impl,
+ executable=True,
+ attrs={
+ "command": attr.string(),
+ "data": attr.label_list(cfg=DATA_CFG, allow_files=True),
+ },
+)
+```
+
+`data.txt`:
+
+```
+Hello World!
+```
+
+`BUILD`:
+
+```build
+load("/pkg/execute", "execute")
+
+execute(
+ name = "e",
+ # The path to data.txt has to include the package directories as well. I.e.
+ # if the BUILD file is under foo/BUILD and the data file is foo/data.txt
+ # then it needs to be referred as foo/data.txt in the command.
+ command = "cat data.txt",
+ data = [':data.txt']
+)
+```
+
+
+## <a name="mandatory-providers"></a>Mandatory providers
+
+In this example, rules have a `number` attribute. Each rule adds its
+number with the numbers of its transitive dependencies, and write the
+result in a file. This shows how to transfer information from a dependency
+to its dependents.
+
+`sum.bzl`:
+
+```python
+def impl(ctx):
+ result = ctx.attr.number
+ for i in ctx.targets.deps:
+ result += i.number
+ ctx.file_action(output=ctx.outputs.out, content=str(result))
+
+ # Fields in the struct will be visible by other rules.
+ return struct(number=result)
+
+sum = rule(
+ implementation=impl,
+ attrs={
+ "number": attr.int(default=1),
+ # All deps must provide all listed providers.
+ "deps": attr.label_list(providers=["number"]),
+ },
+ outputs = {"out": "%{name}.sum"}
+)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/sum", "sum")
+
+sum(
+ name = "n",
+ deps = ["n2", "n5"],
+)
+
+sum(
+ name = "n2",
+ number = 2,
+)
+
+sum(
+ name = "n5",
+ number = 5,
+)
+```
+
+## <a name="optional-providers"></a>Optional providers
+
+This is a similar example, but dependencies may not provide a number.
+
+`sum.bzl`:
+
+```python
+def impl(ctx):
+ result = ctx.attr.number
+ for i in ctx.targets.deps:
+ if hasattr(i, "number"):
+ result += i.number
+ ctx.file_action(output=ctx.outputs.out, content=str(result))
+
+ # Fields in the struct will be visible by other rules.
+ return struct(number=result)
+
+sum = rule(
+ implementation=impl,
+ attrs={
+ "number": attr.int(default=1),
+ "deps": attr.label_list(),
+ },
+ outputs = {"out": "%{name}.sum"}
+)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/sum", "sum")
+
+sum(
+ name = "n",
+ deps = ["n2", "n5"],
+)
+
+sum(
+ name = "n2",
+ number = 2,
+)
+
+sum(
+ name = "n5",
+ number = 5,
+)
+```
+
+## <a name="outputs-executable"></a>Default executable output
+
+This example shows how to create a default executable output.
+
+`extension.bzl`:
+
+```python
+def impl(ctx):
+ ctx.file_action(
+ # Access the executable output file using ctx.outputs.executable.
+ output = ctx.outputs.executable,
+ content = "#!/bin/bash\necho Hello!",
+ executable = True
+ )
+ # The executable output is added automatically to this target.
+
+executable_rule = rule(
+ implementation = impl,
+ executable = True
+)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/extension", "executable_rule")
+
+executable_rule(name = "my_rule")
+```
+
+## <a name="outputs-default"></a>Default outputs
+
+This example shows how to create default outputs for a rule.
+
+`extension.bzl`:
+
+```python
+def impl(ctx):
+ ctx.file_action(
+ # Access the default outputs using ctx.outputs.<output name>.
+ output = ctx.outputs.my_output,
+ content = "Hello World!"
+ )
+ # The default outputs are added automatically to this target.
+
+rule_with_outputs = rule(
+ implementation = impl,
+ outputs = {
+ # %{name} is substituted with the rule's name
+ "my_output": "%{name}.txt"
+ }
+)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/extension", "rule_with_outputs")
+
+rule_with_outputs(name = "my_rule")
+```
+
+## <a name="outputs-custom"></a>Custom outputs
+
+This example shows how to create custom (user defined) outputs for a rule.
+This rule takes a list of output file name templates from the user and
+creates each of them containing a "Hello World!" message.
+
+`extension.bzl`:
+
+```python
+def impl(ctx):
+ # Access the custom outputs using ctx.outputs.<attribute name>.
+ for output in ctx.outputs.outs:
+ ctx.file_action(
+ output = output,
+ content = "Hello World!"
+ )
+ # The custom outputs are added automatically to this target.
+
+rule_with_outputs = rule(
+ implementation = impl,
+ attrs = {
+ "outs": attr.output_list()
+ }
+)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/extension", "rule_with_outputs")
+
+rule_with_outputs(
+ name = "my_rule",
+ outs = ["my_output.txt"]
+)
+```
+
+## <a name="master-rule"></a>Master rules
+
+This example shows how to create master rules to bind other rules together. The
+code below uses genrules for simplicity, but this technique is more useful with
+other rules. For example, if you need to compile C++ files, you can reuse
+`cc_library`.
+
+`extension.bzl`:
+
+```python
+def impl(ctx):
+ # Aggregate the output files from the depending rules
+ files = set()
+ files += ctx.target.dep_rule_1.files
+ files += ctx.target.dep_rule_2.files
+ return struct(files = files)
+
+# This rule binds the depending rules together
+master_rule = rule(
+ implementation = impl,
+ attrs = {
+ "dep_rule_1": attr.label(),
+ "dep_rule_2": attr.label()
+ }
+)
+
+def macro(name, cmd, input):
+ # Create the depending rules
+ name_1 = name + "_dep_1"
+ name_2 = name + "_dep_2"
+ native.genrule(
+ name = name_1,
+ cmd = cmd,
+ outs = [name_1 + ".txt"]
+ )
+ native.genrule(
+ name = name_2,
+ cmd = "echo " + input + " >$@",
+ outs = [name_2 + ".txt"]
+ )
+ # Create the master rule
+ master_rule(
+ name = name,
+ dep_rule_1 = ":" + name_1,
+ dep_rule_2 = ":" + name_2
+ )
+```
+
+`BUILD`:
+
+```build
+load("/pkg/extension", "macro")
+
+# This creates the target :my_rule
+macro(
+ name = "my_rule",
+ cmd = "echo something > $@",
+ input = "Hello World"
+)
+```
+
+## <a name="debugging-tips"></a>Debugging tips
+
+Here are some examples on how to do debug Skylark macros and rules.
+
+`debug.bzl`:
+
+```python
+print("print something when the module is loaded")
+
+def impl(ctx):
+ print("print something when the rule implementation is executed")
+ print(type("abc")) # prints string, the type of "abc"
+ print(dir(ctx)) # prints all the fields and methods of ctx
+ print(dir(ctx.attr)) # prints all the attributes of the rule
+ # prints the objects each separated with new line
+ print("object1", "object2", sep="\n")
+
+debug = rule(implementation=impl)
+```
+
+`BUILD`:
+
+```build
+load("/pkg/debug", "debug")
+
+debug(
+ name = "printing_rule"
+)
+```
diff --git a/docs/historical/README b/docs/historical/README
deleted file mode 100644
index 07bffe7..0000000
--- a/docs/historical/README
+++ /dev/null
@@ -1,2 +0,0 @@
-This directory contains historical documentation describing the state of Bazel
-at the time of the initial Open Source release.
diff --git a/docs/historical/bazel-user-manual.html b/docs/historical/bazel-user-manual.html
deleted file mode 100644
index ef183a4..0000000
--- a/docs/historical/bazel-user-manual.html
+++ /dev/null
@@ -1,3541 +0,0 @@
-<!DOCTYPE html>
-
-<html>
-<head>
- <meta charset="utf-8" />
- <title>A User's Guide to Bazel</title>
-
- <style type="text/css" id="internalStyle">
- 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> tag for bits of code and <var> for variable and object names. */
- code,pre,samp,var {
- color: #006000;
- }
- /* Use the <file> tag for file and directory paths and names. */
- file {
- color: #905050;
- font-family: monospace;
- }
- /* Use the <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> 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;
- }
-
- h1 { margin-bottom: 5px; }
- ul li { margin-bottom: 1em; }
- ul.toc li { margin-bottom: 0em; }
- em.harmful { color: red; }
- div#release { text-align: center; font-size: 14pt; font-weight: bold; font-family: courier; }
-
- .deprecated { text-decoration: line-through; }
- .discouraged { text-decoration: line-through; }
-
- table.truthtable {
- border-collapse: collapse;
- font-family: monospace;
- }
- table.truthtable th, table.truthtable td {
- border: 1px solid black;
- padding: 0.5em;
- text-align: center;
- }
- table.truthtable th {
- font-weight: bold;
- }
- table.truthtable td.rowhead {
- text-align: right;
- font-weight: bold;
- }
-
- 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>Related Documentation</h2>
-<ul class="toc">
- <li><a href="write_build_file.html">Getting Started with BUILD files</a></li>
- <li><a href="build-ref.html">BUILD Concept Reference</a></li>
- <li><a href="build-encyclopedia.html">Build Encyclopedia</a></li>
- <li><a href="bazel-query-v2.html">Bazel Query Reference</a></li>
-</ul>
-
-<h2>Contents</h2>
-
-<div id="nav" class="nav-2-levels"></div>
-
-
-<h2 id='introduction'>Introduction</h2>
-
-<h3>What is Bazel?</h3>
-
-<p>
- Bazel is a build system that
- emphasizes <i>correctness</i> and <i>reproducibility</i> of the
- build, <i>speed</i> of clean and incremental builds,
- and <i>integration</i> of the toolchain with IDEs and analysis
- tools. It is both a specification for code organization and a language for
- expressing software dependencies and the steps involved in a build.
-</p>
-
-<h3>Background reading</h3>
-
-<p>
- Various aspects of the Bazel build system are described in other
- documents.
-
- The <a href="build-ref.html">BUILD Concept Reference</a> introduces
- the primary concepts of the Bazel build system; this is a place to
- start if you are new to Bazel.
-
- The <a
- href="build-encyclopedia.html">Bazel
- BUILD Encyclopedia of Functions</a> describes all the functions of
- the Bazel build language, including the syntax and semantics of
- the current build rules.
-
- <a href="write_build_file.html">Getting Started
- with BUILD files</a> is a tutorial on how to write BUILD files.
-</p>
-
-<h2 id='concepts'>Bazel concepts</h2>
-
-<p>
- Running the <code>bazel</code> tool is easy. Simply go to your
- workspace root and type <code>bazel</code>.
- (Bazel may also be invoked from the subdirectories of your
- workspace.)
-</p>
-<pre>
- % bazel help
- 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.
- <a href='#version'>version</a> Prints version information for Bazel.
-
- Getting more help:
- bazel help <command>
- Prints help and options for <command>.
- bazel help <a href='#startup_options'>startup_options</a>
- Options for the JVM hosting Bazel.
- bazel help <a href='#target-patterns'>target-syntax</a>
- Explains the syntax for specifying targets.
- bazel help info-keys
- Displays a list of keys used by the info command.
-
-</pre>
-<p>
- The <code>bazel</code> tool performs many functions, called
- commands; users of Perforce, 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>. The links in the message
- above refer to the relevant section of this document.
-</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 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 of the Bazel
- <a href="#setup_workspace">workspace</a>. 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>
- In some cases, such as in continuous builds, it may be desirable to disable
- client/server mode and instead run Bazel as a batch application.
- See the <code class='flag'>--batch</code> switch <a href="#batch">below</a>.
-</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 the workspace root 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>.
-
- 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.
-
- 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=releasemode</code>.
-</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 --package_path %workspace%:/home/bob/stuff/bazel --keep_going --jobs 600
- build --color=yes
- query --keep_going
-
- build:releasemode --define buildtype="Release" --test_timeout=3600
-</pre>
-
-
-<h2 id='build'>Building programs with Bazel</h2>
-
-<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
- Welcome to Bazel
- ____Loading package: foo
- ____Loading package: bar
- ____Loading package: baz
- ____Loading complete. Analyzing...
- ____Building 1 target...
- ____[0%] Executing Genrule //bar:helper_rule
- ____[10%] Executing Genrule //baz:another_helper_rule
- ____[95%] Building foo/foo.jar
- Target //foo:foo up-to-date:
- bazel-bin/foo/foo.jar
- bazel-bin/foo/foo
- ____Elapsed time: 9.905s
-</pre>
-<p>
- Bazel prints a welcome message, followed by progress messages as it loads all the
- packages in the transitive closure of dependencies of the requested
- target and analyzes them for correctness, then executes 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 that is being started,
- and approximately what fraction of the build is complete. If the
- estimate of the total workload includes steps that are already
- up-to-date, progress will advance rapidly when this is discovered.
- Since progress is reported when steps are started, rather than
- completed, the reported progress will never reach 100%, and, if
- multiple steps are started with no intervening completions, the
- reported progress will not change.
-</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
- Welcome to Bazel
- ____Loading complete. Analyzing...
- ____Building 1 target...
- Target //foo:foo up-to-date:
- bazel-bin/foo/foo.jar
- bazel-bin/base/foo
- ____Elapsed time: 0.280s
-</pre>
-<p>
- we see an incremental build: in this case, there are no packages to
- re-load, since nothing has changed, and no build steps to execute.
- In most cases, this results in dramatically faster output time.
-</p>
-
-<h3 id='setup_workspace'>Setting up a Bazel workspace</h3>
-
-<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 Bazel label syntax (as used in BUILD files) is used to specify a
-single target. Bazel 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 the first existing one of these:
- //foo/bar:wiz
- //foo:bar/wiz
- //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 = 'bazel/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:all Equivalent to '//foo/bar:all'.
- :all Equivalent to '//foo:all'.
-
-Note: The "..." (recursive) syntax does not follow directory symlinks.
-
-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 .par and _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. For example:
-
- % bazel build -- bigtable/... -bigtable/contrib/...
-
- builds everything in 'bigtable', except 'contrib'. As usual, the
- '--' is required to prevent '-b' from being interpreted as an
- option.
-</pre>
-<p>
- Whereas Bazel <a href="build-ref.html#label">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 and <code>.par</code> files
- associated with <code>py_binary</code> rules.
-
- 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, in which the building of <code>_deploy.jar</code>
- and <code>.par</code> targets 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. 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/baz/...
-</pre>
-<p>
- means "build all targets beneath <code>foo</code> <i>except</i>
- those beneath <code>foo/baz</code>".
-
- (The <code>--</code> argument is required to prevent the subsequent
- arguments starting with <code>-</code> from being interpreted as
- additional options.)
-</p>
-<p>
-Targets with <code>obsolete=1</code> or <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>
-<h4>Bash completion of Bazel commands</h4>
-<p>
- If you use Bash, and source /etc/bash_completion,
- Bash's command-completion is augmented to understand Bazel's
- options, command set, and target syntax. For example,
- hitting <code>TAB</code> after typing a package name followed by a
- colon will expand the names of rules defined in that package:
-</p>
-<pre>
- % source /etc/bash_completion
- % bazel build bar:<TAB>
- aardvark
- alpha
- chestnut
- walnut
- ...
- % bazel build bar:a<TAB>
- aardvark
- alpha
- % bazel build bar:al<TAB>
- % bazel build bar:alpha
-</pre>
-<p>
- Similarly, hitting <code>TAB</code> after <code>bazel
- test <var>package</var>:</code> will expand the names of just
- the <em>test</em> rules in that package.
-</p>
-<p>
- The completion script will additionally attempt to
- expand <code>--key=value</code> options too.
-</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.
- A similar situation may arise when switching to a source-control view of an
- earlier milestone.
-</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>
-
-<h3>Deleting the outputs of a build</h3>
-
-<h4 id='clean'><code>bazel clean</code></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>
- 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 are not
- 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.
- We encourage developers to get out of the habit of
- using <code>clean</code> and into that of reporting bugs in the
- tools.
-</p>
-
-
-<h3 id='phases'>Phases of a build</h3>
-
-<p>
- In Bazel, a build occurs in three distinct phases; as a user,
- understanding the difference between them provides insight into the
- options which control a build (see below).
-</p>
-
-<h4 id='loading-phase'>Loading phase</h4>
-<p>
- The first is <b>loading</b> during which all the necessary BUILD
- files for the initial targets, and their transitive closure of
- dependencies, are loaded, parsed, evaluated and cached.
-</p>
-<p>
- For the first build after a Bazel server is started, the loading
- phase can take many seconds if many BUILD files are loaded
- from high-latency / remotely hosted filesystems. In subsequent builds,
- especially if no BUILD files have changed, loading occurs very
- quickly.
-</p>
-<p>
- Errors reported during this phase include: package not found, target
- not found, lexical and grammatical errors in a BUILD file,
- and evaluation errors.
-</p>
-
-<h4 id='analysis-phase'>Analysis phase</h4>
-<p>
- The second phase, <b>analysis</b>, involves the semantic analysis
- and validation of each build rule, the construction of a build
- dependency graph, and the determination of exactly what work is to
- be done in each step of the build.
-</p>
-<p>
- Like loading, analysis also takes several seconds when computed in
- its entirety. However, Bazel can cache the dependency graph from
- one build to the next, as an optimization;
- see <a href='#flag--cache_analysis'><code class='flag'>--cache_analysis</code></a>).
- This option makes this step extremely fast in the case where the
- packages haven't changed since the previous build.
-</p>
-<p>
- Errors reported at this stage include: inappropriate dependencies,
- invalid inputs to a rule, and all rule-specific error messages.
-</p>
-<p>
- The loading and analysis phases are generally very vast; this is partly because
- Bazel avoids unnecessary file I/O at this stage, reading only BUILD
- files in order to determine the work to be done. This is by design,
- and makes Bazel a good foundation for analysis tools, such as
- Bazel's <a href='#query'>query</a> command, which is implemented
- atop the loading phase.
-</p>
-
-<h4 id='execution-phase'>Execution phase</h4>
-<p>
- The third and final phase of the build is <b>execution</b>. This
- phase ensures that the outputs of each step in the build are
- consistent with its inputs, re-running external compilation tools as
- necessary. This step is where the build spends the majority of
- its time, ranging from a few seconds to over an hour for a large
- build. Errors reported during this phase include: missing source
- files, errors in an external compilation tool, or failure of a tool to
- produce the expected set of outputs.
-</p>
-
-
-<h2>Options</h2>
-
-<p>
- The following sections describe the options available during a
- build. When <code class='flag'>--long</code> is used on a help command, the on-line
- help messages provide summary information about the meaning, type and
- default value for each option.
-</p>
-
-<p>
- Most options can only be specified once. When specified multiple times, the
- last instance wins. Options that can be specified multiple times are
- identified in the on-line help with the text 'may be used multiple times'.
-</p>
-
-<h3>Options that affect how packages are located</h3>
-
-<p>
- See also the <a href='#flag--show_package_location'><code class='flag'>--show_package_location</code></a>
- option.
-</p>
-
-<h4><code class='flag'>--package_path</code></h4>
-<p>
- This option specifies the set of directories that are searched to
- find the BUILD file for a given package; see
- <a href='#flag--package_path'>Setting up a Bazel workspace</a> above
- for a complete explanation.
-</p>
-
-<h4 id='flag--deleted_packages'><code class='flag'>--deleted_packages</code></h4>
-<p>
- This option specifies a comma-separated list of packages which Bazel
- should consider deleted, and not attempt to load from any directory
- on the package path.
-</p>
-<p>
- if you use a workspace layout that maps the entire source tree into some readonly path while
- mapping writable subsections into another path, you may need to use this option to solve
- the following problem: when you have a pending deletion of a package in your
- Bazel workspace, but there is still a BUILD file for this package somewhere
- on your package path, Bazel will consider the package existent unless this
- option tells it not to.
-</p>
-<p>
- Consider the following scenario: you have two
- packages, <code>x</code> and <code>x/y</code> (a subpackage). When
- you populate your client, both packages exist beneath both
- package-path roots:
-</p>
-<pre>
- ~/src/$WORKSPACE_WRITABLE_ROOT/
- /x/BUILD
- /x/y/BUILD <-- about to delete this
- /x/y/foo.txt
-
- ~/src/$WORKSPACE_READONLY_ROOT/
- /x/BUILD
- /x/y/BUILD
- /x/y/foo.txt
-</pre>
-<p>
- Now you delete <code>~/src/$WORKSPACE_WRITABLE_ROOT/x/y/BUILD</code>, intending to
- merge the contents of package <code>x/y</code> into <code>x</code>,
- and now when x's BUILD file refers to the
- file <code>x/y/foo.txt</code>, it uses the
- label <code>//x:y/txt</code>.
-</p>
-<p>
- However, x/y may have been deleted in the read/write workspace, but the
- package still exists elsewhere on the package-path. In this situation, Bazel
- will issue an error, saying that <code>//x:y/txt</code> is an invalid label
- because package <code>x/y</code> still exists (beneath <code>$WORKSPACE_READONLY_ROOT</code>).
- The solution is to specify <code class='flag'>--deleted_packages x/y</code>.
-</p>
-
-
-<h3 id='checking-options'>Error checking options</h3>
-<p>
- These options control Bazel's error-checking and/or warnings.
-</p>
-
-<h4><code class='flag'>--check_constraint <var>constraint</var></code></h4>
-<p>
- This option takes an argument that specifies which constraint
- should be checked.
-</p>
-<p>
- Bazel performs special checks on each rule that is annotated with the
- given constraint.
-</p>
-<p>
- The supported constraints and their checks are as follows:
-</p>
-<ul>
- <li><code>public</code>: Verify that all java_libraries marked with
- <code>constraints = ['public']</code> only depend on java_libraries
- that are marked as <code>constraints = ['public']</code> too. If Bazel
- finds a dependency that does not conform to this rule, Bazel will issue
- an error.
- </li>
-</ul>
-
-<h4 id='flag--check_licenses'><code class='flag'>--[no]check_licenses</code></h4>
-<p>
- This option causes Bazel to analyze the <code>licenses</code> and
- <code>distribs</code> clauses in BUILD files to identify uses of third
- party code that are incompatible with how a product is going to be
- distributed.
-</p>
-<pre>
- % bazel build --check_licenses //foo:bar
-</pre>
-<p>
- will check the licensing of all packages used by "//foo:bar", to
- ensure that they are compatible with how bar is distributed. If the
- licensing check finds no errors, then bar will be built.
-</p>
-
-<h4 id='flag--check_visibility'><code class='flag'>--[no]check_visibility</code></h4>
-<p>
- If this option is set to false, visibility checks are demoted to warnings.
- The default value of this option is true, so that by default, visibility
- checking is done.
-</p>
-
-
-<h4 id='flag--output_filter'><code class='flag'>--output_filter <var>regex</var></code></h4>
-<p>
- The <code class='flag'>--output_filter</code> option will only show build and compilation
- warnings for targets that match the regular expression. If a target does not
- match the given regular expression and its execution succeeds, its standard
- output and standard error are thrown away. This option is intended to be used
- to help focus efforts on fixing warnings in packages under development. Here
- are some typical values for this option:
-</p>
-<table>
- <tr>
- <td><code class='flag'>--output_filter=</code></td>
- <td>Show all output.</td>
- </tr>
- <tr>
- <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td>
- <td>Show the output for the specified packages.</td>
- </tr>
- <tr>
- <td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td>
- <td>Don't show output.</td>
- </tr>
-</table>
-<p>
- If this option is not given, a default filter will be created according to the
- <a href="#flag--auto_output_filter"><code class='flag'>--auto_output_filter</code> option</a>.
-</p>
-
-<h4 id='flag--auto_output_filter'><code class='flag'>--auto_output_filter (none|packages|subpackages)</code></h4>
-
-<p>
- If no <a href="#--output_filter"><code class='flag'>--output_filter</code> option</a> is
- given, Bazel creates an output filter from the targets listed on the command
- line:
-</p>
-<ul>
- <li>
- <code>none</code> does no filtering and shows all output.
- </li>
- <li>
- <code>packages</code> shows only the output for the packages of targets
- requested on the command line. For example, the Bazel invocation
- <pre> % bazel build //foo:bar //baz/...</pre>
- will show the output for all targets in the package <code>foo</code> or any
- package under <code>baz</code>. Warnings for dependencies in other packages
- will be hidden.
- </li>
- <li>
- <code>subpackages</code> (the default) works similar
- to <code>packages</code> but also includes output from subpackages.
- </li>
-</ul>
-
-<h4><code>--[no]analysis_warnings_as_errors</code></h4>
-<p>
- When this option is enabled, visible analysis warnings (as specified by
- the output filter) are treated as errors, effectively preventing the build
- phase from starting. This feature can be used to enable strict builds that
- do not allow new warnings to creep into a project.
-</p>
-
-
-<h3 id='flags-options'>Flags options</h3>
-<p>
- These options control which options Bazel will pass to other tools.
-</p>
-
-<h4 id='flag--jvmopt'><code class='flag'>--jvmopt <var>jvm-option</var></code></h4>
-<p>
- This option allows option arguments to be passed to the Java VM. It can be used
- with one big argument, or multiple times with individual arguments. For example:
-</p>
-<pre>
- % bazel build --jvmopt="-server -Xms256m" java/com/myorg/foo/bar:all
-</pre>
-<p>
- will use the server VM for launching all Java binaries and set the
- startup heap size for the VM to 256 MB.
-</p>
-
-<h4 id='flag--javacopt'><code class='flag'>--javacopt <var>javac-option</var></code></h4>
-<p>
- This option allows option arguments to be passed to javac. It can be used
- with one big argument, or multiple times with individual arguments. For example:
-</p>
-<pre>
- % bazel build --javacopt="-g:source,lines" //myprojects:prog
-</pre>
-<p>
- will rebuild a java_binary with the javac default debug info
- (instead of the Bazel default).
-</p>
-<p>
- The option is passed to javac after the Bazel built-in default options for
- javac and before the per-rule options. The last specification of
- any option to javac wins. The default options for javac are:
-</p>
-<pre>
- -g -source 7 -target 7 -encoding UTF-8 -Xlint:all,-serial,-processing,-fallthrough,-deprecation,-sunapi,-rawtypes,-try,-cast,-varargs,-finally,-static,-dep-ann,-overrides,-unchecked -Werror:+divzero,+empty
-</pre>
-<p>
- Note that changing <code class='flag'>--javacopt</code> settings will force a recompilation
- of all affected classes. Also note that javacopts parameters listed in
- specific java_library or java_binary build rules will be placed on the javac
- command line <em>after</em> these options.
-</p>
-
-<h5 id='-Werror'><code>-Werror:<var>(+|-)warning[,(+|-)warning]*</var></code></h5>
-
-<p>
- This javac option enables selective treating of warnings as errors. To specify
- all or none of the warnings, use <code>+all</code> or <code>-all</code>.
- The last specification for any warning wins. A typical value that enables all
- warnings as errors except those that may be caused upstream is:
-</p>
-<pre>
- -Werror:+all,-deprecation,-unchecked
-</pre>
-
-<p>
- The divzero and empty javac warnings are promoted to errors by default. These
- errors cannot be disabled from the Bazel command line or the BUILD file.
- However, in extreme cases they may be disabled by adding a
- <code>@SuppressWarnings({"divzero", "empty"})</code> annotation to your Java
- source.
-</p>
-
-<h5 id='-extra_checks'><code>-extra_checks[:(off|on)]</code></h5>
-
-<p>
- This javac option enables extra correctness checks. Any problems found will
- be presented as errors.
- Either <code>-extra_checks</code> or <code>-extra_checks:on</code> may be used
- to force the checks to be turned on. <code>-extra_checks:off</code> completely
- disables the analysis.
- When this option is not specified, the default behavior is used.
-</p>
-
-<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps
- (default|strict|off|warn|error)</code></h4>
-<p>
- This option controls whether javac checks for missing direct dependencies.
- Java targets must explicitly declare all directly used targets as
- dependencies. This flag instructs javac to determine the jars actually used
- for type checking each java file, and warn/error if they are not the output
- of a direct dependency of the current target.
-</p>
-<ul>
- <li> <code>off</code> means checking is disabled.
- </li>
- <li> <code>warn</code> means javac will generate standard java warnings of
- type <code>[strict]</code> for each missing direct dependency.
- </li>
- <li> <code>default</code>, <code>strict</code> and <code>error</code> all
- mean javac will generate errors instead of warnings, causing the current
- target to fail to build if any missing direct dependencies are found.
- This is also the default behavior when the flag is unspecified.
- </li>
-</ul>
-
-<h4><code class='flag'>--javawarn (all|cast|deprecation|empty|unchecked|fallthrough|path|rawtypes|serial|finally|overrides)</code></h4>
-<p>
- This option is used to enable Java warnings across an entire build. It takes
- an argument which is a javac warning to be enabled, overriding any other Java
- options that disable the given warning. The arguments to this option are
- appended to the "-Xlint:" flag to javac, and must be exactly one of
- the listed warnings.
-</p>
-<p>
- For example:
-</p>
-<pre>
- % bazel build --javawarn="deprecation" --javawarn="unchecked" //java/...
-</pre>
-<p>
- Note that changing <code class='flag'>--javawarn</code> settings will force a recompilation
- of all affected classes.
-</p>
-
-
-<h3 id='semantics-options'>Semantics options</h3>
-<p>
- These options affect the build commands and/or the output file contents.
-</p>
-
-<h4><code class='flag'>--java_cpu <var>cpu</var></code></h4>
-<p>
- This option specifies the name of the CPU architecture that should
- be used to build libraries dynamically loaded by the JVM.
-</p>
-
-<h4><code class='flag'>--android_cpu <var>cpu</var></code></h4>
-<p>
- This option specifies the name of the CPU architecture
- that should be used to build libraries dynamically loaded by the Android
- applications.
-</p>
-
-<h4 id="flag--define"><code class='flag'>--define <em>name=value</em></code></h4>
-<p>
- This option takes an argument which is a variable
- definition of the form "name=value". The defined variable is integrated
- into the build environment as if they were declared in the BUILD file
- using a <code>vardef</code> statement. This option can occur multiple times
- on the command-line. If the same variable is declared more than once, the
- <em>last</em> definition is the one which is used.
-</p>
-<pre>
- % bazel build --define "INCLUDE_X=1" --define "LINK_Y=no" foo:bar
-</pre>
-<p>
- will build target "foo:bar", and all its prerequisites, with the
- variable assignments <code>INCLUDE_X=1</code>,
- and <code>LINK_Y=no</code> in the "Make" environment.
-</p>
-<p>
- Definitions specified in this way are global: they apply to all
- packages. The order of precedence for definitions of "Make"
- variables, highest first, is: <code class='flag'>--define
- k=...</code>, <code>vardef('k',
- ...)</code>, then the global defaults.
-</p>
-
-<h4 id='flag--translations'><code class='flag'>--[no]translations</code></h4>
-<p>
- The <code class='flag'>--notranslations</code> option can be used to disable the bundling
- of translated Java messages into the jar for each affected rule. By default,
- Bazel will locate the Java message translations on the package path using the
- targets defined by <a href="#--message_translations">
- <code class='flag'>--message_translations</code></a> and use the resulting files for
- translating the messages for each <code>java_library</code>. If no
- targets are specified, Bazel does not bundle translations.
-</p>
-
-<h4 id='flag--message_translations'><code class='flag'>--message_translations
- <var>translation-targets</var></code></h4>
-<p>
- This option specifies the targets containing the Java message
- translations. These targets are used to
- find the Java message translations for each locale. This option can
- be used multiple times to specify a list of translations. The
- targets are specified using standard label syntax. Rules that output
- directories, such as
- <a
- href="build-encyclopedia.html#Fileset">Fileset</a>
- and misbehaving genrules, cannot be used with this flag.
-</p>
-<p>
- Typically translations will increase build times significantly.
-</p>
-<pre>
- % bazel build \
- --message_translations=//some/package/client:translations \
- --message_translations=//some/package/server:translations \
- java/com/myorg/myapp:Myapp_deploy.jar
-</pre>
-<p>
- will build the <code>Myapp_deploy.jar</code> including
- translations. The translations will be retrieved from the
- project-specific translations in
- <code>//some/package/client:translations</code>
- and
- <code>//some/package/server:translations</code>
-</p>
-
-
-<h3 id='version-options'>Version options</h3>
-These options select which versions Bazel will use for the other tools that Bazel invokes.
-
-<h4 id='android_sdk'><code class='flag'>--android_sdk <var>version</var></code></h4>
-<p>
- This option specifies the version of the Android SDK/platform toolchain
- and Android runtime library that will be used to build any Android-related
- rule.
-</p>
-
-<h4 id='flag--java_langtools'><code class='flag'>--java_langtools <var>label</var></code></h4>
-<p>
- This option specifies the label of the Java langtools jar (used by
- Java compilation tools).
-</p>
-
-<h4><code class='flag'>--javabase <var>path</var></code></h4>
-<p>
- This option specifies the value of the <code>JAVABASE</code>
- <a href='build-encyclopedia.html#make_variables'>"Make" variable</a>
- which is passed to all subprocesses (e.g. external Java programs)
- during a build.
-</p>
-
-<p>
- This does not select the Java compiler that is used to compile Java
- source files. There is currently no way to do that, but you can use
- <code class='flag'>--javacopt="-source 5 -target 5"</code> (for example) to
- select a different version of the source language (Java) or target
- language (JVM) during compilation.
-</p>
-
-<h4 id='flag--javac_bootclasspath'><code class='flag'>--javac_bootclasspath <var>label</var></code></h4>
-<p>
- This option specifies the label of the bootclasspath that should be used by
- the Java compiler. This lets you compile against different versions of the
- Java class library, for example, version 7 instead of version 6.
-</p>
-
-
-<h3 id='strategy-options'>Build strategy options</h3>
-<p>
- These options affect how Bazel will execute the build.
- They should not have any significant effect on the output files
- generated by the build. Typically their main effect is on the
- speed on the build.
-</p>
-
-<h4><code class='flag'>--jobs <var>n</var></code> (-j)</h4>
-<p>
- This option, which takes an integer argument, specifies a limit on
- the number of jobs that should be executed concurrently during the
- execution phase of the build. The default is 200.
-</p>
-<p>
- Setting this to -1 means "no limit": use as many threads as possible.
-</p>
-<p>
- Note that the number of concurrent jobs that Bazel will run
- is determined not only by the <code class='flag'>--jobs</code> setting, but also
- by Bazel's scheduler, which tries to avoid running concurrent jobs
- that will use up more resources (RAM or CPU) than are available,
- based on some (very crude) estimates of the resource consumption
- of each job. The behavior of the scheduler can be controlled by
- the <code class='flag'>--ram_utilization_factor</code> option.
-</p>
-
-<h4><code class='flag'>--progress_report_interval <var>n</var></code></h4>
-<p>
-
- Bazel periodically prints a progress report on jobs that are not
- finished yet (e.g. long running tests). This option sets the
- reporting frequency, progress will be printed every <code>n</code>
- seconds.
-</p>
-<p>
- The default is 0, that means an incremental algorithm: the first
- report will be printed after 10 seconds, then 30 seconds and after
- that progress is reported once every minute.
-</p>
-
-<h4><code class='flag'>--ram_utilization_factor</code> <var>percentage</var></h4>
-<p>
- This option, which takes an integer argument, specifies what percentage
- of the system's RAM Bazel should try to use for its subprocesses.
- This option affects how many processes Bazel will try to run
- in parallel. The default value is 67.
- If you run several Bazel builds in parallel, using a lower
- value for this option may avoid thrashing and thus improve overall
- throughput. Using a value higher than the default is NOT recommended. Note
- that Bazel's estimates are very coarse, so the actual RAM usage may be much
- higher or much lower than specified. Note also that this option does not
- affect the amount of memory that the Bazel server itself will use.
-</p>
-<p>
- This option has no effect if --resource_autosense is enabled.
-</p>
-
-<h4><code class='flag'>--local_resources</code> <var>availableRAM,availableCPU,availableIO</var></h4>
-<p>
- This option, which takes three comma-separated floating point arguments,
-specifies the amount of local resources that Bazel can take into
-consideration when scheduling build and test activities. Option expects amount of
-available RAM (in MB), number of CPU cores (with 1.0 representing single full
-core) and workstation I/O capability (with 1.0 representing average
-workstation). By default Bazel will estimate amount of RAM and number of CPU
-cores directly from system configuration and will assume 1.0 I/O resource.
-</p>
-<p>
- If this option is used, Bazel will ignore both --ram_utilization_factor and
- --resource_autosense options.
-</p>
-
-<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4>
-<p>
- This option, which is currently enabled by default, specifies
- whether the runfiles symlinks for tests
- should be built on the local
- machine. Using <code class='flag'>--nobuild_runfile_links</code> can be useful
- to validate if all targets build without incurring the overhead
- for building the runfiles trees.Within Bazel's output tree, the
- runfiles symlink tree is typically rooted as a sibling of the corresponding
- binary or test.
-</p>
-<p>
- When Bazel tests are executed, their
- run-time data dependencies are gathered together in one place, and
- may be accessed by the test using paths of the form
- <code>$TEST_SRCDIR/bazel/<var>packagename</var>/<var>filename</var></code>.
- The "runfiles" tree ensures that tests have access to all the files
- upon which they have a declared dependence, and nothing more. By
- default, the runfiles tree is implemented by constructing a set of
- symbolic links to the required files. As the set of links grows, so
- does the cost of this operation, and for some large builds it can
- contribute significantly to overall build time, particularly because
- each individual test requires its own runfiles tree.
-</p>
-
-<h4 id='flag--cache_analysis'><code class='flag'>--[no]cache_analysis</code></h4>
-<p>
- This option enables an optimization: caching of the results of the
- analysis phase from one build to the next. The dependency graph
- from the previous build will be re-used if no build packages have
- been re-loaded due to changes, and no configuration options have
- changed.
- The optimization is enabled by default, but can be disabled
- via <code class='flag'>--nocache_analysis</code>; this may be useful during fault
- isolation.
-</p>
-<p>
- Typically, this option speeds up
- the <a href='#analysis-phase'>analysis phase</a> by a factor of at
- least a hundred, making analysis time a negligible fraction of total
- build time.
-</p>
-
-<h4 id='flag--discard_analysis_cache'>
- <code class='flag'>--[no]discard_analysis_cache</code></h4>
-<p>
- When this option is enabled, Bazel will discard the analysis cache
- right before execution starts, thus freeing up additional memory
- (around 10%) for the <a href="#execution-phase">execution phase</a>.
- The drawback is that further incremental builds will be slower.
-</p>
-
-<h4><code class='flag'>--[no]keep_going</code> (-k)</h4>
-<p>
- As in GNU Make, the execution phase of a build stops when the first
- error is encountered. Sometimes it is useful to try to build as
- much as possible even in the face of errors. This option enables
- that behavior, and when it is specified, the build will attempt to
- build every target whose prerequisites were successfully built, but
- will ignore errors.
-</p>
-<p>
- While this option is usually associated with the execution phase of
- a build, it also effects the analysis phase: if several targets are
- specified in a build command, but only some of them can be
- successfully analyzed, the build will stop with an error
- unless <code class='flag'>--keep_going</code> is specified, in which case the
- build will proceed to the execution phase, but only for the targets
- that were successfully analyzed.
-</p>
-
-<h4><code class='flag'>--[no]resource_autosense</code></h4>
-<p>
- Bazel's default scheduling algorithm is based on fixed estimates of
- the available CPU/memory resources of the workstation. It does not
- account for the load of any unrelated jobs that happen to be running
- on your machine, such as another Bazel build in a different
- workspace.
-</p>
-<p>
- The <code class='flag'>--resource_autosense</code> option enables a different
- scheduling algorithm for the execution of build steps. It causes
- Bazel to poll the system CPU load and available memory periodically.
- This data is used to limit the number of commands executed
- simultaneously on the workstation, ensuring that the system remains
- responsive, especially when other jobs are running on the machine.
-</p>
-<p>
- (Note, neither algorithm takes into account the actual (dynamic)
- cost of each build step.)
-</p>
-
-<h3 id='output-selection-options'>Output selection options</h3>
-<p>
- These options determine what to build or test.
-</p>
-
-<h4 id="nobuild"><code class='flag'>--[no]build</code></h4>
-<p>
- This option causes the execution phase of the build to occur; it is
- on by default. When it is switched off, the execution phase is
- skipped, and only the first two phases, loading and analysis, occur.
-</p>
-<p>
- This option can be useful for validating BUILD files and detecting
- errors in the inputs, without actually building anything.
-</p>
-
-<h4><code class='flag'>--[no]build_tests_only</code></h4>
-<p>
- If specified, Bazel will build only what is necessary to run the *_test
- and test_suite rules that were not filtered due to their
- <a href='#flag--test_size_filters'>size</a>,
- <a href='#flag--test_timeout_filters'>timeout</a>,
- <a href='#flag--test_tag_filters'>tag</a>, or
- <a href='#flag--test_lang_filters'>language</a>.
- If specified, Bazel will ignore other targets specified on the command line.
- By default, this option is disabled and Bazel will build everything
- requested, including *_test and test_suite rules that are filtered out from
- testing. This is useful because running
- <code>bazel test --build_tests_only foo/...</code> may not detect all build
- breakages in the <code>foo</code> tree.
-</p>
-
-<h4 id="flag--compile_only"><code class='flag'>--[no]compile_only</code></h4>
-<p>
- This option forces Bazel to execute only "lightweight" compilation steps
- related to the specified targets. At this time such steps only include
- compilation of sources for <code>java_*</code> rules
- without building dependencies.
-</p>
-<p>
- This option can be useful to quickly validate a given Java target for
- compilation errors. In particular, it might be especially useful when
- specified together with the <a href="#flag--compile_one_dependency">
- <code class='flag'>--compile_one_dependency</code></a> option.
-</p>
-
-<h4 id="flag--compilation_prerequisites_only"><code class='flag'>--[no]compilation_prerequisites_only</code></h4>
-<p>
- Given this option, Bazel will only build files that are prerequisites for
- compilation of the given target (for example, generated source
- files), but will not build the target itself.
-</p>
-<p>
- This option can be useful to quickly validate a given Java target for
- compilation errors. In particular, it might be especially useful when
- specified together with the <a href="#flag--compile_one_dependency">
- <code class='flag'>--compile_one_dependency</code></a> option.
-</p>
-
-<h4 id='flag--check_up_to_date'><code class='flag'>--[no]check_up_to_date</code></h4>
-<p>
- This option causes Bazel not to perform a build, but merely check
- whether all specified targets are up-to-date. If so, the build
- completes successfully, as usual. However, if any files are out of
- date, instead of being built, an error is reported and the build
- fails. This option may be useful to determine whether a build has
- been performed more recently than a source edit (e.g. for pre-submit
- checks) without incurring the cost of a build.
-</p>
-<p>
- See also <a href="#flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></a>.
-</p>
-
-<h4 id='flag--compile_one_dependency'><code class='flag'>--[no]compile_one_dependency</code></h4>
-<p>
- Compile a single dependency of the argument files. This is useful for
- syntax checking source files in IDEs, for example, by rebuilding a single
- target that depends on the source file to detect errors as early as
- possible in the edit/build/test cycle. This argument affects the way all
- non-flag arguments are interpreted: for each source filename, one
- rule that depends on it will be built.
- Rules in the same language space are preferentially chosen. For
- multiple rules with the same preference, the one that appears first in the
- BUILD file is chosen. An explicitly named target pattern which does not
- reference a source file results in an error.
-</p>
-
-<h4 id='flag--source_jars'><code class='flag'>--[no]source_jars</code></h4>
-<p>
- By default, this option is disabled. If enabled, Bazel will also build all
- source jars in the transitive closure of the targets specified on the command
- line.
-</p>
-
-<h4 id='flag--test_size_filters'><code class='flag'>--test_size_filters <var>size[,size]*</var></code></h4>
-<p>
- If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
- is also specified) only test targets with the given size. Test size filter
- is specified as comma delimited list of allowed test size values (small,
- medium, large or enormous), optionally preceded with '-' sign used to denote
- excluded test sizes. For example,
-</p>
-<pre>
- % bazel test --test_size_filters=small,medium //foo:all
-</pre>
- and
-<pre>
- % bazel test --test_size_filters=-large,-enormous //foo:all
-</pre>
-<p>
- will test only small and medium tests inside //foo.
-</p>
-<p>
- By default, test size filtering is not applied.
-</p>
-
-<h4 id='flag--test_timeout_filters'><code class='flag'>--test_timeout_filters <var>timeout[,timeout]*</var></code></h4>
-<p>
- If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
- is also specified) only test targets with the given timeout. Test timeout filter
- is specified as comma delimited list of allowed test timeout values (short,
- moderate, long or eternal), optionally preceded with '-' sign used to denote
- excluded test timeouts. See <a href='#flag--test_size_filters'>--test_size_filters</a>
- for example syntax.
-</p>
-<p>
- By default, test timeout filtering is not applied.
-</p>
-
-
-<h4 id='flag--test_tag_filters'><code class='flag'>--test_tag_filters <var>tag[,tag]*</var></code></h4>
-<p>
- If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code>
- is also specified) only test targets that have at least one required tag
- (if any of them are specified) and does not have any excluded tags. Test tag
- filter is specified as comma delimited list of tag keywords, optionally
- preceded with '-' sign used to denote excluded tags. Required tags may also
- have a preceding '+' sign.
-</p>
-<p>
- For example,
-<pre>
- % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all
-</pre>
-<p>
- will test targets that are tagged with either <code>performance</code> or
- <code>stress</code> tag but are <b>not</b> tagged with the <code>flaky</code>
- tag.
-</p>
-<p>
- By default, test tag filtering is not applied. Note that you can also filter
- on test's <code>size</code> and <code>local</code> tags in
- this manner.
-</p>
-
-<h4 id="flag--test_filter"><code class='flag'>--test_filter=<var>filter-expression</var></code></h4>
-<p>
- Specifies a filter that the test runner may use to pick a subset of tests for
- running. All targets specified in the invocation are built, but depending on
- the expression only some of them may be executed; in some cases, only certain
- test methods are run.
-</p>
-<p>
- The particular interpretation of <var>filter-expression</var> is up to
- the test framework responsible for running the test. It may be a glob,
- substring, or regexp. <code class='flag'>--test_filter</code> is a convenience
- over passing different <code class='flag'>--test_arg</code> filter arguments,
- but not all frameworks support it.
-<p>
- Examples:
-</p>
-<pre>
- :my_junit3_test --test_filter=com.myorg.myproj.MyClass#testMyStuff
- # class or method (multiple
- # values OK, separate w/commas)
- :my_junit4_test --test_filter=Frob.*ate # regexp
-</pre>
-
-
-<h3>Verbosity options: options that control what Bazel prints</h3>
-
-These options control the verbosity of Bazel's output,
-either to the terminal, or to additional log files.
-
-<h4 id='flag--dump_makefile'><code class='flag'>--dump_makefile</code></h4>
-<p>
- If this option is specified, Bazel will dump a representation
- of the action graph for the current build request in (pseudo)
- <code>make</code> syntax to the file <code>Makefile.bazel</code>
- in the execution root directory.
-</p>
-<p>
- This is for debugging purposes only. The format of the output file
- might change in future Bazel releases.
-</p>
-
-<h4 id='flag--dump_action_graph'><code class='flag'>--dump_action_graph</code></h4>
-<p>
- If this option is specified, Bazel will dump a representation of the
- action graph for the current build request in GraphViz syntax to the
- file 'BazelActionGraph.dot' in the workspace root.
-</p>
-<p>
- This is for debugging purposes only. The format of the output file
- might change in future Bazel releases.
-</p>
-
-<h4 id='flag--dump_action_graph_for_package'>
- <code class='flag'>--dump_action_graph_for_package=package</code>
-</h4>
-<p>
- This option restricts the parts shown in an action graph to the given packages.
- This is only useful in conjunction with specifying <code class='flag'>--dump_action_graph</code>.
-</p>
-
-<h4 id='flag--dump_action_graph_with_middlemen'>
- <code class='flag'>--dump_action_graph_with_middlemen</code>
-</h4>
-<p>
- This flag selects whether middlemen are shown in an action graph or not. Middlemen could be
- considered an implementation detail and tend to make graphs much larger.
- This is only usful in conjuction with specifying <code class='flag'>--dump_action_graph</code>.
-</p>
-
-<h4 id='flag--dump_targets'><code class='flag'>--dump_targets=(inputs|rules|all|packages)</code></h4>
-<p>
- If this option is specified, Bazel will dump the targets touched
- by the current build request to the file <code>BazelTargets.txt</code>.
-</p>
-<ul>
- <li><code class='flag'>--dump_targets=inputs</code> will dump the labels of the input
- file targets.</li>
- <li><code class='flag'>--dump_targets=rules</code> will dump the labels of the rule
- targets.</li>
- <li><code class='flag'>--dump_targets=all</code> will dump the labels of the rule
- and input file targets.</li>
- <li><code class='flag'>--dump_targets=packages</code> will dump the package names of
- the rule and input file targets.
- <br/><strong>Please note:</strong>Only packages that contain
- input files are dumped. BUILD files are not considered as input files.
- That means that packages that do not contain any input files will not
- be dumped. Even so they may be part of the transitive closure of the
- current build request.</li>
-</ul>
-
-<h4 id='flag--dump_to_stdout'><code class='flag'>--dump_to_stdout</code></h4>
-<p>
- If this option is specified, the options
- <code class='flag'>--dump_action_graph</code>, <code class='flag'>--dump_makefile</code>
- and <code class='flag'>--dump_targets</code> will not dump to the files
- specified above but to stdout.
-</p>
-
-<h4 id='flag--explain'><code class='flag'>--explain <var>logfile</var></code></h4>
-<p>
- This option, which requires a filename argument, causes the
- dependency checker in <code>bazel build</code>'s execution phase to
- explain, for each build step, either why it is being executed, or
- that it is up-to-date. The explanation is written
- to <i>logfile</i>.
-</p>
-<p>
- If you are encountering unexpected rebuilds, this option can help to
- understand the reason. Add it to your <code>.bazelrc</code> so that
- logging occurs for all subsequent builds, and then inspect the log
- when you see an execution step executed unexpectedly. This option
- may carry a small performance penalty, so you might want to remove
- it when it is no longer needed.
-</p>
-
-<h4 id='flag--verbose_explanations'><code class='flag'>--verbose_explanations</code></h4>
-<p>
- This option increases the verbosity of the explanations generated
- when the <a href='#flag--explain'>--explain</a> option is enabled.
-</p>
-<p>
- In particular, if verbose explanations are enabled,
- and an output file is rebuilt because the command used to
- build it has changed, then the output in the explanation file will
- include the full details of the new command (at least for most
- commands).
-</p>
-<p>
- Using this option may significantly increase the length of the
- generated explanation file and the performance penalty of using
- <code class='flag'>--explain</code>.
-</p>
-<p>
- If <code class='flag'>--explain</code> is not enabled, then
- <code class='flag'>--verbose_explanations</code> has no effect.
-</p>
-
-<h4><code class='flag'>--profile <var>file</var></code></h4>
-<p>
- This option, which takes a filename argument, causes Bazel to write
- profiling data into a file. The data then can be analyzed or parsed using the
- <code>bazel analyze-profile</code> command. The Build profile can be useful in
- understanding where Bazel's <code>build</code> command is spending its time.
-</p>
-
-<h4 id='flag--show_package_location'><code class='flag'>--[no]show_package_location</code></h4>
-<p>
- This option causes Bazel to display, as each package is loaded, the
- directory on the <a href='#flag--package_path'>package path</a> beneath
- which the package's BUILD file was found. This can be useful as a
- diagnostic aid. Nothing is printed if the directory was the Bazel
- workspace (<code>%workspace%</code>). For example:
-</p>
-<pre>
-INFO Loading package: foo/bar/scripts
-INFO Loading package: foo/bar/main
-INFO Loading package: baz from ../$WORKSPACE_READONLY_ROOT
-</pre>
-
-<h4 id='flag--show_loading_progress'><code class='flag'>--[no]show_loading_progress</code></h4>
-<p>
- This option causes Bazel to output package-loading progress
- messages. If it is disabled, the messages won't be shown.
-</p>
-
-<h4><code class='flag'>--[no]show_progress</code></h4>
-<p>
- This option causes progress messages to be displayed; it is on by
- default. When disabled, progress messages are suppressed.
-</p>
-
-<h4><code class='flag'>--show_progress_rate_limit <var>n</var></code></h4>
-<p>
- This option causes Bazel to display only
- one progress message per <code>n</code> seconds. If <code>n</code> is -1,
- all progress messages will be displayed. The default value for this
- option is -1.
-</p>
-
-<h4 id='flag--show_result'><code class='flag'>--show_result <var>n</var></code></h4>
-<p>
- This option controls the printing of result information at the end
- of a <code>bazel build</code> command. By default, if a single
- build target was specified, Bazel prints a message stating whether
- or not the target was successfully brought up-to-date, and if so,
- the list of output files that the target created. If multiple
- targets were specified, result information is not displayed.
-</p>
-<p>
- While the result information may be useful for builds of a single
- target or a few targets, for large builds (e.g. an entire top-level
- project tree), this information can be overwhelming and distracting;
- this option allows it to be controlled. <code class='flag'>--show_result</code>
- takes an integer argument, which is the maximum number of targets
- for which full result information should be printed. By default,
- the value is 1. Above this threshold, no result information is
- shown for individual targets. Thus zero causes the result
- information to be suppressed always, and a very large value causes
- the result to be printed always.
-</p>
-<p>
- Users may wish to choose a value in-between if they regularly
- alternate between building a small group of targets (for example,
- during the compile-edit-test cycle) and a large group of targets
- (for example, when establishing a new workspace or running
- regression tests). In the former case, the result information is
- very useful whereas in the latter case it is less so. As with all
- options, this can be specified implicitly via
- the <a href='#bazelrc'><code>.bazelrc</code></a> file.
-</p>
-<p>
- The files are printed so as to make it easy to copy and paste the
- filename to the shell, to run built executables. The "up-to-date"
- or "failed" messages for each target can be easily parsed by scripts
- which drive a build.
-</p>
-
-<h4 id='flag--show_builder_stats'><code class='flag'>--show_builder_stats</code></h4>
-<p>
- This option will enable parallel builder to output several internal statistics
- after each completed action. Statistic includes following sections:
-</p>
-<pre>
- time since the start of execution phase;
- queue: cumulative number of queued and dequeued actions. At the end of the
- build those two numbers should be equal to the number of actions.
- threads: number of scheduled tasks, number of active threads in the pool,
- number of threads not waiting on resources and number of threads
- executing action payload;
- actions: number of actions waiting on single remaining unbuilt dependency
- before they can get scheduled and number of total actions in the
- build;
- locked: number of threads being blocked by resource (ram, cpu, etc) locks.
-
- >>> [action name]: for actions that are potentially on the critical build path
- (at the time of action completion there were no actions
- awaiting execution).
-</pre>
-<p>
- Examples:
-</p>
-<pre>
- ____13.5 s, queue: 400 / 262, threads: 138 / 20 / 19 / 18, actions: 47 (608), locked: 1
-
- ____22.8 s, queue: 464 / 453, threads: 11 / 11 / 3 / 3, actions: 16 (608), locked: 8 >>> action 'Building foo/bar/Myapp_deploy.jar'
-</pre>
-<p>
- Please, note, that this flag is mostly intended for internal Bazel profiling
- and can change or disappear at any time.
-</p>
-
-<h4 id='flag--subcommands'><code class='flag'>--subcommands</code> (-s)</h4>
-<p>
- This option causes Bazel's execution phase to print the full command line
- for each command prior to executing it.
-</p>
-<p>
- Where possible, commands are printed in a Bourne shell compatible syntax,
- so that they can be easily copied and pasted to a shell command prompt.
- (The surrounding parentheses are provided to protect your shell from the
- <code>cd</code> and <code>exec</code> calls; be sure to copy them!)
- All commands output by <code class='flag'>--subcommands</code>
- are executable by <code>/bin/sh</code> or <code>bash</code>.
-</p>
-<p>
- See also <a href="#--verbose_failures">--verbose_failures</a>, below.
-</p>
-
-<h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4>
-<p>
- This option causes Bazel's execution phase to print the full command line
- for commands that failed. This can be invaluable for debugging a
- failing build.
-</p>
-<p>
- Failing commands are printed in a Bourne shell compatible syntax, suitable
- for copying and pasting to a shell prompt.
-</p>
-
-
-<h3 id='misc_build_options'>Miscellaneous options</h3>
-
-<h4 id='flag--symlink_prefix'><code class='flag'>--symlink_prefix <var>string</var></code></h4>
-<p>
- Changes the prefix of the generated convenience symlinks. The
- default value for the symlink prefix is <code>bazel-</code> which
- will create the symlinks <code>bazel-bin</code>, <code>bazel-testlogs</code>, and
- <code>bazel-genfiles</code>.
-</p>
-<p>
- If the symbolic links cannot be created for any reason, a warning is
- issued but the build is still considered a success. In particular,
- this allows you to build in another user's client, or a read-only
- directory. Any paths printed in informational
- messages at the conclusion of a build will only use the
- symlink-relative short form if the symlinks point to the expected
- location; in other words, you can rely on the correctness of those
- paths, even if you cannot rely on the symlinks being created.
-</p>
-<p>
- Some common values of this option:
-</p>
-<ul>
- <li>
- <p><b>Suppress symlink creation:</b>
- <code class='flag'>--symlink_prefix=/</code> will cause Bazel to not
- create or update any symlinks. Use this option to suppress symlink
- creation entirely.
- </p>
- </li>
- <li>
- <p><b>Reduce clutter:</b>
- <code class='flag'>--symlink_prefix=.bazel/</code> will cause Bazel to create
- symlinks called <code>bin</code> (etc) inside a hidden
- directory <code>.bazel</code>. Some users use this to avoid
- cluttering their bazel directory with files.
- </p>
- </li>
-</ul>
-
-
-<h2 id='test'>Running tests with Bazel</h2>
-<p>
- To build and run tests with Bazel, type <code>bazel test</code> followed by
- the name of the test targets using embedded test runner.
-</p>
-<p>
- By default, this command performs simultaneous build and test
- activity, building all specified targets (including any non-test
- targets specified on the command line) and testing
- <code>*_test</code> and <code>test_suite</code> targets as soon as
- their prerequisites are built, meaning that test execution is
- interleaved with building. Doing so usually results in significant
- speed gains, especially when using a distributed environment.
-</p>
-
-<h3>Options for <code>bazel test</code></h3>
-
-<h4 id="flag--cache_test_results"><code class='flag'>--cache_test_results=(yes|no|auto)</code> (-t)</h4>
-<p>
- If this option is set to yes then Bazel will only rerun a test if any of the
- following conditions apply:
-</p>
-<ul>
- <li>Bazel detects changes in the test or its dependencies</li>
- <li>the test is marked as <code>external</code></li>
- <li>a cached result does not exist or is older than the interval specified by the
- <code class='flag'>--test_result_expiration</code> option.</li>
-</ul>
-<p>
- If 'auto' (the default), the caching behavior will be the same as 'yes' except that
- Bazel will never cache test failures and never cache multiple test runs
- that were requested with <code class='flag'>--runs_per_test</code>.
-</p>
-<p>
- If 'no', all tests will be always executed unconditionally.
-</p>
-<p>
- Note that test results are <em>always</em> saved in Bazel's output tree,
- regardless of whether this option is enabled, so
- you needn't have used <code class='flag'>--cache_test_results</code> on the
- prior run(s) of <code>bazel test</code> in order to get cache hits.
- The option only affects whether Bazel will <em>use</em> previously
- saved results, not whether it will save results of the current run.
-</p>
-<p>
- Users who have enabled this option by default in
- their <code>.bazelrc</code> file may find the
- abbreviations <code>-t</code> (on) or <code>-t-</code> (off)
- convenient for overriding the default on a particular run.
-</p>
-
-
-<h4 id="flag--test_result_expiration"><code class='flag'>--test_result_expiration=<seconds></code></h4>
-<p>
- Specifies interval (in seconds) during which test results from the previous test
- execution will be considered valid. This option is applicable only when used with
- 'yes' or default ('auto') value of the <code class='flag'>--cache_test_results</code> option. Otherwise,
- it is ignored. Setting option to 0 expires cached results immediately and, as such, is
- the same as <code class='flag'>--nocache_test_results</code>. Setting the option to -1 results in
- never expiring the cached result.
-</p>
-
-<h4 id="flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></h4>
-<p>
- This option tells Bazel not to run the tests, but to merely check and report
- the cached test results. If there are any tests which have not been
- previously built and run, or whose tests results are out-of-date (e.g. because
- the source code or the build options have changed), then Bazel will report
- an error message ("test result is not up-to-date"), will record the test's
- status as "NO STATUS" (in red, if color output is enabled), and will return
- a non-zero exit code.
-</p>
-<p>
- This option also implies
- <code><a href="#--check_up_to_date">--check_up_to_date</a></code> behavior.
-</p>
-<p>
- This option may be useful for pre-submit checks.
-</p>
-
-<h4 id="flag--test_verbose_timeout_warnings"><code class='flag'>--test_verbose_timeout_warnings</code></h4>
-<p>
- This option tells Bazel to explicitly warn the user if a test's timeout is
-significantly longer then the test's actual execution time. While a test's
-timeout should be set such that it is not flaky, a test that has a highly
-over-generous timeout can hide real problems that crop up unexpectedly.
-</p>
-<p>
-For instance, a test that normally executes in a minute or two should not have
-a timeout of ETERNAL or LONG as these are much, much too generous. Bazel can generate a warning
-if the stated timeout is much too generous based on the results of the test
-run. This option is useful to help users decide on a good timeout value or
-sanity check existing timeout values.
-</p>
-<p>
-Note that each test shard is allotted the timeout of the entire
-<code>XX_test</code> target. Using this option does not affect a test's timeout
-value, merely warns if Bazel thinks the timeout could be restricted further.
-</p>
-
-<h4 id='flag--test_keep_going'><code class='flag'>--[no]test_keep_going</code></h4>
-<p>
- By default, all tests are run to completion. If this flag is disabled,
- however, the build is aborted on any non-passing test. Subsequent build steps
- and test invocations are not run, and in-flight invocations are canceled.
- Do not specify both <code class='flag'>--notest_keep_going</code> and
- <code class='flag'>--keep_going</code>.
-</p>
-
-<h4 id='flag--flaky_test_attempts'><code class='flag'>--flaky_test_attempts <var>attempts</var></code></h4>
-<p>
- This option specifies the maximum number of times a test should be attempted
- if it fails for any reason. A test that initially fails but eventually
- succeeds is reported as <code>FLAKY</code> on the test summary. It is,
- however, considered to be passed when it comes to identifying Bazel exit code
- or total number of passed tests. Tests that fail all allowed attempts are
- considered to be failed.
-</p>
-<p>
- By default (when this option is not specified, or when it is set to
- "default"), only a single attempt is allowed for regular tests, and
- 3 for test rules with the <code>flaky</code> attribute set. You can specify
- an integer value to override the maximum limit of test attempts. Bazel allows
- a maximum of 10 test attempts in order to prevent abuse of the system.
-</p>
-
-<h4 id='flag--runs_per_test'><code class='flag'>--runs_per_test <var>[regex@]number</var></code></h4>
-<p>
- This option specifies the number of times each test should be executed. All
- test executions are treated as separate tests (e.g. fallback functionality
- will apply to each of them independently).
-</p>
-<p>
- The status of a target with failing runs depends on the value of the
- <code>--runs_per_test_detects_flakes</code> flag:
-</p>
-<ul>
- <li>If absent, any failing run causes the entire test to fail.</li>
- <li>If present and two runs from the same shard return PASS and FAIL, the test
- will receive a status of flaky (unless other failing runs cause it to
- fail).</li>
-</ul>
-
-<p>
- If a single number is specified, all tests will run that many times.
- Alternatively, a regular expression may be specified using the syntax
- regex@number. This constrains the effect of --runs_per_test to targets
- which match the regex (e.g. "--runs_per_test=^//pizza:.*@4" runs all tests
- under //pizza/ 4 times).
- This form of --runs_per_test may be specified more than once.
-</p>
-
-<h4 id='flag--runs_per_test_detects_flakes'><code
- class='flag'>--[no]runs_per_test_detects_flakes</code></h4>
-<p>
- If this option is specified (by default it is not), Bazel will detect flaky
- test shards through --runs_per_test. If one or more runs for a single shard
- fail and one or more runs for the same shard pass, the target will be
- considered flaky with the flag. If unspecified, the target will report a
- failing status.
-</p>
-
-<h4 id='flag--test_summary'><code class='flag'>--test_summary <var>output_style</var></code></h4>
-<p>
- Specifies how the test result summary should be displayed.
-</p>
-<ul>
- <li><code>short</code> prints the results of each test along with the name of
- the file containing the test output if the test failed. This is the default
- value.
- </li>
- <li><code>terse</code> like <code>short</code>, but even shorter: only print
- information about tests which did not pass.
- </li>
- <li><code>detailed</code> prints each individual test case that failed, not
- only each test. The names of test output files are omitted.
- </li>
- <li><code>none</code> does not print test summary.
- </li>
-</ul>
-
-<h4 id='flag--test_output'><code class='flag'>--test_output <var>output_style</var></code></h4>
-<p>
- Specifies how test output should be displayed:
-</p>
-<ul>
- <li><code>summary</code> shows a summary of whether each test passed or
- failed. Also shows the output log file name for failed tests. The summary
- will be printed at the end of the build (during the build, one would see
- just simple progress messages when tests start, pass or fail).
- This is the default behavior.
- </li>
- <li><code>errors</code> sends combined stdout/stderr output from failed tests
- only into the stdout immediately after test is completed, ensuring that
- test output from simultaneous tests is not interleaved with each other.
- Prints a summary at the build as per summary output above.
- </li>
- <li><code>all</code> is similar to <code>errors</code> but prints output for
- all tests, including those which passed.
- </li>
- <li><code>streamed</code> streams stdout/stderr output from each test in
- real-time. This option implies
- <code class='flag'>--test_sharding_strategy=disabled</code>.
- </li>
-</ul>
-
-<h4 id='flag--java_debug'><code class='flag'>--java_debug</code></h4>
-<p>
- This option causes the Java virtual machine of a java test to wait for a connection from a
- JDWP-compliant debugger (such as jdb or Eclipse) before starting the test. This option implies
- --test_output=streamed.
-</p>
-
-<h4 id='flag--verbose_test_summary'><code class='flag'>--[no]verbose_test_summary</code></h4>
-<p>
- By default this option is enabled, causing test times and other additional
- information (such as test attempts) to be printed to the test summary. If
- <code class='flag'>--noverbose_test_summary</code> is specified, test summary will
- include only test name, test status and cached test indicator and will
- be formatted to stay within 80 characters when possible.
-</p>
-
-<h4 id='flag--test_tmpdir'><code class='flag'>--test_tmpdir <var>path</var></code></h4>
-<p>
- Specifies temporary directory for tests executed locally. Each test will be
- executed in a separate subdirectory inside this directory. The directory will
- be cleaned at the beginning of the each <code>bazel test</code> command.
- By default, Bazel will place this directory under Bazel output base directory.
- Note that this is a directory for running tests, not storing test results
- (those are always stored under the <code>bazel-out</code> directory).
-</p>
-
-<h4 id='flag--test_timeout'>
- <code class='flag'>--test_timeout
- <var>seconds</var></code>
- OR
- <code class='flag'>--test_timeout
- <var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var>
- </code>
-</h4>
-<p>
- Overrides the timeout value for all tests by using specified number of
- seconds as a new timeout value. If only one value is provided, then it will
- be used for all test timeout categories.
- </p>
- <p>
- Alternatively, four comma-separated values may be provided, specifying
- individual timeouts for short, moderate, long and eternal tests (in that
- order).
- In either form, zero or a negative value for any of the test sizes will
- be substituted by the default timeout for the given timeout categories.
- By default, Bazel will use Test Encyclopedia timeouts for all tests by
- inferring the timeout limit from the test's size whether the size is
- implicitly or explicitly set.
-</p>
-<p>
- Tests which explicitly state their timeout category as distinct from their
- size will receive the same value as if that timeout had been implicitly set by
- the size tag. So a test of size 'small' which declares a 'long' timeout will
- have the same effective timeout that a 'large' tests has with no explicit
- timeout.
-</p>
-
-<h4 id='flag--test_arg'><code class='flag'>--test_arg <var>arg</var></code></h4>
-<p>
- Passes command-line options/flags/arguments to the test (not to the test runner). This
- option can be used multiple times to pass several arguments, e.g.
- <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>.
-</p>
-
-<h4 id='flag--test_env'><code class='flag'>--test_env <var>variable</var>=<i>value</i></code>
- OR
- <code class='flag'>--test_env <var>variable</var></code></h4>
-<p>
- Specifies additional variables that must be injected into the test
- environment for each test. If <var>value</var> is not specified it will be
- inherited from the shell environment used to start the <code>bazel test</code>
- command.
-</p>
-<p>
- The environment can be accessed from within a test by using
- <code>System.getenv("var")</code> (Java),
-</p>
-
-<h4 id='sharding-strategy'><code class='flag'>--test_sharding_strategy <var>strategy</var>
-</code></h4>
-<p>
- Specifies one of the following strategies to be used for
- test sharding.
- With test sharding, each shard will run as a separate process and will
- execute approximately <code>(1/N)</code>th of the total number of tests
- methods. This can result in significant test latency improvements.
-</p>
-<p>
- The default is <code>explicit</code>.
-</p>
-<ul>
- <li><code>explicit</code> will only use sharding if the
- <code>shard_count</code> BUILD attribute is present.
- </li>
- <li><code>disabled</code> will never shard tests.
- </li>
- <li><code>experimental_heuristic</code> (experimental) will enable sharding
- on distributed tests without an explicit <code>shard_count</code> attribute
- which link in a supported framework. This option is considered experimental
- primarily because there may be false positives: in certain pathological
- circumstances, Bazel might attempt to shard a test that does not speak the
- sharding protocol.
- </li>
-</ul>
-
-<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
-<p>
- This specifies a prefix that the test runner will insert in front
- of the test command before running it. The
- <var>command-prefix</var> is split into words using Bourne shell
- tokenization rules, and then the list of words is prepended to the
- command that will be executed.
-</p>
-<p>
- If the first word is a fully qualified label (i.e. starts with
- <code>//</code>) it is built. Then the label is substituted by the
- corresponding executable location that is prepended to the command
- that will be executed along with the other words.
-<p>
-Some caveats apply:
-</p>
-<ul>
- <li>
- The PATH used for running tests may be different than the PATH in your environment,
- so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code>
- command (the first word in <var>command-prefix</var>).
- </li>
- <li>
- <b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code>
- can't be used for interactive commands.
- </li>
-</ul>
-<p>
-Examples:
-</p>
-<pre>
- --run_under=/usr/bin/valgrind
- --run_under=/usr/bin/strace
- --run_under='/usr/bin/strace -c'
- --run_under='/usr/bin/valgrind --quiet --num-callers=20'
- --run_under=//testing/valgrind:tsan
- --run_under='//testing/valgrind:memcheck --gen-suppressions=all -v'
-</pre>
-
-<h4>Test selection</h4>
-<p>
- As documented under <a href='#output-selection-options'>Output selection options</a>,
- you can filter tests by <a href='#flag--test_size_filters'>size</a>,
- <a href='#flag--test_timeout_filters'>timeout</a>,
- <a href='#flag--test_tag_filters'>tag</a>, or
- <a href='#flag--test_lang_filters'>language</a>. A convenience
- <a href='#flag--test_filter'>general name filter</a> can forward particular
- filter args to the test runner.
-</p>
-
-<h4>Other options for <code>bazel test</code></h4>
-<p>
- The syntax and the remaining options are exactly like
- <a href='#build'>bazel build</a>.
-</p>
-
-<h3 id='tags_keywords'>Test rule <code>tags</code> attribute keywords and other
- common attributes</h3>
-
-<p>
- Bazel modifies test behavior if it finds the following keywords in the
- <code>tags</code> attribute of the test rule:
-</p>
-<ul>
- <li><code>exclusive</code> keyword will force test to be run in the
- "exclusive" mode, ensuring that no other tests are running at the
- same time. Such tests will be executed in serial fashion after all build
- activity and non-exclusive tests have been completed.
- </li>
- <li><code>manual</code> keyword will force test to be ignored by all command
- line wildcards (<code>...</code>, <code>:*</code>, <code>:all</code>, etc).
- It will also be ignored by the <code>test_suite</code> rules that do not
- mention this test explicitly. The only way
- to run such test is to specify it explicitly on the command line.
- </li>
- <li><code>external</code> keyword will force test to be unconditionally
- executed (regardless of <code class='flag'>--cache_test_results</code> value).
- </li>
-</ul>
-<p>
- There are also several other attributes that affect test behavior:
-</p>
-<ul>
- <li>Test rules marked with the <code>flaky=1</code> attribute are considered
- to be flaky and will be automatically retried up to 3 times unless larger
- <code class='flag'>--flaky_test_attempts</code> value has been specified.
- </li>
- <li>Test rules marked with the <code>obsolete=1</code> attribute will be
- ignored by the <code>test_suite</code> rules and by all command line
- wildcards - this behavior is identical to the <code>manual</code> keyword
- described above.
- </li>
-</ul>
-
-
-<h2 id='run'>Running executables with Bazel</h2>
-<p>
- The <code>bazel run</code> command is similar to <code>bazel build</code>, except
- it is used to build and run a single target. Here is a typical session:
-</p>
-<pre>
- % bazel run -- java/myapp:myapp --arg1 --arg2
- Welcome to Bazel
- INFO: Loading package: java/myapp
- INFO: Loading package: foo/bar
- INFO: Loading complete. Analyzing...
- INFO: Building 1 target...
- [0%] Building java/myapp/myapp
- [0%] Creating runfiles directory java/myapp/myapp.runfiles
- ...
- Target //java/myapp:myappp up-to-date:
- bazel-bin/java/myapp:myapp
- INFO: Elapsed time: 5.072s
-
- Hello there
- $EXEC_ROOT/java/myapp/myapp
- --arg1
- --arg2
-</pre>
-
-<p>
- Note the use of the <code>--</code>. This is needed so that Bazel
- does not interpret <code>--arg1</code> and <code>--arg2</code> as
- Bazel options, but rather as part of the command line for running the binary.
-</p>
-
-<h3>Options for <code>bazel run</code></h3>
-
-<h4 id='flag--run_under_run'><code class='flag'>--run_under=<var>command-prefix</var></code></h4>
-<p>
- This has the same effect as the <code class='flag'>--run_under</code> option for
- <code>bazel test</code> (<a href='#flag--run_under'>see above</a>),
- except that it applies to the command being run by <code>bazel
- run</code> rather than to the tests being run by <code>bazel test</code>
- and cannot run under label.
-</p>
-
-
-<h2 id='query'>Querying the dependency graph with Bazel</h2>
-
-<p>
- Bazel includes a query language for asking questions about the
- dependency graph used during the build. The query tool is an
- invaluable aid to many software engineering tasks.
-</p>
-<p>
- The query language is based on the idea of
- algebraic operations over graphs; it is documented in detail
- in <a href='bazel-query-v2.html'>Bazel Query Language, revision
- 2</a>. Please refer to that document for reference, for
- examples, and for query-specific command-line options.
-</p>
-
- <p>
- The query tool accepts several command-line
- option. <code class='flag'>--output</code> selects the output format.
- <code class='flag'>--[no]keep_going</code> (disabled by default) causes the query
- tool to continue to make progress upon errors; this behavior may be
- disabled if an incomplete result is not acceptable in case of errors.
-</p>
-<p>
- The <code class='flag'>--[no]implicit_deps</code> option, enabled by default, causes
- implicit dependencies
- to be included in the dependency graph over which the query operates. An
- implicit dependency is one that is not explicitly specified in the BUILD file
- but added by Bazel.
-</p>
-<p>
- Example: "Show the locations of the definitions (in BUILD files) of
- all genrules required to build all the tests in the ABC tree."
-</p>
-<pre>
- bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
-</pre>
-
-
-<h2 id='misc'>Miscellaneous Bazel commands and options</h2>
-
-<h3 id='help'>The <code>help</code> command</h3>
-
-<p>
- The <code>help</code> command provides on-line help. By default, it
- shows a summary of available commands and help topics, as shown in
- the <a href='#concepts'><i>Bazel Concepts</i></a> section above.
- Specifying an argument displays detailed help for a particular
- topic. Most topics are Bazel commands, e.g. <code>build</code>
- or <code>query</code>, but there are some additional help topics
- that do not correspond to commands.
-</p>
-
-<h4><code class='flag'>--[no]long</code> (-l)</h4>
-<p>
- By default, <code>bazel help [<var>topic</var>]</code> prints only a
- summary of the relevant options for a topic. If
- the <code class='flag'>--long</code> option is specified, the type, default value
- and full description of each option is also printed.
-</p>
-
-<h3 id='shutdown'>The <code>shutdown</code> command</h3>
-
-<p>
- Bazel server processes (see <a href='#client/server'>Client/server
- implementation</a>) may be stopped by using the <code>shutdown</code>
- command. This command causes the Bazel server to exit as soon as it
- becomes idle (i.e. after the completion of any builds or other
- commands that are currently in progress).
-
- Bazel servers stop themselves after an idle timeout, so this command
- is rarely necessary; however, it can be useful in scripts when it is
- known that no further builds will occur in a given workspace.
-</p>
-<p>
- <code>shutdown</code> accepts one
- option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which
- requires an integer argument. If specified, this makes the shutdown
- conditional on the amount of memory already consumed. This is
- useful for scripts that initiate a lot of builds, as any memory
- leaks in the Bazel server could cause it to crash spuriously on
- occasion; performing a conditional restart preempts this condition.
-</p>
-
-<h3 id='info'>The <code>info</code> command</h3>
-
-<p>
- The <code>info</code> command prints various values associated with
- the Bazel server instance, or with a specific build configuration.
- (These may be used by scripts that drive a build.)
-</p>
-
-<p>
- The <code>info</code> command also permits a single (optional)
- argument, which is the name of one of the keys in the list below.
- In this case, <code>bazel info <var>key</var></code> will print only
- the value for that one key. (This is especially convenient when
- scripting Bazel, as it avoids the need to pipe the result
- through <code>sed -ne /key:/s/key://p</code>:
-</p>
-
-<h4>Configuration-independent data</h4>
-<ul>
- <li><code>release</code>: the release label for this Bazel
- instance, or "development version" if this is not a released
- binary.
- </li>
- <li><code>workspace</code> the absolute path to this Baze;
- workspace.
- </li>
- <li><code>install_base</code>: the absolute path to the installation
- directory used by this Bazel instance for the current user. Bazel
- installs its internally required executables below this directory.
- </li>
- <li><code>output_base</code>: the absolute path to the base output
- directory used by this Bazel instance for the current user and
- workspace combination. Bazel puts all of its scratch and build
- output below this directory.
- </li>
- <li><code>execution_root</code>: the absolute path to the execution
- root directory under output_base. This directory is the root for all files
- accessible to commands executed during the build, and is the working
- directory for those commands. If the workspace directory is writable, a
- symlink is placed there pointing to this
- directory.
- </li>
- <li><code>output_path</code>: the absolute path to the output
- directory beneath the execution root used for all files actually
- generated as a result of build commands. If the workspace directory is
- writable, a symlink named <code>bazel-out</code> is placed there pointing
- to this directory.
- </li>
- <li><code>server_pid</code>: the process ID of the Bazel server
- process. </li>
- <li><code>command_log</code>: the absolute path to the command log file;
- this contains the interleaved stdout and stderr streams of the most recent
- Bazel command. Note that running <code>bazel info</code> will overwrite the
- contents of this file, since it then becomes the most recent Bazel command.
- However, the location of the command log file will not change unless you
- change the setting of the <code class='flag'>--output_base</code> or
- <code class='flag'>--output_user_root</code> options.
- </li>
- <li><code>server_log</code>: the absolute path to the Bazel server's
- log file; this contains useful information for debugging Bazel.
- </li>
- <li><code>used-heap-size</code>,
- <code>committed-size</code>,
- <code>max-heap-size</code>: reports various JVM heap size
- parameters. Respectively: memory currently used, memory currently
- guaranteed to be available to the JVM from the system, maximum
- possible allocation.
- </li>
- <li><code>gc-count</code>, <code>gc-time</code>: The cumulative count of
- garbage collections since the start of this Bazel server and the time spent
- to perform them. Note that these values are not reset at the start of every
- build.
- </li>
- <li><code>package_path</code>: A colon-separated list of paths which would be
- searched for packages by Bazel. Has the same format as the
- <code class='flag'>--package_path</code> build command line argument.
- </li>
-</ul>
-<p>
- Example: the process ID of the Bazel server.
-</p>
-<pre>% bazel info server_pid
-1285
-</pre>
-
-<h4>Configuration-specific data</h4>
-<p>
- These data may be affected by the configuration options passed
- to <code>bazel info</code>, for
- example <code class='flag'>--define</code>.
- The <code>info</code> command accepts all
- the <a href='#analysis-options'>options that control dependency
- analysis</a>, since some of these determine the location of the
- output directory of a build, the choice of compiler, etc.
-</p>
-<ul>
- <li>
- <code>bazel-bin</code>, <code>bazel-testlogs</code>,
- <code>bazel-genfiles</code>: reports the absolute path to
- the <code>bazel-*</code> directories in which programs generated by the
- build are located. This is usually, though not always, the same as
- the <code>bazel-*</code> symlinks created in the bazel workspace after a
- successful build. However, if the workspace directory is read-only,
- no <code>bazel-*</code> symlinks can be created. Scripts that use
- the value reported by <code>bazel info</code>, instead of assuming the
- existence of the symlink, will be more robust.
- </li>
- <li>
- The complete
- <a href='build-encyclopedia.html#make_variables'
- >"Make" environment</a>. If the <code class='flag'>--show_make_env</code> flag is
- specified, all variables in the current configuration's "Make" environment
- are also displayed (e.g. <code>JAVABASE</code>).
- These are the variables accessed using the <code>$(JAVABASE)</code>
- or <code>varref("JAVABASE")</code> syntax inside BUILD files.
- </li>
-</ul>
-
-
-<h3 id='version'>The <code>version</code> command</h3>
-
-<p>
- The version command prints version details about the built Bazel
- binary, including the changelist at which it was built and the date.
- These are particularly useful in determining if you have the latest
- Bazel. Some of the interesting values are:
-</p>
-<ul>
- <li><code>label</code>: the release label for this Bazel
- instance, or "development version" if this is not a released
- binary.
- </li>
-</ul>
-
-
-<h3 id='analyze-profile'>The <code>analyze-profile</code> command</h3>
-
-<p>
- The <code>analyze-profile</code> command analyzes data previously gathered
- during the build using <code class='flag'>--profile</code> option. It provides several
- options to either perform analysis of the build execution or export data in
- the specified format.
-</p>
-
-<h3 id='canonicalize'>The <code>canonicalize-flags</code> command</h3>
-
-<p>
- The <code>canonicalize-flags</code> command, which takes a list of options for
- a Bazel command and returns a list of options that has the same effect. The
- new list of options is canonical, i.e., two lists of options with the same
- effect are canonicalized to the same new list.
-</p>
-<p>
- The <code class='flag'>--for_command</code> option can be used to select between different
- commands. At this time, only <code>build</code> and <code>test</code> are
- supported. Options that the given command does not support cause an error.
-</p>
-<p>
- Note that a small number of options cannot be reordered, because Bazel cannot
- ensure that the effect is identical.
-</p>
-
-<h3 id='startup_options'>Bazel startup options</h3>
-
-<p>
- The options described in this section affect the startup of the Java
- virtual machine used by Bazel server process, and they apply to all
- subsequent commands handled by that server. If there is an already
- running Bazel server and the startup options do not match, it will
- be restarted.
-</p>
-<p>
- All of the options described in this section must be specified using the
- <code class='flag'>--key=value</code> or <code class='flag'>--key value</code>
- syntax. Also, these options must appear <i>before</i> the name of the Bazel
- command.
-</p>
-
-<h4><code class='flag'>--output_base=<var>dir</var></code></h4>
-<p>
- This option requires a path argument, which must specify a
- writable directory. Bazel will use this location to write all its
- output. The output base is also the key by which the client locates
- the Bazel server. By changing the output base, you change the server
- which will handle the command.
-</p>
-<p>
- By default, the output base is derived from the user's login name,
- and the name of the workspace directory (actually, its MD5 digest),
- so a typical value looks
- like: <code>/usr/local/_bazel_myname/d41d8cd98f00b204e9800998ecf8427e</code>.
- Note that the client uses the output base to find the Bazel server
- instance, so if you specify a different output base in a Bazel
- command, a different server will be found (or started) to handle the
- request. It's possible to perform two concurrent builds in the same
- bazel workspace by varying the output base:
-</p>
-<pre>
- % bazel --output_base /tmp/1 build //foo & bazel --output_base /tmp/2 build //bar
-</pre>
-<p>
- In this command, the two Bazel commands run concurrently (because of
- the shell <code>&</code> operator), each using a different Bazel
- server instance (because of the different output bases).
- In contrast, if the default output base was used in both commands,
- then both requests would be sent to the same server, which would
- handle them sequentially: a <code>foo</code> build first, followed
- by an incremental build of <code>bar</code>.
-</p>
-<p>
- We recommend you do not use NFS locations for the output base, as
- the higher access latency of NFS will cause noticeably slower
- builds. Also, this places unnecessary loads on the NFS filers.
-</p>
-
-<h4><code class='flag'>--output_user_root=<var>dir</var></code></h4>
-<p>
- By default, the <code>output_base</code> value is chosen to as to
- avoid conflicts between multiple users building in the same client.
- In some situations, though, it is desirable to build from a client
- shared between multiple users; release engineers may do this. In
- those cases it may be useful to deliberately override the default so
- as to ensure "conflicts" (i.e., sharing) between multiple users.
- Use the <code class='flag'>--output_user_root</code> option to achieve this: the
- output base is placed in a subdirectory of the output user root,
- with a unique name based on the workspace, so the result of using an
- output user root that is not a function of <code>$USER</code> is
- sharing. Of course, it is important to ensure (via umask and group
- membership) that all the cooperating users can read/write each
- others files.
-</p>
-<p>
- If the <code class='flag'>--output_base</code> option is specified, it overrides
- using <code class='flag'>--output_user_root</code> to calculate the output base.
-</p>
-<p>
- The install base location is also calculated based on
- <code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded
- binaries.
-</p>
-<p>
- You can also use the <code class='flag'>--output_user_root</code> option to choose an
- alternate base location for all of Bazel's output (install base and output
- base) if there is a better location in your filesystem layout.
-</p>
-
-<h4><code class='flag'>--host_jvm_args=<var>string</var></code></h4>
-<p>
- Specifies a space-separated list of startup options to be passed to
- the Java virtual machine in which <i>Bazel itself</i> runs. This
- can be used to set the stack size, for example:
-</p>
-<pre>
- % bazel --host_jvm_args="-Xss256K" build //base
-</pre>
-<p>
- This option can be used multiple times with individual arguments. Note that
- setting this flag should rarely be needed. Default heap size values passed
- to the JVM from Bazel are set aggressively in both the 32-bit and 64-bit
- case (<code>3000MB</code> and <code>10GB</code>, respectively).
-</p>
-<p>
- (Please note that this does <i>not</i> affect any JVMs used by
- subprocesses of Bazel: applications, tests, tools, etc. To pass
- JVM options to executable Java programs, whether run by <code>bazel
- run</code> or on the command-line, you should use
- the <code>--jvm_flags</code> argument which
- all <code>java_binary</code> and <code>java_test</code> programs
- support. Alternatively for tests, use <code>bazel
- test --test_arg=--jvm_flags=foo ...</code>.)
-</p>
-
-<h4><code class='flag'>--host_jvm_debug</code></h4>
-<p>
- This option causes the Java virtual machine to wait for a connection
- from a JDWP-compliant debugger (such as jdb or Eclipse) before
- calling the main method of <i>Bazel itself</i>. This is primarily
- intended for use by Bazel developers.
-</p>
-<p>
- (Please note that this does <i>not</i> affect any JVMs used by
- subprocesses of Bazel: applications, tests, tools, etc.)
-</p>
-
-<h4 id='batch'><code class='flag'>--batch</code></h4>
-<p>
- This switch will cause Bazel to be run in batch mode, instead of the
- standard client/server mode described <a href='#client/server'>above</a>.
- Doing so provides more predictable semantics with respect to signal handling,
- job control, and environment variable inheritance.
-</p>
-
-<p>
- Batch mode retains proper queueing semantics within the same output_base.
- That is, simultaneous invocations will be processed in order, without overlap.
- If a batch mode Bazel is run on a client with a running server, it first
- kills the server before processing the command.
-</p>
-
-<p>
- Bazel will run slower in batch mode, compared to client/server mode.
- Among other things, the build file cache is memory-resident, so it is not
- preserved between sequential batch invocations.
- Therefore, using batch mode often makes more sense in cases where performance
- is less critical, such as continuous builds.
-</p>
-
-<h4><code class='flag'>--max_idle_secs <var>n</var></code></h4>
-<p>
- This option specifies how long, in seconds, the Bazel server process
- should wait after the last client request, before it exits. The
- default value is 10800 (3 hours).
-</p>
-<p>
- This option may be used by scripts that invoke Bazel to ensure that
- they do not leave Bazel server processes on a user's machine when they
- would not be running otherwise.
- For example, an automated script might wish to
- invoke <code>bazel query</code> to ensure that a user's pending
- change does not introduce unwanted dependencies. However, if the
- user has not done a recent build in that workspace, it would be
- undesirable for the script to start a Bazel server just
- for it to remain idle for the rest of the day.
- By specifying a small value of <code class='flag'>--max_idle_secs</code> in the
- query request, the script can ensure that <i>if</i> it caused a new
- server to start, that server will exit promptly, but if instead
- there was already a server running, that server will continue to run
- until it has been idle for the usual time. Of course, the existing
- server's idle timer will be reset.
-</p>
-
-<h4><code class='flag'>--[no]block_for_lock</code></h4>
-<p>
- If enabled, Bazel will wait for other Bazel commands holding the
- server lock to complete before progressing. If disabled, Bazel will
- exit in error if it cannot immediately acquire the lock and
- proceed.
-
- Developers might use this to avoid long waits caused
- by another Bazel command in the same client.
-</p>
-
-<h4><code class='flag'>--io_nice_level <var>n</var></code></h4>
-<p>
- Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority,
- 7 is lowest. The anticipatory scheduler may only honor up to priority 4.
- Negative values are ignored.
-</p>
-
-<h4><code class='flag'>--batch_cpu_scheduling</code></h4>
-<p>
- Use <code>batch</code> CPU scheduling for Bazel. This policy is useful for
- workloads that are non-interactive, but do not want to lower their nice value.
- See 'man 2 sched_setscheduler'. This policy may provide for better system
- interactivity at the expense of Bazel throughput.
-</p>
-
-<h3 id='misc_options'>Miscellaneous options</h3>
-
-<h4 id='flag--announce_rc'><code class='flag'>--[no]announce_rc</code></h4>
-<p>
- Controls whether Bazel announces the options read from the bazelrc file when
- starting up.
-</p>
-
-<h4><code class='flag'>--color (yes|no|auto)</code></h4>
-<p>
- This option determines whether Bazel will use colors to highlight
- its output on the screen.
-</p>
-<p>
- If this option is set to <code>yes</code>, color output is enabled.
- If this option is set to <code>auto</code>, Bazel will use color output only if
- the output is being sent to a terminal and the TERM environment variable
- is set to a value other than <code>dumb</code>, <code>emacs</code>, or <code>xterm-mono</code>.
- If this option is set to <code>no</code>, color output is disabled,
- regardless of whether the output is going to a terminal and regardless
- of the setting of the TERM environment variable.
-</p>
-
-<h4 id='flag--config'><code class='flag'>--config <var>name</var></code></h4>
-<p>
- Selects additional config sections from the rc files; for the current
- <code>command</code>, it also pulls in the options from
- <code>command:name</code> if such a section exists. Note that it is currently
- only possible to provide these options on the command line, not in the rc
- files.
-</p>
-
-<h4><code class='flag'>--curses (yes|no|auto)</code></h4>
-<p>
- This option determines whether Bazel will use cursor controls
- in its screen output. This results in less scrolling data, and a more
- compact, easy-to-read stream of output from Bazel. This works well with
- <code class='flag'>--color</code>.
-</p>
-<p>
- If this option is set to <code>yes</code>, use of cursor controls is enabled.
- If this option is set to <code>no</code>, use of cursor controls is disabled.
- If this option is set to <code>auto</code>, use of cursor controls will be
- enabled under the same conditions as for <code class='flag'>--color=auto</code>.
-</p>
-
-<h4><code class='flag'>--logging <var>n</var></code></h4>
-<p>
- This option controls the level of logging output produced by Bazel.
- The default level of logging is 3 (INFO log level); higher numbers mean more
- output. The most detailed output is produced at level = 6. A value of 0 turns
- logging off.
-</p>
-<p>
- Note, the logging output is highly technical and not intended for
- consumption by Bazel users. Instead, we recommend using one
- of the following more user-friendly options to control the
- diagnostic information printed by Bazel.
-</p>
-<ul>
- <li>For understanding the dependency graph,
- use <a href='#query'><code>bazel query</code></a>.
- </li>
- <li>To see the full command line for commands that failed,
- use <a href='#flag--verbose_failures'><code class='flag'>--verbose_failures</code></a>.
- </li>
- <li>For monitoring all executed commands,
- use <a href='#flag--subcommands'><code class='flag'>--subcommands</code></a>.
- </li>
- <li>To understand why a particular step was rebuilt,
- use <a href='#flag--explain'><code class='flag'>--explain</code></a>.
- </li>
- <li>For profiling a build,
- use <a href='#flag--profile'><code class='flag'>--profile</code></a>.
- </li>
- <li>To disable progress messages,
- use <a href='#flag--show_progress'><code class='flag'>--noshow_progress</code></a>.
- </li>
- <li>To control the display of build result information,
- use <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a>.
- </li>
- <li>To prefix all log messages with a timestamp,
- use <a href='#flag--show_timestamps'><code class='flag'>--show_timestamps</code></a>.
- </li>
- <li>To show where each BUILD file is loaded from,
- use <a href='#flag--show_package_location'><code class='flag'>--show_package_location</code></a>.
- </li>
-</ul>
-
-<h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4>
-<p>
- If specified, a timestamp is added to each message generated by
- Bazel specifying the time at which the message was displayed.
-</p>
-
-
-<h2 id='scripting'>Calling Bazel from scripts</h2>
-
-<p>
- Bazel can be called from scripts in order to perform a build, run
- tests or query the dependency graph. Bazel has been designed to
- enable effective scripting, but this section lists some details to
- bear in mind to make your scripts more robust.
-</p>
-
-
-<h3>Choosing the output base</h3>
-
-<p>
- The <code class='flag'>--output_base</code> option controls where the Bazel process should
- write the outputs of a build to, as well as various working files used
- internally by Bazel, one of which is a lock that guards against
- concurrent mutation of the output base by multiple Bazel processes.
-</p>
-<p>
- Choosing the correct output base directory for your script depends
- on several factors. If you need to put the build outputs in a
- specific location, this will dictate the output base you need to
- use. If you are making a "read only" call to Bazel
- (e.g. <code>bazel query</code>), the locking factors will be more important.
- In particular, if you need to run multiple instances of your script
- concurrently, you will need to give each one a different (or random) output
- base.
-</p>
-<p>
- If you use the default output base value, you will be contending for
- the same lock used by the user's interactive Bazel commands. If the
- user issues long-running commands such as builds, your script will
- have to wait for those commands to complete before it can continue.
-</p>
-
-<h3>Server or no server?</h3>
-
-<p>
- By default, Bazel uses a long-running <a
- href='#client/server'>server process</a> as an optimization; this
- behavior can be disabled using the <a
- href='#batch'><code class='flag'>--batch</code></a> option. There's no hard and
- fast rule about whether or not your script should use a server, but
- in general, the trade-off is between performance and reliability.
- The server mode makes a sequence of builds, especially incremental
- builds, faster, but its behavior is more complex and prone to
- failure. We recommend in most cases that you use batch mode unless
- the performance advantage is critical.
-</p>
-<p>
- If you do use the server, don't forget to call <code>shutdown</code>
- when you're finished with it, or, specify
- <code class='flag'>--max_idle_secs=5</code> so that idle servers shut themselves
- down promptly.
-</p>
-
-<h3>What exit code will I get?</h3>
-
-<p>
- Bazel attempts to differentiate failures due to the source code under
-consideration from external errors that prevent Bazel from executing properly.
-Bazel execution can result in following exit codes:
-</p>
-
-<b>Exit Codes common to all commands:</b>
-<ul>
- <li><code>0</code> - Success</li>
- <li><code>2</code> - Command Line Problem, Bad or Illegal flags or command
- combination, or Bad Environment Variables. Your command line must be
- modified.</li>
- <li><code>8</code> - Build Interrupted but we terminated with an orderly shutdown.</li>
- <li><code>33</code> - OOM failure. You need to modify your command line.</li>
- <li><code>36</code> - Local Environmental Issue, suspected permanent.</li>
- <li><code>37</code> - Unhandled Exception / Internal Bazel Error.</li>
- <li><code>40-44</code> - Reserved for errors in Bazel's command line launcher,
- <code>bazel.cc</code> that are not command line
- related. Typically these are related to Bazel server
- being unable to launch itself.</li>
-</ul>
-
-<b>Return codes for commands <code>bazel build</code>, <code>bazel test</code>.</b>
-<ul>
- <li><code>1</code> - Build failed.</li>
- <li><code>3</code> - Build OK, but some tests failed or timed out.</li>
- <li><code>4</code> - Build successful but no tests were found even though
- testing was requested.</li>
-</ul>
-
-
-<b>For <code>bazel run</code>:</b>
-<ul>
- <li><code>1</code> - Build failed.</li>
- <li><code>6</code> - Run command failure. The executed subprocess returned a
- non-zero exit code. The actual subprocess exit code is
- given in stderr.</li>
-</ul>
-
-
-<b>For <code>bazel query</code>:</b>
-<ul>
- <li><code>3</code> - Partial success, but the query encountered 1 or more
- errors in the input BUILD file set and therefore the
- results of the operation are not 100% reliable.
- This is likely due to a <code class='flag'>--keep_going</code> option
- on the command line.
- <li><code>7</code> - Analyze or Query command failure.</li>
-</ul>
-
-<p>
- Future Bazel versions may add additional exit codes, replacing generic failure
- exit code <code>1</code> with a different non-zero value with a particular
- meaning. However, all non-zero exit values will always constitute an error.
-</p>
-
-<h3>Reading the .bazelrc file</h3>
-
-<p>
- By default, Bazel will read the <a
- href='#bazelrc'><code>.bazelrc</code> file</a> from the workspace
- directory or the user's home directory. Whether or not this is
- desirable is a choice for your script; if your script needs to be
- perfectly hermetic (e.g. when doing release builds), you should
- disable reading the .bazelrc file by using the option
- <code class='flag'>--bazelrc=/dev/null</code>. If you want to perform a build
- using the user's preferred settings, the default behavior is better.
-</p>
-
-<h3 id='master_log'>Using the Bazel master log</h3>
-
-<p>
- On each build, test, analyze, or coverage command, Bazel will
- write a readily-parseable summary log. The output is in the form of
- a line-based grammar, familiar to standard unix tools (grep, sed,
- sort, awk, etc.).
-</p>
-
-<p>
- The master log contains information on the result of each target
- and test. You'll be able to determine, for instance, if a given target
- passed the loading phase, but not the analysis phase. We also
- provide references to test log files and test time information.
- You can find the master log file with the following command:
-</p>
-
-<pre>
-% bazel info master-log
-</pre>
-
-<p>
- Say you were interested in seeing the three longest-running tests
- in your most recent test command. Here's how you could do it:
-</p>
-
-<pre>
-% grep '^test ' $(bazel info master-log 2>/dev/null) | awk '{print $5,$2}' | sort -nr | head -n 3
-2404 //foo:foo_test
-713 //bar:bar_test
-624 //baz:baz_test
-</pre>
-
-<h4>Master log format</h4>
-
-<p>
- Line ordering is generally unspecified (exceptions are handled on a
- case-by-case basis), but the file will contain the following contents:
-</p>
-
-<ul>
-<li>
- <code>startup_options</code><br/>
- The line contains a properly quoted representation of the startup options
- used to start Bazel, including <code>.bazelrc</code> options.
-</li>
-
-<li>
- <code>cmd_line</code><br/>
- The line contains a properly quoted representation of the user's command
- line arguments. This includes <code>.bazelrc</code> options, but not the
- startup options, command, or target patterns specified on the command line.
-</li>
-
-<li>
- <code>build_id <var>uuid</var></code><br/>
- <var>uuid</var> is a string uniquely identifying this build.
- The identifier is guaranteed to be unique across any other Bazel build,
- even those of other users.
-</li>
-
-<li>
- <code>version_num <var>number</var></code><br/>
- <var>number</var> is the version number of the master log.
- Incompatible changes may be made to the master log
- only if <var>number</var> is increased.
-</li>
-
-<li>
- <code>pattern <var>pattern</var> ...</code><br/>
- A single line with a space-separated list of target patterns as they
- appeared on the command line. e.g., for <code>bazel build foo //bar:*</code>,
- the line would read: <code>pattern foo //bar:*</code>.
-</li>
-
-<li>
- <code>command <var>command_name</var></code><br/>
- <var>command_name</var> is the name of the command executed by Bazel. (e.g., build or test).
-</li>
-
-<li>
- <code>bazel_version <var>version string</var></code><br/>
- <var>version string</var> is a human readable version descriptor indicating the Bazel version
- used for the build.
-</li>
-
-<li>
- <code>log_starting <var>log_name</var> <var>log_path</var></code><br/>
- <var>log_name</var> is the name of the log being started.<br/>
- <var>log_path</var> is the absolute path to the log file.
-</li>
-
-<li>
- <code>start_time <var>time</var></code><br/>
- <var>time</var> is the start time of the build, in milliseconds since
- midnight, January 1, 1970 UTC.
-</li>
-
-<li>
- <code>stop_time <var>time</var></code><br/>
- <var>time</var> is the end time of the build, in milliseconds since
- midnight, January 1, 1970 UTC.
-</li>
-
-<li>
- <code>output_fs <var>filesystem_type</var></code><br/>
- <var>filesystem_type</var> is the type of the filesystem that contains the Bazel output
- directory (does not contain spaces).
-</li>
-
-<li>
- <code>runs_per_test <var>runs</var></code><br/>
- <var>runs</var> is the number of test runs Bazel is configured to perform on
- each test target.
-</li>
-
-<li>
- <code>working_directory <var>cwd</var></code><br/>
- <var>cwd</var> is the working directory from which Bazel was invoked.
-</li>
-
-<li>
- <code>symlink_prefix <var>string</var></code><br/>
- <var>string</var> is the value of the <code class='flag'>--symlink_prefix</code> flag.
- See <a href="#flag--symlink_prefix"><code class='flag'>--symlink_prefix</code></a>.
-</li>
-
-<li>
- <code>target <var>label</var> <var>kind</var></code><br/>
- One line for each target the that was parsed from the command line.
- e.g.,
-<pre>
- target //foo:foo java_library rule
- target //bar:t1 source file
- target //bar:t2 generated file
-</pre>
- If a <code>test_suite</code> target is specified in the pattern, just one
- <code>target</code> line will appear for it, but no <code>target</code> lines
- will appear for the test targets it expands to. If the test targets build
- successfully, you can use the
- <code>test_target</code> lines to determine target language.
-</li>
-
-<li>
- <code>test_target <var>label</var> <var>kind</var> <var>shards</var></code>
- <br/><var>label</var> is the label identifying the target.
- <br/><var>kind</var> is the type of rule the target tests as (e.g. java_test).
- <br/><var>shards</var> is the number of shards the test is configured to use.
- <p>One line for each test target that Bazel will attempt to execute.
- These targets have been successfully loaded, analyzed, and have not been
- filtered via <a href='#flag--test_size_filters'>size</a>,
- <a href='#flag--test_timeout_filters'>timeout</a>,
- <a href='#flag--test_tag_filters'>tag</a>, or
- <a href='#flag--test_lang_filters'>language</a>. Note that these tests may not
- be executed if the execution phase is not entered, is interrupted, or fails.
- These lines will appear before any <code>status</code>,
- <code>test</code>, <code>test_status</code> lines.
- If a <code>test_suite</code> target is specified in the pattern, a
- <code>test_target</code> line will appear for each test target it expands to.
- </p>
-</li>
-
-<li>
- <code>make_var <var>key</var> <var>value</var></code><br/>
- One line with a key value pair for each
- <a href="build-encyclopedia.html#make_variables">make variable</a>.
- <p>Available make variables may be displayed with:</p>
-<pre>
- bazel info --show_make_env
-</pre>
-</li>
-
-<li id="status_line">
- <code>
- <a name="status">status</a> <var>label</var> <var>result</var>
- <var>time</var> <var>cached</var>
- </code>
- <br/>
- <var>label</var> is the name of the target for which status is reported.<br/>
- <var>result</var> is the status of the target; see below for values.<br/>
- <var>time</var> is the time of target completion, in milliseconds since
- midnight, January 1, 1970 UTC.
- <var>cached</var> is "cached" only if the entire target is cached;
- i.e. all artifacts required to run the target were cached from a previous
- build <em>of the same target</em>. Otherwise, it is "not_cached".
- <p>
- One status line for each <code>target</code> line. In the
- <code class='flag'>--keep_going</code> case, different targets may reach
- different phases (e.g. loading vs. analysis) before failing.
- However, in the default case, all <var>result</var> values will be
- identical, because the build stops as soon as the first error is
- encountered. This line strictly reports build statuses; for test status
- reporting, see <a href="#test_status"><code>test_status</code></a>.
- </p>
- <p>
- <var>result</var> may be one of:
- </p>
- <ul>
- <li><code>parsing-failed</code>: the target could not be parsed (due to the
- architecture of Bazel, this is sometimes also emitted when the target
- simply does not exist). Also see
- <a href="#parsing_failed">parsing_failed</a></li>
- <li><code>target-filtered</code>: the target got filtered out by a negative
- target specifier that came later in the command line.</li>
- <li><code>loading-failed</code>: the target contained
- a <a href='#loading-phase'>loading phase</a> error.</li>
- <li><code>analysis-failed</code>: the target contained
- an <a href='#analysis-phase'>analysis phase</a> error.</li>
- <li><code>test-filtered</code>: the target was loaded and analyzed
- successfully, but was not built or run because it did not match the
- current
- <a href='#flag--test_size_filters'>size</a>,
- <a href='#flag--test_timeout_filters'>timeout</a>,
- <a href='#flag--test_tag_filters'>tag</a>, or
- <a href='#flag--test_lang_filters'>language</a> test
- filter settings.</li>
- <li><code>not-built</code>: the target was loaded and analyzed successfully,
- but was not built or run because Bazel did not perform the
- <a href="#execution-phase">execution phase</a>;
- e.g. if the <a href="#nobuild">--nobuild</a> flag was specified.</li>
- <li><code>build-failed</code>: the target could not be built
- because of an error during
- the <a href='#execution-phase'>execution phase</a>.</li>
- <li><code>built</code>: the target was built successfully.</li>
- </ul>
- These lines are not guaranteed to be printed in the case of a Bazel crash.
-</li>
-
-<li>
- <code>action_executed <var>target</var> <var>type</var> <var>outcome</var>
- <var>stdout</var> <var>stderr</var> <var>primary_input</var>
- <var>primary_output</var></code><br/>
- One such line is generated for every action with stdout/stderr that Bazel executed.<br/>
- <var>target</var>: The target the action was associated with, or
- <code><none></code> if the action does not belong to any target.<br/>
- <var>type</var>: The type of the action. This is intended to be a clue as to
- how the output of the action should be parsed. It does not precisely
- determine the compiler that was executed;
- <var>outcome</var>: <code>success</code> or <code>failure</code> depending
- on whether the action succeeded or failed.<br/>
- <var>stdout</var>: the file containing the standard output of the action.
- <code>/dev/null</code> if the action did not write anything there.<br/>
- <var>stderr</var>: the file containing the standard error of the action.
- <code>/dev/null</code> if the action did not write anything there.<br/>
- <var>primary_input</var>: the "primary" input artifact processed by this
- action.
- <code>null</code> if the action has no input artifacts.<br/>
- <var>primary_output</var>: the "primary" output artifact processed by this
- action.
- <code>null</code> if the action has no output artifacts.<br/>
-</li>
-
-<li>
- <code>
- <a name="root_cause">root_cause</a> <var>target</var> <var>cause</var>
- </code>
- <br/>
-
- When a target is not built, and Bazel has information about the reason,
- a <code>root_cause</code> line is added. Such a line means that the
- reason why <var>target</var> could not be built is that there was a
- problem with building one of its dependencies, <var>cause</var>. Note
- that there can be multiple <code>root_cause</code> lines for a single
- target when that target has multiple faulty dependencies which do not
- depend on each other. Also note that a target can be its own root cause.
- Root cause lines are most meaningful in the presence of --keep_going; in
- builds lacking -k, only the first failing target will report root causes
- (and because actions are executed in parallel, which target fails first is
- not deterministic).
-</li>
-<li>
- <code>bazel_crashed <var>description</var></code><br/>
- This line is included if the build crashed unexpectedly. This could happen,
- for example, in the case of an <code>OutOfMemoryError</code>.
-</li>
-<li>
- <code>bazel_catastrophe</code><br/>
- This line is included if there is a severe enough failure such that Bazel halts the build before
- completion, even if <code>keep_going</code> is set. One example of this is unexpected IO failure
- when writing to local disk, whether due to physical failure or filesystem corruption.
-</li>
-
-<li id="parsing_failed">
- <code>parsing_failed <var>pattern</var> “<var>description</var>”
- </code><br/>
- In the event that a user-supplied target pattern cannot be parsed, this line
- will be emitted with the failing target pattern and a description of the error
- (surrounded by double quotes). Certain error types (those which occur after
- targets are parsed from the pattern) will emit corresponding
- <a href="#status_line">status //target parsing-failed</a> lines; others will
- not. If multiple target patterns are specified on the command
- line, one parsing_failed line will be emitted for each failing pattern.
-</li>
-
-<li>
- <code>output_file <var>label</var> <var>path</var> <var>tags</var></code><br/>
- One output file line for each non-input file built for each
- successfully built target. The <var>tags</var>
- value is a comma separated and terminated sequence of strings.
- Currently, the only possible value is <code>executable</code>, which is
- printed if and only if the file is the target's executable
- output. Each target may have at most one executable.
-</li>
-
-<li id="test_line">
- <code>test <var>label</var>
- <var>shard_num</var>/<var>total_shards</var> <var>result</var> <var>time</var>
- <var>log_file</var></code><br/>
-
- One test line for <em>each run of each shard</em> of a successfully-built
- test target. For the aggregate status of the entire target, see
- <a href="#test_status"><code>test_status</code></a>.
-
- <p>Multiple runs and flaky attempts will appear on different lines.
- Targets which failed to build or were filtered out due to language
- or tags will appear as soon as the failure or filtering occurs.</p>
- <var>shard_num</var>: The zero-based shard index, or zero if
- sharding is disabled.<br/>
- <var>total_shards</var>: The total number of shards, or zero if
- sharding is disabled.<br/>
- <var>result</var>: One of <code>no_status</code>, <code>passed</code>,
- <code>failed</code>, <code>timeout</code> or <code>flaky</code>.<br/>
- <var>time</var>: The duration of test execution in milliseconds,
- or -1 if the test was not executed because of caching.<br/>
- <var>log_file</var>: The absolute path to the test log file.
-</li>
-
-<li>
- <code>test <var>label</var> failed_to_build</code> (deprecated) <br/>
- One test failed_to_build line for each test target that failed to build.
-</li>
-
-<li id="test_status"> <code>test_status <var>label</var>
-<var>result</var></code>
-
- <p>
- Reports the final testing status of each test <em>target</em> as soon as it
- becomes available.
- For individual shard and run results, refer to
- <a href="#test_line"><code>test</code></a>. The status codes roughly
- mirror the status lines output to the console. Possible status codes are:
- </p>
- <ul>
- <li><code>passed</code>: the target passed testing.</li>
- <li><code>failed</code>: the target failed in testing.</li>
- <li><code>timeout</code>: the target timed out in testing.</li>
- <li><code>flaky</code>: the target produced flaky results in testing.</li>
- <li><code>incomplete</code>: the target began testing but never completed,
- most likely due to an interrupt.</li>
- <li><code>failed-to-build</code>: the target couldn't be tested because it
- failed to build.</li>
- <li><code>no-status</code>: the target was scheduled to be tested but
- testing was never actually performed on it, most likely due to an interrupt
- or failure while building an earlier target.
- </li>
- </ul>
-</li>
-
-<li>
-<code>baseline_coverage <var>label</var> <var>filename</var></code><br/>
- Reference to the baseline LCOV-based coverage file produced for the given label.
-</li>
-
-<li>
- <code>build_interrupted</code><br/>
- This line is included if the build was interrupted by the user via SIGINT.
- This only applies to server mode. In batch mode, the master build log
- will be truncated before this line would be emitted.
-</li>
-
-<li>
- <code>eof</code><br/>
- This line is guaranteed to be the last non-whitespace line in the file.
-</li>
-</ul>
-
-<h3>Command log</h3>
-
-<p>
- The Bazel output is also available in a command log file which you can
- find with the following command:
-</p>
-
-<pre>
-% bazel info command_log
-</pre>
-
-<p>
- The command log file contains the interleaved stdout and stderr streams
- of the most recent Bazel command. Note that running <code>bazel info</code>
- will overwrite the contents of this file, since it then becomes the most
- recent Bazel command. However, the location of the command log file will
- not change unless you change the setting of the <code class='flag'>--output_base</code>
- or <code class='flag'>--output_user_root</code> options.
-</p>
-
-<h3>Parsing output</h3>
-
-<p>
- The Bazel output is quite easy to parse for many purposes. Two
- options that may be helpful for your script are
- <code class='flag'>--noshow_progress</code> which suppresses progress messages,
- and <code class='flag'>--show_result <var>n</var></code>, which controls whether
- or not "build up-to-date" messages are printed; these messages may
- be parsed to discover which targets were successfully built, and the
- location of the output files they created. Be sure to specify a
- very large value of <i>n</i> if you rely on these messages.
-</p>
-
-<p>
- Note that it often makes sense to use the
- <a href='#master_log'>master log</a> instead of parsing Bazel output
- directly.
-</p>
-
-
-</body>
-</html>
diff --git a/docs/historical/build-encyclopedia.html b/docs/historical/build-encyclopedia.html
deleted file mode 100644
index 53215fc..0000000
--- a/docs/historical/build-encyclopedia.html
+++ /dev/null
@@ -1,3568 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
- <title>Bazel BUILD Encyclopedia of Functions</title>
-
- <style type="text/css" id="internalStyle">
- 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> tag for bits of code and <var> for variable and object names. */
- code,pre,samp,var {
- color: #006000;
- }
- /* Use the <file> tag for file and directory paths and names. */
- file {
- color: #905050;
- font-family: monospace;
- }
- /* Use the <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> 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;
- }
-
- h1 { margin-bottom: 5px; }
- .toc { margin: 0px; }
- ul li { margin-bottom: 1em; }
- ul.toc li { margin-bottom: 0px; }
- em.harmful { color: red; }
-
- .deprecated { text-decoration: line-through; }
- .discouraged { text-decoration: line-through; }
-
- #rules { width: 980px; border-collapse: collapse; }
- #rules td { border-top: 1px solid gray; padding: 4px; vertical-align: top; }
- #rules th { text-align: left; padding: 4px; }
-
- table.layout { width: 980px; }
- table.layout td { vertical-align: top; }
-
- #maintainer { text-align: right; }
-
- dt {
- font-weight: bold;
- margin-top: 0.5em;
- margin-bottom: 0.5em;
- }
- dd dt {
- font-weight: normal;
- text-decoration: underline;
- color: gray;
- }
- </style>
-
- <style type="text/css">
- .rule-signature {
- color: #006000;
- font-family: monospace;
- }
- </style>
-</head>
-
-<body>
-<h1>Bazel BUILD Encyclopedia of Functions</h1>
-
-<h2>Contents</h2>
-
- <h3>Concepts and terminology</h3>
- <table class="layout"><tr><td>
- <ul class="toc">
- <li><a href="#common-definitions">Common definitions</a>:
- <ul>
- <li><a href="#sh-tokenization">Bourne shell tokenization</a></li>
- <li><a href="#label-expansion">Label expansion</a></li>
- <li><a href="#common-attributes">Common attributes</a></li>
- <li><a href="#common-attributes-tests">Common attributes for tests</a></li>
- <li><a href="#common-attributes-binaries">Common attributes for binaries</a></li>
- <li><a href="#implicit-outputs">Implicit output targets</a></li>
- </ul>
- </li>
- </ul>
- </td><td>
- <ul class="toc">
- <li><a href="#make_variables">"Make" variables</a>
- <ul class="toc">
- <li><a href="#make-var-substitution">"Make" variable substitution</a></li>
- <li><a href="#predefined_variables">Predefined variables</a></li>
- <li><a href="#define_your_own_make_vars">Defining your own variables</a>
- <ul>
- <li><a href="#vardef">vardef</a></li>
- <li><a href="#varref">varref</a></li>
- </ul>
- </li>
- </ul>
- <li><a href="#predefined-python-variables">Predefined Python Variables</a></li>
- </ul>
- </td><td>
- <ul class="toc">
- <li><a href="#include">include</a></li>
- <li><a href="#package">package</a></li>
- <li><a href="#package_group">package_group</a></li>
- <li><a href="#description">Description</a></li>
- <li><a href="#distribs">distribs</a></li>
- <li><a href="#licenses">licenses</a></li>
- <li><a href="#exports_files">exports_files</a></li>
- <li><a href="#glob">glob</a></li>
- </ul>
- </td></tr></table>
-
- <h3>Rules</h3>
-
-<table id="rules" summary="Table of rules sorted by language">
-<colgroup span="5" width="20%"></colgroup>
-<tr><th>Language</th><th>Binary rules</th><th>Library rules</th><th>Test rules</th><th>Other rules</th><th></th></tr>
- <tr>
- <td class="lang">Android</td>
- <td><a href="#android_binary">android_binary</a></td>
- <td><a href="#android_library">android_library</a></td>
- <td><a href="#android_test">android_test</a></td>
- <td><a href="#android_device">android_device</a></td>
- <td><a href="#android_manifest_merge">android_manifest_merge</a><br/><a href="#android_resources">android_resources</a></td>
- <tr>
- <td class="lang">Java</td>
- <td><a href="#java_binary">java_binary</a></td>
- <td><a href="#java_import">java_import</a><br/><a href="#java_library">java_library</a></td>
- <td><a href="#java_test">java_test</a></td>
- <td><a href="#java_plugin">java_plugin</a><br/><a href="#java_wrap_cc">java_wrap_cc</a><br/></td>
- <td></td>
- <tr>
- <td class="lang">Shell</td>
- <td><a href="#sh_binary">sh_binary</a></td>
- <td><a href="#sh_library">sh_library</a></td>
- <td><a href="#sh_test">sh_test</a></td>
- <td></td>
- <td></td>
-<tr><th> </th></tr><tr><th colspan="5">Rules that do not apply to a specific programming language</th></tr> <tr>
- <td class="lang">General</td>
- <td><a href="#filegroup">filegroup</a></td>
- <td><a href="#test_suite">test_suite</a></td>
- <td><a href="#genrule">genrule</a></td>
-</table>
-
-
-<h2 id="common-definitions">Common definitions</h2>
-
-<p>This section defines various terms and concepts that are common to
-many functions or build rules below.
-</p>
-
-<!-- we haven't defined 'rules' or 'attributes' yet. -->
-
-<h3 id='sh-tokenization'>Bourne shell tokenization</h3>
-<p>
- Certain string attributes of some rules are split into multiple
- words according to the tokenization rules of the Bourne shell:
- unquoted spaces delimit separate words, and single- and
- double-quotes characters and backslashes are used to prevent
- tokenization.
-</p>
-<p>
- Those attributes that are subject to this tokenization are
- explicitly indicated as such in their definitions in this document.
-</p>
-<p>
- Attributes subject to "Make" variable expansion and Bourne shell
- tokenization are typically used for passing arbitrary options to
- compilers and other tools, such as the <code>copts</code> attribute
- of <code>cc_library</code>, or the <code>javacopts</code> attribute of
- <code>java_library</code>. Together these substitutions allow a
- single string variable to expand into a configuration-specific list
- of option words.
-</p>
-
-<h3 id='label-expansion'>Label expansion</h3>
-<p>
- Some string attributes of a very few rules are subject to label
- expansion: if those strings contain a valid build label as a
- substring, such as <code>//mypkg:target</code>, and that label is a
- declared prerequisite of the current rule, it is expanded into the
- pathname of the file represented by the target <code>//mypkg:target</code>.
-</p>
-<p>
- Example attributes include the <code>cmd</code> attribute of
- genrule, and the <code>linkopts</code> attribute
- of <code>cc_library</code>. The details may vary significantly in
- each case, over such issues as: whether relative labels are
- expanded; how labels that expand to multiple files are
- treated, etc. Consult the rule attribute documentation for
- specifics.
-</p>
-
-<h3 id="common-attributes">Attributes common to all build rules</h3>
-
-<p>This section describes attributes that are common to all build rules.<br/>
-Please note that it is an error to list the same label twice in a list of
-labels attribute.
-</p>
-
-<ul>
-<li id="common.deps"><code>deps</code>:
-A list of dependencies of this rule.
-<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
-The precise semantics of what it means for this rule to depend on
-another using <code>deps</code> are specific to the kind of this rule,
-and the rule-specific documentation below goes into more detail.
-At a minimum, though, the targets named via <code>deps</code> will
-appear in the <code>*.runfiles</code> area of this rule, if it has
-one.
-<p>Most often, a <code>deps</code> dependency is used to allow one
-module to use symbols defined in another module written in the
-same programming language and separately compiled. Cross-language
-dependencies are also permitted in many cases: for example,
-a <code>java_library</code> rule may depend on C++ code in
-a <code>cc_library</code> rule, by declaring the latter in
-the <code>deps</code> attribute. See the definition
-of <a href="build-ref.html#deps">dependencies</a> for more
-information.</p>
-<p>Almost all rules permit a <code>deps</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.</p></li>
-<li id="common.data"><code>data</code>:
-The list of files needed by this rule at runtime.
-<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
-Targets named in the <code>data</code> attribute will appear in
-the <code>*.runfiles</code> area of this rule, if it has one. This
-may include data files needed by a binary or library, or other
-programs needed by it. See the
-<a href="build-ref.html#data">data dependencies</a> section for more
-information about how to depend on and use data files.
-<p>Almost all rules permit a <code>data</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.</p></li>
-<li id="common.deprecation"><code>deprecation</code>:
-<i>(String; optional)</i><br/>
-An explanatory warning message associated with this rule.
-Typically this is used to notify users that a rule has become obsolete,
-or has become superseded by another rule, is private to a package, or is
-perhaps "considered harmful" for some reason. It is a good idea to include
-some reference (like a webpage, a bug number or example migration CLs) so
-that one can easily find out what changes are required to avoid the message.
-If there is a new target that can be used as a drop in replacement, it is a good idea
-to just migrate all users of the old target.
-<p>
-This attribute has no effect on the way things are built, but it
-may affect a build tool's diagnostic output. The build tool issues a
-warning when a rule with a <code>deprecation</code> attribute is
-depended upon by another rule.</p>
-<p>
-Intra-package dependencies are exempt from this warning, so that,
-for example, building the tests of a deprecated rule does not
-encounter a warning.</p>
-<p>
-If a deprecated rule depends on another deprecated rule, no warning
-message is issued.</p>
-<p>
-Once people have stopped using it, the package can be removed or marked as
-<a href="#common.obsolete"><code>obsolete</code></a>.</p></li>
-<li id="common.distribs"><code>distribs</code>:
-<i>(List of strings; optional)</i><br/>
-A list of distribution-method strings to be used for this particular build rule.
-Overrides the <code>BUILD</code>-file scope defaults defined by the
-<a href="#distribs"><code>distribs()</code></a> directive.</li>
-<li id="common.licenses"><code>licenses</code>:
-<i>(List of strings; optional)</i><br/>
-A list of license-type strings to be used for this particular build rule.
-Overrides the <code>BUILD</code>-file scope defaults defined by the
-<a href="#licenses"><code>licenses()</code></a> directive.</li>
-<li id="common.obsolete"><code>obsolete</code>:
-<i>(Boolean; optional; default 0)</i><br/>
-If 1, only obsolete targets can depend on this target. It is an error when
-a non-obsolete target depends on an obsolete target.
-<p>
-As a transition, one can first mark a package as in
-<a href="#common.deprecation"><code>deprecation</code></a>.</p>
-<p>
-This attribute is useful when you want to prevent a target from
-being used but are yet not ready to delete the sources.</p></li>
-<li id="common.tags"><code>tags</code>:
-List of arbitrary text tags. Tags may be any valid string; default is the
-empty list.<br/>
-<i>Tags</i> can be used on any rule; but <i>tags</i> are most useful
-on test and <code>test_suite</code> rules. Tags on non-test rules
-are only useful to humans and/or external programs.
-<i>Tags</i> are generally used to annotate a test's role in your debug
-and release process. The use of tags and size elements
-gives flexibility in assembling suites of tests based around codebase
-check-in policy.
-<p>
-A few tags have special meaning to the build tool; consult
-the <a href='bazel-user-manual.html#tags_keywords'>Bazel
-documentation</a> for details.
-</p></li>
-<li id="common.testonly"><code>testonly</code>:
-<i>(Boolean; optional; default 0 except as noted)</i><br />
-If 1, only testonly targets (such as tests) can depend on this target.
-<p>Equivalently, a rule that is not <code>testonly</code> is not allowed to
-depend on any rule that is <code>testonly</code>.</p>
-<p>Tests (<code>*_test</code> rules)
-and test suites (<a href="#test_suite">test_suite</a> rules)
-are <code>testonly</code> by default.</p>
-<p>By virtue of
-<a href="#package.default_testonly"><code>default_testonly</code></a>,
-targets under <code>javatests</code> are <code>testonly</code> by default.</p>
-<p>This attribute is intended to mean that the target should not be
-contained in binaries that are released to production.</p>
-<p>Because testonly is enforced at build time, not run time, and propagates
-virally through the dependency tree, it should be applied judiciously. For
-example, stubs and fakes that
-are useful for unit tests may also be useful for integration tests
-involving the same binaries that will be released to production, and
-therefore should probably not be marked testonly. Conversely, rules that
-are dangerous to even link in, perhaps because they unconditionally
-override normal behavior, should definitely be marked testonly.</p></li>
-<li id="common.visibility"><code>visibility</code>:
-<i>(List of <a href="build-ref.html#labels">labels</a>; optional; default private)</i><br/>
-<p>The <code>visibility</code> attribute on a rule controls whether
-the rule can be used by other packages. Rules are always visible to
-other rules declared in the same package.</p>
-<p>There are five forms (and one temporary form) a visibility label can take:
-<ul>
-<li><code>['//visibility:public']</code>: Anyone can use this rule.</li>
-<li><code>['//visibility:private']</code>: Only rules in this package
-can use this rule. Rules in <code>javatests/foo/bar</code>
-can always use rules in <code>java/foo/bar</code>.
-</li>
-<li><code>['//some/package:__pkg__', '//other/package:__pkg__']</code>:
-Only rules in <code>some/package</code> and <code>other/package</code>
-(defined in <code>some/package/BUILD</code> and
-<code>other/package/BUILD</code>) have access to this rule. Note that
-sub-packages do not have access to the rule; for example,
-<code>//some/package/foo:bar</code> or
-<code>//other/package/testing:bla</code> wouldn't have access.
-<code>__pkg__</code> is a special target and must be used verbatim.
-It represents all of the rules in the package.
-</li>
-<li><code>['//project:__subpackages__', '//other:__subpackages__']</code>:
-Only rules in packages <code>project</code> or <code>other</code> or
-in one of their sub-packages have access to this rule. For example,
-<code>//project:rule</code>, <code>//project/library:lib</code> or
-<code>//other/testing/internal:munge</code> are allowed to depend on
-this rule (but not <code>//independent:evil</code>)
-</li>
-<li><code>['//some/package:my_package_group']</code>:
-A <a href="#package_group">package group</a> is
-a named set of package names. Package groups can also grant access rights
-to entire subtrees, e.g.<code>//myproj/...</code>.
-</li>
-</ul>
-<p>The visibility specifications of <code>//visibility:public</code>,
-<code>//visibility:private</code> and
-<code>//visibility:legacy_public</code>
-can not be combined with any other visibility specifications.
-A visibility specification may contain a combination of package labels
-(i.e. //foo:__pkg__) and package_groups.</p>
-<p>If a rule does not specify the visibility attribute,
-the <code><a href="#package">default_visibility</a></code>
-attribute of the <code><a href="#package">package</a></code>
-statement in the BUILD file containing the rule is used
-(except <a href="#exports_files">exports_files</a> and
-<a href="#cc_public_library">cc_public_library</a>, which always default to
-public).</p>
-<p><b>Example</b>:</p>
-<p>
-File <code>//frobber/bin/BUILD</code>:
-</p>
-<pre class="code">
-# This rule is visible to everyone
-java_binary(
- name = "executable",
- visibility = ["//visibility:public"],
- deps = [":library"],
-)
-
-# This rule is visible only to rules declared in the same package
-java_library(
- name = "library",
- visibility = ["//visibility:private"],
-)
-
-# This rule is visible to rules in package //object and //noun
-java_library(
- name = "subject",
- visibility = [
- "//noun:__pkg__",
- "//object:__pkg__",
- ],
-)
-
-# See package group //frobber:friends (below) for who can access this rule.
-java_library(
- name = "thingy",
- visibility = ["//frobber:friends"],
-)
-</pre>
-<p>
-File <code>//frobber/BUILD</code>:
-</p>
-<pre class="code">
-# This is the package group declaration to which rule //frobber/bin:thingy refers.
-#
-# Our friends are packages //frobber, //fribber and any subpackage of //fribber.
-package_group(
- name = "friends",
- packages = [
- "//fribber/...",
- "//frobber",
- ],
-)
-</pre></li>
-</ul>
-
-
-<h3 id="common-attributes-tests">Attributes common to all test rules (*_test)</h3>
-
-<p>This section describes attributes that are common to all test rules.</p>
-
-<ul>
-<li id="test.args"><code>args</code>:
-Add these arguments to the <code>--test_arg</code>
-when executed by <code>bazel test</code>.
-<i>(List of strings; optional; subject to
-<a href="#make_variables">"Make variable"</a> substitution and
-<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
-These arguments are passed before the <code>--test_arg</code> values
-specified on the <code>bazel test</code> command line.</li>
-<li id="test.flaky"><code>flaky</code>:
-Marks test as flaky. <i>(Boolean; optional)</i><br/>
-If set, executes the test up to 3 times before being declared as failed.
-By default this attribute is set to 0 and test is considered to be stable.
-Note, that use of this attribute is generally discouraged - we do prefer
-all tests to be stable.</li>
-<li id="test.local"><code>local</code>:
-Forces the test to be run locally. <i>(Boolean; optional)</i><br/>
-By default this attribute is set to 0 and the default testing strategy is
-used. This is equivalent to providing 'local' as a tag
-(<code>tags=["local"]</code>).</li>
-<li id="test.shard_count"><code>shard_count</code>:
-Specifies the number of parallel shards
-to use to run the test. <i>(Non-negative integer less than or equal to 50;
-optional)</i><br/>
-This value will override any heuristics used to determine the number of
-parallel shards with which to run the test.</li>
-<li id="test.size"><code>size</code>:
-How "heavy" the test is
-<i>(String "enormous", "large" "medium" or "small",
-default is "medium")</i><br/>
-A classification of the test's "heaviness": how much time/resources
-it needs to run. This is useful when deciding which tests to run.
-Before checking in a change, you might run the small tests.
-Before a big release, you might run the large tests.
-</li>
-<li id="test.timeout"><code>timeout</code>:
-How long the test is
-normally expected to run before returning.
-<i>(String "eternal", "long", "moderate", or "short"
-with the default derived from a test's size attribute)</i><br/>
-While a test's size attribute controls resource estimation, a test's
-timeout may be set independently. If not explicitly specified, the
-timeout is based on the test's size (with "small" ⇒ "short",
-"medium" ⇒ "moderate", etc...). While size and runtime are generally
-heavily correlated, they are not strictly causal, hence the ability to set
-them independently.</li>
-</ul>
-
-
-<h3 id="common-attributes-binaries">Attributes common to all binary rules (*_binary)</h3>
-
-<p>This section describes attributes that are common to all binary rules.</p>
-
-<ul>
-<li id="binary.args"><code>args</code>:
-Add these arguments to the target when executed by
-<code>bazel run</code>.
-<i>(List of strings; optional; subject to
-<a href="#make_variables">"Make variable"</a> substitution and
-<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
-These arguments are passed to the target before the target options
-specified on the <code>bazel run</code> command line.
-<p>Most binary rules permit an <code>args</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.</p></li>
-<li id="binary.output_licenses"><code>output_licenses</code>:
-The licenses of the output files that this binary generates.
-<i>(List of strings; optional)</i><br/>
-Describes the licenses of the output of the binary generated by
-the rule. When a binary is referenced in a host attribute (for
-example, the <code>tools</code> attribute of
-a <code>genrule</code>), this license declaration is used rather
-than the union of the licenses of its transitive closure. This
-argument is useful when a binary is used as a tool during the
-build of a rule, and it is not desirable for its license to leak
-into the license of that rule. If this attribute is missing, the
-license computation proceeds as if the host dependency was a
-regular dependency.
-<p><em class="harmful">WARNING: in some cases (specifically, in
-genrules) the build tool cannot guarantee that the binary
-referenced by this attribute is actually used as a tool, and is
-not, for example, copied to the output. In these cases, it is the
-responsibility of the user to make sure that this is
-true.</em></p></li>
-</ul>
-
-
-<h3 id="implicit-outputs">Implicit output targets</h3>
-
-<p>When you define a build rule in a BUILD file, you are explicitly
- declaring a new, named rule target in a package. Many build rule
- functions also <i>implicitly</i> entail one or more output file
- targets, whose contents and meaning are rule-specific.
-
- For example, when you explicitly declare a
- <code>java_binary(name='foo', ...)</code> rule, you are also
- <i>implicitly</i> declaring an output file
- target <code>foo_deploy.jar</code> as a member of the same package.
- (This particular target is a self-contained Java archive suitable
- for deployment.)
-</p>
-
-<p>
- Implicit output targets are first-class members of the build
- target graph. Just like other targets, they are built on demand,
- either when specified in the top-level built command, or when they
- are necessary prerequisites for other build targets. They can be
- referenced as dependencies in BUILD files, and can be observed in
- the output of analysis tools such as <code>bazel query</code>.
-</p>
-
-<p>
- For each kind of build rule, the rule's documentation contains a
- special section detailing the names and contents of any implicit
- outputs entailed by a declaration of that kind of rule.
-</p>
-
-<p>
- Please note an important but somewhat subtle distinction between the
- two namespaces used by the build system. Build
- <a href="build-ref.html#labels">labels</a> identify <em>targets</em>,
- which may be rules or files, and file targets may be divided into
- either source (or input) file targets and derived (or output) file
- targets. These are the things you can mention in BUILD files,
- build from the command-line, or examine using <code>bazel query</code>;
- this is the <em>target namespace</em>. Each file target corresponds
- to one actual file on disk (the "file system namespace"); each rule
- target may correspond to zero, one or more actual files on disk.
- There may be files on disk that have no corresponding target; for
- example, <code>.o</code> object files produced during C++ compilation
- cannot be referenced from within BUILD files or from the command line.
- In this way, the build tool may hide certain implementation details of
- how it does its job. This is explained more fully in
- the <a href="build-ref.html">BUILD Concept Reference</a>.
-</p>
-<!-- ============================================
- binary
- ============================================
--->
-<h2 id="binary">*_binary</h2>
-
-<p>A <code>*_binary</code> rule compiles an application. This might be
- an executable, a <code>.jar</code> file, and/or a collection of scripts.</p>
-
-<h3 id="android_binary">android_binary</h3>
-
-
-<p class="rule-signature">
-android_binary(<a href="#android_binary.name">name</a>,
-<a href="#android_binary.deps">deps</a>,
-<a href="#android_binary.srcs">srcs</a>,
-<a href="#android_binary.resources">resources</a>,
-<a href="#android_binary.aaptopts">aaptopts</a>,
-<a href="#android_binary.debug_key">debug_key</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#android_binary.dexopts">dexopts</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>,
-<a href="#android_binary.proguard_specs">proguard_specs</a>,
-<a href="#android_binary.strict_android_deps">strict_android_deps</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
- Produces Android application package files (.apk).
-</p>
-
-<h4 id="android_binary_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>name</var>.apk</code>: An Android application
- package file signed with debug keys and
- <a href="http://developer.android.com/guide/developing/tools/zipalign.html">
- zipaligned</a>, it could be used to develop and debug your application.
- You cannot release your application when signed with the debug keys.</li>
- <li><code><var>name</var>_unsigned.apk</code>: An unsigned version of the
- above file that could be signed with the release keys before release to
- the public.
- </li>
- <li><code><var>name</var>_deploy.jar</code>: A Java archive containing the
- transitive closure of this target.
- <p>The deploy jar contains all the classes that would be found by a
- classloader that searched the runtime classpath of this target
- from beginning to end.</p>
- </li>
- <li><code><var>name</var>_proguard.jar</code>: A Java archive containing
- the result of running ProGuard on the
- <code><var>name</var>_deploy.jar</code>.
- This output is only produced if
- <a href="#android_binary.proguard_specs">proguard_specs</a> attribute is
- specified.
- </li>
- <li><code><var>name</var>_proguard.map</code>: A mapping file result of
- running ProGuard on the <code><var>name</var>_deploy.jar</code>.
- This output is only produced if
- <a href="#android_binary.proguard_specs">proguard_specs</a> attribute is
- specified and
- <a href="#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>
- is set.
- </li>
- </ul>
-
-
-<h4 id="android_binary">Arguments</h4>
-<ul>
-<li id="android_binary.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="android_binary.deps"><code>deps</code>:
- The list of other libraries to be linked in to the binary target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- Permitted library types are: <code>android_library</code>,
- <code>android_idl</code>, <code>java_library</code> with
- <code>android</code> constraint and <code>cc_library</code> wrapping or
- producing <code>.so</code> native libraries for the Android target platform.
-</li>
-<li id="android_binary.srcs"><code>srcs</code>:
- The list of source files that are processed to create the target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
- <p><code>srcs</code> files of type <code>.java</code> are compiled.
- <em>For readability's sake</em>, it is not good to put the name of a
- generated <code>.java</code> source file into the <code>srcs</code>.
- Instead, put the depended-on rule name in the <code>srcs</code>, as
- described below.
- </p>
- <p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
- compiled. (This is useful if you need to generate a set of .java files with
- a genrule or build extension.)
- </p>
- <p>This rule currently forces source and class compatibility with Java 6.
- </p>
- <p><code>srcs</code> files of type <code>.jar</code> are linked in.
- (This is useful if you have third-party <code>.jar</code> files
- with no source.)
- </p>
-</li>
-<li id="android_binary.resources"><code>resources</code>:
- The <code>android_resources</code> target corresponding to this binary.
- <i>(<a href="build-ref.html#labels">Label</a>; required)</i><br/>
- The target describing the manifest, resources and assets used by this
- binary.
-</li>
-<li id="android_binary.aaptopts"><code>aaptopts</code>:
- Additional command-line flags for the aapt tool when generating apk. This
- is only used if this rule uses other android_library project with resources.
- <i>(List of strings; optional; subject to
- <a href="#make_variables">"Make variable"</a> substitution and
- <a href="#sh-tokenization">Bourne shell tokenization</a>)</i>
-</li>
-<li id="android_binary.debug_key"><code>debug_key</code>:
- File containing debug keystore to be used to sign debug apk.
- <i>(<a href="build-ref.html#labels">Label</a>; optional)</i>.
- Points to a location of debug keystore file that is different than default
- debug key. Usually you do not want to use key other than default key, so
- this attribute should be omitted.
-</li>
-<li id="android_binary.dexopts"><code>dexopts</code>:
- Additional command-line flags for the dx tool when generating classes.dex.
- <i>(List of strings; optional; subject to
- <a href="#make_variables">"Make variable"</a> substitution and
- <a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
-</li>
-<li id="android_binary.proguard_generate_mapping"><code>proguard_generate_mapping</code>:
- Whether to generate Proguard mapping file.
- <i>(Boolean; optional, default is 0)</i><br/>
- The mapping file will be generated only if <code>proguard_specs</code> is
- specified. This file will list the mapping between the original and
- obfuscated class, method, and field names.
- <p><em class="harmful">WARNING: If you use this attribute, your Proguard specification
- should contain neither <code>-dontobfuscate</code> nor <code>-printmapping</code>.
- </em>.</p>
-</li>
-<li id="android_binary.proguard_specs"><code>proguard_specs</code>:
- Files to be used as Proguard specification.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- This file will describe the set of specifications to be used by Proguard.
-</li>
-<li id="android_binary.strict_android_deps"><code>strict_android_deps</code>:
- <i>(Integer; optional; default is -1 (inherited))</i><br/>
- <p>By default, javac will perform checks when compiling the java sources
- in this library to verify that all explicitly mentioned classes were loaded
- from directly specified <code>deps</code> (rather than from the transitive
- closure of all <code>deps</code>), the transitive closure of
- <del><code>srcs</code>-less libraries</del>, and the transitive closure of
- <code>exports</code>. This default can be overridden when set to 0.</p>
-</li>
-</ul>
-
-
-<h3 id="java_binary">java_binary</h3>
-
-
-<p class="rule-signature">
-java_binary(<a href="#java_binary.name">name</a>,
-<a href="#java_binary.deps">deps</a>,
-<a href="#java_binary.srcs">srcs</a>,
-<a href="#common.data">data</a>,
-<a href="#java_binary.resources">resources</a>,
-<a href="#binary.args">args</a>,
-<a href="#java_binary.classpath_resources">classpath_resources</a>,
-<a href="#java_binary.create_executable">create_executable</a>,
-<a href="#java_binary.deploy_env">deploy_env</a>,
-<a href="#java_binary.deploy_manifest_lines">deploy_manifest_lines</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#java_binary.javacopts">javacopts</a>,
-<a href="#java_binary.jvm_flags">jvm_flags</a>,
-<a href="#java_binary.launcher">launcher</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#java_binary.main_class">main_class</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#binary.output_licenses">output_licenses</a>,
-<a href="#java_binary.plugins">plugins</a>,
-<a href="#java_binary.runtime_deps">runtime_deps</a>,
-<a href="#java_binary.stamp">stamp</a>,
-<a href="#java_binary.swigdeps">swigdeps</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#java_binary.use_testrunner">use_testrunner</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
- Builds a Java archive ("jar file"), plus a wrapper shell script with the same
- name as the rule. The wrapper shell script uses a classpath that
- includes, among other things, a jar file for each library on
- which the binary depends.
-</p>
-
-<h4 id="java_binary_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>name</var>.jar</code>: A Java archive, containing the
- class files and other resources corresponding to the binary's
- direct dependencies.
- </li>
- <li><code><var>name</var>-src.jar</code>: An archive containing the sources ("source jar").</li>
- <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable
- for deployment (only built if explicitly requested).
- <p>Building the <code><java_binary_name>_deploy.jar</code>
- target for your rule creates a self-contained
- <code><java_binary_name>_deploy.jar</code> file with a manifest that
- allows it to be run with the <code>java -jar</code> command or with the
- wrapper script's <code>--singlejar</code> option. Using the wrapper script
- is preferred, as it also passes the <a href="#java_binary.jvm_flags">JVM
- flags</a> and the options to load SWIG libraries.</p>
- <p>The deploy jar contains all the classes that would be found by a
- classloader that searched the classpath from the binary's wrapper script
- from beginning to end. It also contains the native libraries needed for SWIG
- dependencies; these are automatically unpacked and loaded into the JVM at
- runtime.</p>
- </li>
- <li><code><var>name</var>_deploy-src.jar</code>: An archive containing the sources collected from
- the transitive closure of the target. These will matches the classes in the
- <code>deploy.jar</code>, except for cases where jars have no matching source jar.</li>
- </ul>
-
-
-<h4 id="java_binary">Arguments</h4>
-<ul>
-<li id="java_binary.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i> <br/>This should be the same as the name of the source file that is the main
- entry point of the application (minus the extension). For example, if
- your entry point is called <code>Main.java</code>, then your name should
- be <code>Main</code>.
-</li>
-<li id="java_binary.deps"><code>deps</code>:
- The list of other libraries to be linked in to the target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- See general comments about <code>deps</code>
- at <a href="#common-attributes">Attributes common to all build
- rules</a>.
-
- <p>These can be
- <a href="#java_library"><code>java_library</code></a>,
- <a href="#cc_library"><code>cc_library</code></a>, or
- <a href="#java_wrap_cc"><code>java_wrap_cc</code></a> rules.</p>
-
- <p>
- If this rule has no <code>srcs</code>, then it should have
- only one <code>deps</code>, the <code>java_library</code>
- containing the <code>.java</code> file suggested by this
- rule's <code>name</code>.
- </p>
-
- <p>
- The following code snippet illustrates a common mistake:
- </p>
-
-<pre class="code">
-java_binary(
- name = "DontDoThis",
- srcs = [
- <var>...</var>,
- <code class="deprecated">"GeneratedJavaFile.java"</code>, # a generated .java file
- ],
- deps = [<code class="deprecated">":generating_rule",</code>], # rule that generates that file
-)
-</pre>
-
- <p>This is better:</p>
-
-<pre class="code">
-java_binary(
- name = "DoThisInstead",
- srcs = [
- <var>...</var>,
- ":generating_rule",
- ],
-)
-</pre>
-
- <p>More <a href="#java_binary_examples">examples</a> are below.</p>
- <p>
- Why list the generating rule instead of file names in <code>srcs</code>?
- Because it is more resilient to future changes: if the generating rule
- generates different files in the future, you only need to fix one
- place--the <code>outs</code> of the generating rule. Why not list the
- generating rule in <code>deps</code>? Because it is a no-op.
- </p>
-</li>
-<li id="java_binary.srcs"><code>srcs</code>:
- The list of source files that are processed to create the target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; required excepting
- special cases described below)</i>
-
- <p><code>srcs</code> files of type <code>.java</code> are compiled.
- <em>For readability's sake</em>, it is not good to put the name of a
- generated <code>.java</code> source file into the <code>srcs</code>.
- Instead, put the depended-on rule name in the <code>srcs</code>, as
- described below.
- </p>
-
- <p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
- compiled. (This is useful if you need to generate a set of .java files with
- a genrule or build extension.)
- </p>
-
- <p><code>srcs</code> files of type <code>.jar</code> are linked in.
- (This is useful if you have third-party <code>.jar</code> files
- with no source.)
- </p>
-
- <p><code>srcs</code> files of type <code>.properties</code> are treated as
- resources.</p>
-
- <p style="margin-bottom:0.25em; ">
- This argument is required, excepting special cases:</p>
-
- <ul>
- <li style="margin-bottom: 0.25em; ">
- a <a href="#java_binary.main_class"><code>main_class</code></a>
- attribute specifies a class on the runtime classpath; or</li>
- <li style="margin-bottom: 1.0em; ">
- you specify the <code>use_testrunner</code> argument</li>
- </ul>
-</li>
-<li id="java_binary.resources"><code>resources</code>:
- A list of data files to include in a Java jar.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- If resources are specified, they will be bundled in the jar along with
- the usual <code>.class</code> files produced by compilation. All
- resources will be
- placed in the jar in a directory corresponding to the build package
- name, regardless of their original location on the filesystem. Resources
- may be source files or derived files.
-</li>
-<li id="java_binary.classpath_resources"><code>classpath_resources</code>:
- <i>(optional)</i>
- A list of resources that must be located at the root of the java
- tree. This was introduced because some third party libraries required
- that their resources be found on the classpath as exactly "myconfig.xml".
- It is only allowed on binaries and not libraries, due to the danger of
- namespace conflicts.
-</li>
-<li id="java_binary.create_executable"><code>create_executable</code>:
- Whether to build the executable wrapper script or not.
- <i>(Boolean; optional; default is 1)</i><br/>
- If this option is present, no executable wrapper script is built
- around the .jar file. Incompatible with <code>main_class</code>
- attribute.
-</li>
-<li id="java_binary.deploy_env"><code>deploy_env</code>:
- A list of other <code>java_binary</code> targets which represent the deployment
- environment for this binary. Set this attribute when building a plugin
- which will be loaded by another <code>java_binary</code>.<br />
- Setting this attribute excludes all dependencies from the runtime classpath
- (and the deploy jar) of this binary that are shared between this binary and
- the targets specified in <code>deploy_env</code>.
-</li>
-<li id="java_binary.deploy_manifest_lines"><code>deploy_manifest_lines</code>:
- A list of lines to add to the meta-inf/manifest.mf file generated for the
- <code>*_deploy.jar</code> target. The
- contents of <code>deploy_manifest_lines</code> are not subject to
- <a href="#make_variables">"Make variable"</a> substitution.
-</li>
-<li id="java_binary.javacopts"><code>javacopts</code>:
- Extra compiler options for this library.
- <i>(List of strings; optional; subject to
- <a href="#make_variables">"Make variable"</a> substitution and
- <a href="#sh-tokenization">Bourne shell tokenization</a>)</i>
- <p>
- These compiler options are passed to javac after the global compiler
- options.</p>
-</li>
-<li id="java_binary.jvm_flags"><code>jvm_flags</code>:
- A list of flags to
- embed in the wrapper script generated for running this binary.
- <i>(List of strings; optional; subject to
- <a href="#make_variables">"Make variable"</a> substitution and
- <a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
- The wrapper script for a Java binary includes a CLASSPATH definition
- (to find all the dependent jars) and invokes the right Java interpreter.
- The command line generated by the wrapper script includes the name of
- the main class followed by a <code>"$@"</code> so you can pass along other
- arguments after the classname. However, arguments intended for parsing
- by the JVM must be specified <i>before</i> the classname on the command
- line. The contents of <code>jvm_flags</code> are added to the wrapper
- script before the classname is listed.
-</li>
-<li id="java_binary.launcher"><code>launcher</code>:
- <i>(Label; optional; default is empty.)</i><br/>
- If specified, the target will be used to launch the Java Virtual Machine in
- the wrapper shell script. The target must be a <code>cc_binary</code>.
- Any <code>cc_binary</code> that implements the Java Invocation AP can be a launcher
- target.
-
- <p>The related <a href="bazel-user-manual.html#flag--java_launcher"><code>
- --java_launcher</code></a> bazel flag affects only those
- <code>java_binary</code> and <code>java_test</code> targets that have
- <i>not</i> specified a <code>launcher</code> attribute.
-
- <p>If you build a deploy jar and specify a launcher target through either
- this <code>launcher</code> attribute or <code>--java_launcher</code> Bazel
- flag, then the deploy jar will be a single file that is both (a) a .jar
- file that contains the appropriate classes, and (b) the executable
- specified by the launcher target.</p>
-</li>
-<li id="java_binary.main_class"><code>main_class</code>:
- Name of class with <code>main()</code> method to use as entry point.
- <i>(String)</i> <br/>
- If a rule uses this option, it does not need a <code>srcs=[...]</code>
- list.
- Thus, with this attribute one can make an executable from a Java library
- that already contains one or more <code>main()</code> methods.
-
- The value of the
- <code>main_class</code> attribute is a class name, not a source file.
- The class must be available at runtime: it may be compiled by this rule
- (from <code>srcs</code>) or provided by direct or transitive dependencies
- (through <code>runtime_deps</code> or <code>deps</code>). If the class is
- unavailable, the binary will fail at runtime; there is no build-time check.
-</li>
-<li id="java_binary.plugins"><code>plugins</code>:
- Java compiler plugins to run at compile-time.
- <i>(List of <a href="build-ref.html#labels">labels</a>;
- optional)</i><br/> Every <code>java_plugin</code> specified in
- the plugins attribute will be run whenever
- this <code>java_library</code> is built. A library may also inherit
- plugins from dependencies that use
- <code><a href="#java_library.exported_plugins">exported_plugins</a></code>.
- Resources generated by the plugin will be included in the result jar of
- the <code>java_library</code>.
-</li>
-<li id="java_binary.runtime_deps"><code>runtime_deps</code>:
- Libraries to make available to the final binary or test at runtime only.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- Like ordinary <code>deps</code>, these will appear on the runtime
- classpath, but unlike them, not on the compile-time classpath.
- Dependencies needed only at runtime should be here because
- dependency-management tools may remove deps not needed at compile time.
- Dependency-management tools should ignore targets that appear in both
- <code>runtime_deps</code> and <code>deps</code>.
-</li>
-<li id="java_binary.stamp"><code>stamp</code>:
- Enable link stamping.
- <i>(Integer; optional; default is -1)</i><br/>
- Whether to encode build information into the binary. Possible values:
- <ul>
- <li><code>stamp = 1</code>: Stamp the build information into the
- binary. Stamped binaries are only rebuilt when their dependencies
- change. Use this if there are tests that depend on the build
- information.</li>
- <li><code>stamp = 0</code>: Always replace build information by constant
- values. This gives good build result caching.</li>
- <li><code>stamp = -1</code>: Embedding of build information is controlled
- by the <a href="bazel-user-manual.html#flag--stamp">--[no]stamp</a> Bazel
- flag.</li>
- </ul>
-</li>
-<li id="java_binary.swigdeps"><code>swigdeps</code>:
- <i>(Boolean; optional; default 1)</i><br/>
- If 0, do not build and add a swigdeps.so file into the binary, even if
- there are cc or swig targets in the transitive closure.
- Useful if native code is loaded via a different mechanism for this binary,
- such as native methods linked into a cc_binary.
-</li>
-<li id="java_binary.use_testrunner"><code>use_testrunner</code>:
- Use the
- You can use this to override the default
- behavior. It is unlikely
- you will want to do this. One use is for <code>AllTest</code>
- rules that are invoked by another rule (to set up a database
- before running the tests, for example). The <code>AllTest</code>
- rule must be declared as a <code>java_binary</code>, but should
- still use the test runner as its main entry point.
-</li>
-</ul>
-
-
-<h3 id="sh_binary">sh_binary</h3>
-
-
-<p class="rule-signature">
-sh_binary(<a href="#sh_binary.name">name</a>,
-<a href="#sh_binary.deps">deps</a>,
-<a href="#sh_binary.srcs">srcs</a>,
-<a href="#common.data">data</a>,
-<a href="#binary.args">args</a>,
-<a href="#sh_binary.bash_version">bash_version</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#binary.output_licenses">output_licenses</a>,
-<a href="#sh_binary.random_tmpdir">random_tmpdir</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
- The <code>sh_binary</code> rule is used to declare executable
- programs in interpreted languages such as the Bourne shell, or Bash,
- Perl, Ruby, etc. (<code>sh_binary</code> is a double misnomer: its
- outputs aren't necessarily either shell programs or binary.) This
- rule ensures that all dependencies are built, and appear in
- the <code>runfiles</code> area at execution time. We recommend that you name
- your <code>sh_binary()</code> rules after the name of the script
- minus the extension (e.g. <code>.sh</code>); do not give the rule
- and the file the same name.
-</p>
-
-<h4 id="sh_binary_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>name</var>.sar</code>: A self-contained binary (i.e. one that
- packages all its dependencies).
- </li>
- </ul>
-
-
-<h4 id="sh_binary">Arguments</h4>
-<ul>
-<li id="sh_binary.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i> <br/>If your main script is called <code>foo.sh</code>, we recommend
- that you name the rule <code>foo</code>, but this is not required.
-</li>
-<li id="sh_binary.deps"><code>deps</code>:
- The list of other "library" targets to be aggregated in to this executable program.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- See general comments about <code>deps</code>
- at <a href="#common-attributes">Attributes common to all build rules</a>.
- You should use this attribute to list other
- <code>sh_library</code> rules that provide
- interpreted program source code depended on by the code in
- <code>srcs</code>.
-</li>
-<li id="sh_binary.srcs"><code>srcs</code>:
- The shell script.
- <i>(A list of <a href="build-ref.html#labels">labels</a> of length 1; required)</i><br/>
- This attribute must be a singleton list, whose element is the
- shell script (or other script). This script must be executable,
- and may be a source file or a generated file. All other files
- required at runtime (whether scripts or data) belong in the
- <code>data</code> attribute.
- <!-- TODO: allow multiple srcs. Guess the main one based on the
- rule name (quite tricky). -->
-</li>
-<li id="sh_binary.bash_version"><code>bash_version</code>:
- The version of bash to package with this target's .sar file.
- <i>(String; optional; default is "system")</i><br/>
- Valid values are: <code>"3"</code>, <code>"4"</code>, and
- <code>"system"</code>. The first embeds bash 3. The second embeds
- bash 4. The third doesn't embed anything, so the script runs with
- whatever version is installed on the executing system.
-</li>
-<li id="sh_binary.random_tmpdir"><code>random_tmpdir</code>:
- Whether or not to extract .sar contents to a randomly chosen temp directory.
- <i>(Boolean; optional; default is 1)</i><br/>
- If <code>0</code>, the directory's name is computed from a hash of the
- .sar file contents. This saves the need to redo extraction each time
- the .sar is run, making startup time potentially much shorter. However,
- it also increases the risk of failure due to the system removing files
- from the temp dir.
-</li>
-</ul>
-
-
-<h4 id="sh_binary_examples">Example</h4>
-
-<p>For a simple shell script with no dependencies or data:
-</p>
-
-<pre class="code">
-sh_binary(
- name = "foo",
- srcs = ["foo.sh"],
-)
-</pre>
-
-<!-- ============================================
- library
- ============================================
--->
-<h2 id="library">*_library</h2>
-
-<p>A <code>*_library()</code> rule compiles some sources into a library.
- In general, a <code><var>language</var>_library</code> rule works like
- the corresponding <code><var>language</var>_binary</code> rule, but
- doesn't generate something executable.</p>
-
-<h3 id="android_library">android_library</h3>
-
-
-<p class="rule-signature">
-android_library(<a href="#android_library.name">name</a>,
-<a href="#android_library.deps">deps</a>,
-<a href="#android_library.srcs">srcs</a>,
-<a href="#common.data">data</a>,
-<a href="#android_library.resources">resources</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#android_library.idl_import_root">idl_import_root</a>,
-<a href="#android_library.idl_parcelables">idl_parcelables</a>,
-<a href="#android_library.idl_srcs">idl_srcs</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#android_library.neverlink">neverlink</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#android_library.plugins">plugins</a>,
-<a href="#android_library.proguard_specs">proguard_specs</a>,
-<a href="#android_library.strict_android_deps">strict_android_deps</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>This rule compiles and archives its sources into a <code>.jar</code> file.
- The Android runtime library <code>android.jar</code> is implicitly put on
- the compilation class path.
-</p>
-
-<h4 id="android_library_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code>lib<var>name</var>.jar</code>: A Java archive.</li>
- <li><code>lib<var>name</var>-src.jar</code>: An archive containing the
- sources ("source jar").</li>
- </ul>
-
-
-<h4 id="android_library">Arguments</h4>
-<ul>
-<li id="android_library.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="android_library.deps"><code>deps</code>:
- The list of other libraries to link against.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- Permitted library types are: <code>android_library</code>,
- <code>java_library</code> with <code>android</code> constraint and
- <code>cc_library</code> wrapping or producing <code>.so</code> native libraries
- for the Android target platform.
-</li>
-<li id="android_library.srcs"><code>srcs</code>:
- The list of source files that are processed to create the target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
- <p><code>srcs</code> files of type <code>.java</code> are compiled.
- <em>For readability's sake</em>, it is not good to put the name of a
- generated <code>.java</code> source file into the <code>srcs</code>.
- Instead, put the depended-on rule name in the <code>srcs</code>, as
- described below.
- </p>
- <p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
- compiled. (This is useful if you need to generate a set of .java files with
- a genrule or build extension.)
- </p>
- <p>This rule currently forces source and class compatibility with Java 6.
- </p>
- <p><code>srcs</code> files of type <code>.jar</code> are linked in.
- (This is useful if you have third-party <code>.jar</code> files
- with no source.)
- </p>
-</li>
-<li id="android_library.resources"><code>resources</code>:
- The <code>android_resources</code> target assigned to this library.
- <i>(<a href="build-ref.html#labels">Label</a>; optional)</i><br/>
- If specified, the resources will be added to any <code>android_binary</code>
- depending on this library.
- <p>Only an <code>android_resource</code> rule with the attribute
- <code>inline_constants</code> set to 0 can be used in this case.</p>
-</li>
-<li id="android_library.idl_import_root"><code>idl_import_root</code>:
- Package-relative path to the root of the java package tree containing idl
- sources included in this library.
- <i>(String; optional)</i><br/>
- This path will be used as the import root when processing idl sources that
- depend on this library. If the import is part of the normal java
- package structure, this attribute is unnecessary. (See
- <a href="#android_library_examples.idl_import_root">examples</a>.)
-</li>
-<li id="android_library.idl_parcelables"><code>idl_parcelables</code>:
- List of Android IDL definitions to supply as imports.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- These files will be made available as imports for any
- <code>android_library</code> target that depends on this library, directly
- or via its transitive closure, but will not be translated to Java
- or compiled.
- <p>Only <code>.aidl</code> files that correspond directly to
- <code>.java</code> sources in this library should be included (e.g., custom
- implementations of Parcelable), otherwise <code>idl_srcs</code> should be
- used.</p>
-</li>
-<li id="android_library.idl_srcs"><code>idl_srcs</code>:
- List of Android IDL definitions to translate to Java interfaces.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- After the Java interfaces are generated, they will be compiled together
- with the contents of <code>srcs</code>.
- <p>These files will be made available as imports for any
- <code>android_library</code> target that depends on this library, directly
- or via its transitive closure.</p>
-</li>
-<li id="android_library.neverlink"><code>neverlink</code>:
- Only use this library for compilation and not at runtime.
- <i>(Boolean; optional; default is 0)</i><br/>
- The outputs of a rule marked as <code>neverlink</code> will not be used in
- <code>.apk</code> creation. Useful if the library will be provided by the
- runtime environment during execution.
-</li>
-<li id="android_library.plugins"><code>plugins</code>:
- Java compiler plugins to run at compile-time.
- <i>(List of <a href="build-ref.html#labels">labels</a>;
- optional)</i><br/> Every <code>java_plugin</code> specified in
- the plugins attribute will be run whenever
- this <code>android_library</code> is built. Resources generated by
- the plugin will be included in the result jar of
- the <code>android_library</code>.
-</li>
-<li id="android_library.proguard_specs"><code>proguard_specs</code>:
- Files to be used as Proguard specification.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- These will describe the set of specifications to be used by Proguard. If specified,
- they will be added to any <code>android_binary</code> target depending on this library.
-
- The files included here must only have idempotent rules, namely -dontnote, -dontwarn,
- assumenosideeffects, and rules that start with -keep. Other options can only appear in
- <code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.
-</li>
-<li id="android_library.strict_android_deps"><code>strict_android_deps</code>:
- <i>(Integer; optional; default is -1 (inherited))</i><br/>
- <p>When set to 1, javac will perform checks when compiling the java sources in
- this library to verify that all explicitly mentioned classes were loaded from
- directly specified <code>deps</code> (rather than from the transitive closure
- of all <code>deps</code>). Set to 0 to mark target non-compliant in preparation
- for future modification of default behavior, when 1 will become the default.
- </p>
-</li>
-</ul>
-
-
-<h3 id="java_import">java_import</h3>
-
-
-<p class="rule-signature">
-java_import(<a href="#java_import.name">name</a>,
-<a href="#common.data">data</a>,
-<a href="#java_import.constraints">constraints</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#java_import.exports">exports</a>,
-<a href="#java_import.jars">jars</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#java_import.neverlink">neverlink</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#java_import.srcjar">srcjar</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
- <p>This rule allows the use of precompiled JAR files as libraries for
- <code><a href="#java_library">java_library</a></code> rules.</p>
-
-<h4 id="java_import">Arguments</h4>
-<ul>
-<li id="java_import.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="java_import.constraints"><code>constraints</code>:
- Extra constraints imposed on this rule as a Java library.
- <i>(List of strings; optional)</i><br />
- See <a href="#java_library.constraints">java_library.constraints</a>.
-</li>
-<li id="java_import.exports"><code>exports</code>:
- Targets to make available to users of this rule.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- See <a href="#java_library.exports">java_library.exports</a>.
-</li>
-<li id="java_import.jars"><code>jars</code>:
- The list of JAR files provided to Java targets that depend on this target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; required)</i>
-</li>
-<li id="java_import.neverlink"><code>neverlink</code>:
- Only use this library for compilation and not at runtime.
- <i>(Boolean; optional; default is 0)</i><br/>
- Useful if the library will be provided by the runtime environment
- during execution. Examples of libraries like this are the IDE APIs
- for IDE plug-ins or <code>tools.jar</code> for anything running on
- a standard JDK.
-</li>
-<li id="java_import.srcjar"><code>srcjar</code>:
- A JAR file that contains source code for the compiled JAR files.
- <i>(<a href="build-ref.html#labels">Label</a>; optional)</i>
-</li>
-</ul>
-
-
-<h3 id="java_library">java_library</h3>
-
-
-<p class="rule-signature">
-java_library(<a href="#java_library.name">name</a>,
-<a href="#java_library.deps">deps</a>,
-<a href="#java_library.srcs">srcs</a>,
-<a href="#java_library.data">data</a>,
-<a href="#java_binary.resources">resources</a>,
-<a href="#java_library.constraints">constraints</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#java_library.exported_plugins">exported_plugins</a>,
-<a href="#java_library.exports">exports</a>,
-<a href="#java_binary.javacopts">javacopts</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#java_library.neverlink">neverlink</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#java_binary.plugins">plugins</a>,
-<a href="#java_binary.runtime_deps">runtime_deps</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>This rule compiles and links sources into a <code>.jar</code> file.
-</p>
-
-<h4 id="java_library_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code>lib<var>name</var>.jar</code>: A Java archive containing the class files.</li>
- <li><code>lib<var>name</var>-src.jar</code>: An archive containing the sources ("source jar").</li>
- </ul>
-
-
-<h4 id="java_library">Arguments</h4>
-<ul>
-<li id="java_library.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="java_library.deps"><code>deps</code>:
- The list of libraries to link into this library.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- See general comments about <code>deps</code>
- at <a href="#common-attributes">Attributes common to all build rules</a>.
-
- <p>For other <code>java_library</code> rules listed in <code>deps</code>,
- the jars they build will be on the compile-time classpath for this rule;
- also, the transitive closure of their <code>deps</code>,
- <code>runtime_deps</code>, and <code>exports</code> will be on the runtime
- classpath.</p>
-
- <p>By contrast, targets in the <code>data</code> attribute are included
- in the runfiles but on neither the compile-time nor runtime classpath.</p>
-</li>
-<li id="java_library.srcs"><code>srcs</code>:
- The list of source files that are processed to create the library target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
-
- <p><code>srcs</code> files of type <code>.java</code> are compiled.
- <em>For readability's sake</em>, it is not good to put the name of a
- generated <code>.java</code> source file into the <code>srcs</code>.
- Instead, put the depended-on rule name in the <code>srcs</code>, as
- described below.
- </p>
-
- <p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
- compiled. (This is useful if you need to generate a set of .java files with
- a genrule or build extension.)
- </p>
-
- <p><code>srcs</code> files of type <code>.jar</code> are linked in.
- (This is useful if you have third-party <code>.jar</code> files
- with no source.)
- </p>
-
- <p><code>srcs</code> files of type <code>.properties</code> are treated as
- resources.</p>
-
-</li>
-<li id="java_library.data"><code>data</code>:
- The list of files needed by this library at runtime.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- See general comments about <code>data</code>
- at <a href="#common-attributes">Attributes common to all build rules</a>.
-
- <p>When building a <code>java_library</code>, the build tool
- doesn't put these files anywhere; if the <code>data</code> files are
- generated files, the build tool generates them.
- When building a test that depends upon this <code>java_library</code>,
- the build tool copies or links the <code>data</code> files into the
- runfiles area.
- </p>
-</li>
-<li id="java_library.constraints"><code>constraints</code>:
- Extra constraints imposed on this library.
- <i>(List of strings; optional)</i>
- <p>
- At the moment, the following constraints are supported:
- </p>
- <ul>
- <li><code>android</code>: Specifies that this java_library is
- Android-compatible. This means that the java_library does not
- use Java APIs not supported by Android. If a java_library is
- Android-compatible, the build tool will check that all dependent
- java_libraries are marked as Android-compatible.
- If an Android-compatible library depends on a java_library that is
- not Android-compatible an error will be generated.
- </li>
- <li><code>public</code>: Specifies that this java_library only
- includes source code and resources that can be made public.
- </li>
- </ul>
-</li>
-<li id="java_library.exported_plugins"><code>exported_plugins</code>:
- The list of <code><a href="#java_plugin">java_plugin</a></code>s
- (e.g. annotation processors) to export to libraries that directly depend
- on this library.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br />
- <p>The specified list of <code>java_plugin</code>s will be applied to any
- library which directly depends on this library, just as if that library had
- explicitly declared these labels in
- <code><a href="#java_library.plugins">plugins</a></code>.
-</li>
-<li id="java_library.exports"><code>exports</code>:
- The closure of all rules reached via <code>exports</code> attributes are
- considered direct dependencies of any rule that directly depends on the
- target with <code>exports</code>.
- <p><code>exports</code> are not direct deps of the rule they belong to.</p>
-</li>
-<li id="java_library.neverlink"><code>neverlink</code>:
- Only use this library for compilation and not at runtime.
- <i>(Boolean; optional; default is 0)</i><br/>
- Useful if the library will be provided by the runtime environment during
- execution. Examples of libraries like this are the IDE APIs for IDE
- plug-ins or <code>tools.jar</code> for anything running on a standard JDK.
- Note that <code>neverlink = 1</code> does not prevent the compiler from
- inlining material from this library into compilation targets that depend on
- it, as permitted by the Java Language Specification (e.g., <code>static
- final</code> constants of <code>String</code> or primitive type). The
- preferred use case is therefore when the runtime library is identical to
- the compilation library. If the runtime library differs from the
- compilation library, then you must ensure that it differs only in places
- that the JLS forbids compilers from inlining (and that must hold for all
- future versions of the JLS).
-</li>
-</ul>
-
-
-<h3 id="sh_library">sh_library</h3>
-
-
-<p class="rule-signature">
-sh_library(<a href="#sh_library.name">name</a>,
-<a href="#sh_library.deps">deps</a>,
-<a href="#sh_library.srcs">srcs</a>,
-<a href="#common.data">data</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
- The main use for this rule is to aggregate together a logical
- "library" consisting of related scripts—programs in an
- interpreted language that does not require compilation or linking,
- such as the Bourne shell—and any data those programs need at
- run-time. Such "libraries" can then be used from
- the <code>data</code> attribute of one or
- more <code>sh_binary</code> rules.
-</p>
-
-<p>
- Historically, a second use was to aggregate a collection of data files
- together, to ensure that they are available at runtime in
- the <code>.runfiles</code> area of one or more <code>*_binary</code>
- rules (not necessarily <code>sh_binary</code>).
- However, the <a href="#filegroup"><code>filegroup()</code></a> rule
- should be used now; it is intended to replace this use of
- <code>sh_library</code>.
-</p>
-
-<p>
- In interpreted programming languages, there's not always a clear
- distinction between "code" and "data": after all, the program is
- just "data" from the interpreter's point of view. For this reason
- (and historical accident) this rule has three attributes which are
- all essentially equivalent: <code>srcs</code>, <code>deps</code>
- and <code>data</code>.
- The recommended usage of each attribute is mentioned below. The
- current implementation does not distinguish the elements of these lists.
- All three attributes accept rules, source files and derived files.
-</p>
-
-<h4 id="sh_library">Arguments</h4>
-<ul>
-<li id="sh_library.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="sh_library.deps"><code>deps</code>:
- The list of other targets to be aggregated in to this "library" target.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- See general comments about <code>deps</code>
- at <a href="#common-attributes">Attributes common to all build rules</a>.
- You should use this attribute to list other
- <code>sh_library</code> rules that provide
- interpreted program source code depended on by the code in
- <code>srcs</code>.
-</li>
-<li id="sh_library.srcs"><code>srcs</code>:
- The list of input files.
- <i>(List of <a href="build-ref.html#labels">labels</a>,
- optional)</i><br/>
- You should use this attribute to list interpreted program
- source files that belong to this package, such as additional
- files containing Bourne shell subroutines, loaded via the shell's
- <code>source</code> or <code>.</code> command.
-</li>
-</ul>
-
-
-<h4 id="sh_library_examples">Examples</h4>
-
-<pre class="code">
-sh_library(
- name = "aggregator",
- data = [
- ":aggregator_service_script", # a sh_binary with srcs
- ":deploy_aggregator", # another sh_binary with srcs
- ],
-)
-</pre>
-
-<!-- ============================================
- test
- ============================================
--->
-<h2 id="test">*_test</h2>
-
-<p>A <code>*_test</code> rule compiles a
-test. See <a href="#common-attributes-tests">Common attributes for
-tests</a> for an explanation of the common attributes.
-
-<h3 id="android_test">android_test</h3>
-
-
-<p class="rule-signature">
-android_test(<a href="#android_test.name">name</a>,
-<a href="#android_test.deps">deps</a>,
-<a href="#android_binary.srcs">srcs</a>,
-<a href="#android_test.data">data</a>,
-<a href="#android_binary.resources">resources</a>,
-<a href="#test.args">args</a>,
-<a href="#android_binary.debug_key">debug_key</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#android_binary.dexopts">dexopts</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#test.flaky">flaky</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#test.local">local</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>,
-<a href="#android_test.proguard_specs">proguard_specs</a>,
-<a href="#test.shard_count">shard_count</a>,
-<a href="#test.size">size</a>,
-<a href="#android_binary.strict_android_deps">strict_android_deps</a>,
-<a href="#common.tags">tags</a>,
-<a href="#android_test.target_devices">target_devices</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#test.timeout">timeout</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
- A <code>android_test</code> rule runs Android tests. By default, it will
- start an emulator, install the application under test along with the test
- binary and any other needed Android binaries and run the tests defined in the
- test package. An option to run the test on an existing device is available
- to <code>target_devices</code> users when running locally.
-</p>
-<p>
- These tests require an Android device (virtual or physical) to run because
- they rely on Android libraries only available on the device.
-</p>
-
-<h4 id="android_test">Arguments</h4>
-<ul>
-<li id="android_test.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="android_test.deps"><code>deps</code>:
- The list of other libraries and binaries to be linked in to the test
- target. <i>(List of <a href="build-ref.html#labels">labels</a>; optional)
- </i>
- <p>Permitted library types are: <code>android_library</code>,
- <code>java_library</code> or <code>java_import</code>
- with <code>android</code> constraint, and
- <code>cc_library</code> wrapping or producing <code>.so</code> native
- libraries for the Android target platform.</p>
- <p><code>deps</code> of type <code>android_binary</code> are installed in
- the emulator before running the tests, and the first in the list is
- considered to be the proper application under test.
- </p>
-</li>
-<li id="android_test.data"><code>data</code>:
- A collection of artifacts to be pushed onto the device's external storage
- before the test is executed.
- <p><i>This option is only available when using <code>target_devices</code>
- attribute.</i></p>
-</li>
-<li id="android_test.proguard_specs"><code>proguard_specs</code>:
- Files to be used as Proguard specification.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- This file will describe the set of specifications to be used by Proguard.
- </p>
-</li>
-<li id="android_test.target_devices"><code>target_devices</code>:
- The <a href="#android_device">android_device</a> the test should run against.
- <i>(<a href="build-ref.html#labels">Label</a>: required)</i>
- <p>At this time only one <a href="#android_device">android_device</a>
- is allowed in the <code>target_devices</code> attribute.</p>
-</li>
-</ul>
-
-
-<h3 id="java_test">java_test</h3>
-
-
-<p class="rule-signature">
-java_test(<a href="#java_test.name">name</a>,
-<a href="#java_binary.deps">deps</a>,
-<a href="#java_binary.srcs">srcs</a>,
-<a href="#common.data">data</a>,
-<a href="#java_binary.resources">resources</a>,
-<a href="#test.args">args</a>,
-<a href="#java_binary.classpath_resources">classpath_resources</a>,
-<a href="#java_binary.create_executable">create_executable</a>,
-<a href="#java_binary.deploy_manifest_lines">deploy_manifest_lines</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#test.flaky">flaky</a>,
-<a href="#java_binary.javacopts">javacopts</a>,
-<a href="#java_binary.jvm_flags">jvm_flags</a>,
-<a href="#java_binary.launcher">launcher</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#test.local">local</a>,
-<a href="#java_binary.main_class">main_class</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#java_binary.plugins">plugins</a>,
-<a href="#java_binary.runtime_deps">runtime_deps</a>,
-<a href="#test.shard_count">shard_count</a>,
-<a href="#test.size">size</a>,
-<a href="#java_binary.stamp">stamp</a>,
-<a href="#java_binary.swigdeps">swigdeps</a>,
-<a href="#common.tags">tags</a>,
-<a href="#java_test.test_class">test_class</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#test.timeout">timeout</a>,
-<a href="#java_binary.use_testrunner">use_testrunner</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
-A <code>java_test()</code> rule compiles a Java test.
-A test is binary wrapper around your test code.
-The test runner's main method is invoked instead of
-the main class being compiled.</p>
-
-<h4 id="java_test_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>name</var>.jar</code>: A Java archive.</li>
- <li><code><var>name</var>_deploy.jar</code>: A Java archive suitable
- for deployment. (Only built if explicitly requested.)</li>
- </ul>
-
-
-<h4 id="java_test">Arguments</h4>
-<ul>
-<li id="java_test.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="java_test.test_class"><code>test_class</code>:
- The Java class to be loaded by the test runner.<br/>
- <i>(String, the fully qualified name of a Java class; optional)</i><br/>
- <p>
- This attribute specifies the name of a Java class to be run by
- this test. For JUnit3, this class needs to either be a subclass of
- <code>junit.framework.TestCase</code> or it needs to have a public
- static <code>suite()</code> method that returns a
- <code>junit.framework.Test</code> (or a subclass of <code>Test</code>).
- For JUnit4, proper
- annotations should be used. If this argument is omitted, the Java class
- whose name corresponds to the <code>name</code> of this
- <code>java_test</code> rule will be used.
- </p>
- <p>
- This attribute allows several <code>java_test</code> rules to
- share the same <code>Test</code>
- (<code>TestCase</code>, <code>TestSuite</code>, ...). Typically
- additional information is passed to it
- (e.g. via <code>jvm_flags=['-Dkey=value']</code>) so that its
- behavior differs in each case, such as running a different
- subset of the tests. This attribute also enables the use of
- Java tests outside the <code>javatests</code> tree.
- </p>
-</li>
-</ul>
-
-
-<p>
- See the section on <a href="#java_binary_args">java_binary()</a>
- arguments, with the <i>caveats</i> that
- there is no <code>main_class</code> argument.
- It also supports all <a href="#common-attributes-tests">attributes common to
- all test rules (*_test)</a>.
- <code>java_test</code> has this extra argument:</p>
-
-<h3 id="sh_test">sh_test</h3>
-
-
-<p class="rule-signature">
-sh_test(<a href="#sh_test.name">name</a>,
-<a href="#sh_binary.deps">deps</a>,
-<a href="#sh_binary.srcs">srcs</a>,
-<a href="#common.data">data</a>,
-<a href="#test.args">args</a>,
-<a href="#sh_test.bash_version">bash_version</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#test.flaky">flaky</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#test.local">local</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#test.shard_count">shard_count</a>,
-<a href="#test.size">size</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#test.timeout">timeout</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
-A <code>sh_test()</code> rule creates a test. A test is
-a wrapper around the tested code. If you're working with Perl and want to
-write a unit test, then <code>sh_test()</code> is the best
-approach (though Perl is not supported).</p>
-
-<h4 id="sh_test">Arguments</h4>
-<ul>
-<li id="sh_test.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i>
- <br/>If your main script is called <code>foo.sh</code>, we recommend
- that you name the rule <code>foo</code>, but this is not required.
-</li>
-<li id="sh_test.bash_version"><code>bash_version</code>:
- The version of bash to run this test with.
- <i>(String; optional; default is "system")</i><br/>
- Valid values are: <code>"3"</code>, <code>"4"</code>, and
- <code>"system"</code>. The first runs bash 3. The second runs
- bash 4. The third runs with the executing system's default installation.
- <p>For a non-system bash, the output executable is a custom test runner
- that invokes the source script with the correct bash. For a system bash,
- the output executable is just the original source script.</p>
-</li>
-</ul>
-
-
-<p>
-See the section on <a href="#sh_binary_args">sh_binary()</a> for other
-arguments. Also see the <a href="#common-attributes-tests">attributes common to
-all test rules (*_test)</a>.</p>
-
-<!-- ============================================
- variables
- ============================================
--->
-<h2 id="make_variables">"Make" Variables</h2>
-
-<p>
- This section describes how to use or define a special class of string
- variables that are called the "Make" environment. Bazel defines a set of
- standard "Make" variables, and you can also define your own.
-</p>
-
-<p>(The reason for the term "Make" is historical: the syntax and semantics of
- these variables are somewhat similar to those of GNU Make, and in the
- original implementation, were implemented by GNU Make. The
- scare-quotes are present because newer build tools support
- "Make" variables without being implemented using GNU Make; therefore
- it is important to read the specification below carefully to
- understand the differences.)
-</p>
-
-<p>To see the list of all common "Make" variables and their values,
- run <code>bazel info --show_make_env</code>.
-</p>
-
-<p>Build rules can introduce additional rule specific variables. One example is
- the <a href="#genrule.cmd"><code>cmd</code> attribute of a genrule</a>.
-</p>
-
-<h3 id='make-var-substitution'>"Make" variable substitution</h3>
-
-<p>Variables can be referenced in attributes and other variables using either
- <code>$(FOO)</code> or <code>varref('FOO')</code>, where <code>FOO</code> is
- the variable name. In the attribute documentation of rules, it is mentioned
- when an attribute is subject to "Make" variable substitution. For those
- attributes this means that any substrings of the form <code>$(X)</code>
- within those attributes will be interpreted as references to the "Make"
- variable <var>X</var>, and will be replaced by the appropriate value of that
- variable for the applicable build configuration. The parens may be omitted
- for variables whose name is a single character.
-</p>
-<p>
- It is an error if such attributes contain embedded strings of the
- form <code>$(X)</code> where <var>X</var> is not the name of a
- "Make" variable, or unclosed references such as <code>$(</code> not
- matched by a corresponding <code>)</code>.
-</p>
-<p>
- Within such attributes, literal dollar signs must be escaped
- as <code>$$</code> to prevent this expansion.
-</p>
-<p>
- Those attributes that are subject to this substitution are
- explicitly indicated as such in their definitions in this document.
-</p>
-
-<h3 id="predefined_variables">Predefined "Make" Variables</h3>
-
-<p>Bazel defines a set of "Make" variables for you.</p>
-
-<p>The build system also provides a consistent PATH for genrules and tests which
- need to execute shell commands. For genrules, you can indirect your commands
- using the Make variables below. For basic Unix utilities, prefer relying on
- the PATH variable to guarantee correct results. For genrules involving
- compiler and platform invocation, you must use the Make variable syntax.
- The same basic command set is also available during tests. Simply rely on the
- PATH.</p>
-
-<p>Bazel uses a tiny Unix distribution to guarantee consistent behavior of
- build and test steps which execute shell code across all build execution
- hosting environments but it does not enforce a pure chroot. As such, do
- <b>not</b> use hard coded paths, such as
- <code>/usr/bin/foo</code>. Binaries referenced in hardcoded paths are not
- hermetic and can lead to unexpected and non-reproducible build behavior.</p>
-
-<p><strong>Command Variables for genrules</strong></p>
-
-<p>Note that in general, you should simply refer to many common utilities as
-bare commands that the $PATH variable will correctly resolve to hermetic
-versions for you.</p>
-
-<p><strong>Path Variables</strong></p>
-
-<ul><!-- keep alphabetically sorted -->
- <li><code>BINDIR</code>: The base of the generated binary tree for the target
- architecture. (Note that a different tree may be used for
- programs that run during the build on the host architecture,
- to support cross-compiling. If you want to run a tool from
- within a genrule, the recommended way of specifying the path to
- the tool is to use <code>$(location <i>toolname</i>)</code>,
- where <i>toolname</i> must be listed in the <code>tools</code>
- attribute for the genrule.</li>
- <li><code>GENDIR</code>: The base of the generated code
- tree for the target architecture.</li>
- <li><code>JAVABASE</code>:
- The base directory containing the Java utilities.
- It will have a "bin" subdirectory.</li>
-</ul>
-
-<p><strong>Architecture Variables</strong></p>
-
-<ul><!-- keep alphabetically sorted -->
- <li><code>ABI</code>: The C++ ABI version. </li>
- <li><code>ANDROID_CPU</code>: The Android target architecture's cpu. </li>
- <li><code>JAVA_CPU</code>: The Java target architecture's cpu. </li>
- <li> <code>TARGET_CPU</code>: The target architecture's cpu. </li>
-</ul>
-
-<p id="predefined_variables.genrule.cmd">
- <strong>
- Other Variables available to <a href="#genrule.cmd">the cmd attribute of a genrule</a>
- </strong>
-</p>
-<ul><!-- keep alphabetically sorted -->
- <li><code>OUTS</code>: The <code>outs</code> list. If you have only one output
- file, you can also use <code>$@</code>.</li>
- <li><code>SRCS</code>: The <code>srcs</code> list (or more
- precisely, the pathnames of the files corresponding to
- labels in the <code>srcs</code> list). If you have only one
- source file, you can also use <code>$<</code>.</li>
- <li><code><</code>: <code>srcs</code>, if it is a single file.</li>
- <li><code>@</code>: <code>outs</code>, if it is a single file.</li>
- <li><code>@D</code>: The output directory. If there is only
- one filename in <code>outs</code>, this expands to the
- directory containing that file. If there are multiple
- filenames, this variable instead expands to the package's root
- directory in the <code>genfiles</code> tree, <i>even if all
- the generated files belong to the same subdirectory</i>!
- <!-- (as a consequence of the "middleman" implementation) -->
- If the genrule needs to generate temporary intermediate files
- (perhaps as a result of using some other tool like a compiler)
- then it should attempt to write the temporary files to
- <code>@D</code> (although <code>/tmp</code> will also be
- writable), and to remove any such generated temporary files.
- Especially, avoid writing to directories containing inputs -
- they may be on read-only filesystems. </li>
-</ul>
-
-</ul>
-
-<h3 id="define_your_own_make_vars">Defining Your Own Variables</h3>
-
-<p>
-You may want to use Python-style variable assignments rather than "Make"
-variables, because they work in more use cases and are less surprising. "Make"
-variables will work in the <a href="#genrule.cmd">cmd</a> attribute of genrules
-and in the key of the <a href="#cc_library.abi_deps">abi_deps</a> attribute of
-a limited number of rules, but only in very few other places.
-
-</p>
-<p>To define your "Make" own variables, first call <a
- href="#vardef">vardef()</a> to define your variable, then call <a
- href="#varref">varref(name)</a> to retrieve it. varref can be embedded as part
- of a larger string. Custom "Make" variables differ from ordinary "Python"
- variables in the BUILD language in two important ways:
-</p>
-<ul>
- <li>Only string values are supported,</li>
- <li>The "Make" environment is parameterized over the build
- platform, so that variables can be conditionally defined based on
- the target architecture, ABI or compiler, and</li>
- <li>The values of custom "Make" variables are <i>not available</i> during
- BUILD-file evaluation. To work around this, you must call <a
- href="#varref">varref()</a> to retrieve the value of a variable (unlike
- predefined values, which can be retrieved using <code>$(FOO)</code>.
- varref defers evaluation until after BUILD file evaluation.</li>
-</ul>
-
-<h4 id="vardef">vardef()</h4>
-
-<p><code>vardef(name, value, platform)</code></p>
-
- <p>
- Define a variable for use within this <code>BUILD</code> file only.
- This variable can then be used by <a href="#varref">varref()</a>.
- The value of the variable can be overridden on the command line by using the
- <code class='flag'><a href='bazel-user-manual.html#flag--define'>--define</a></code>
- flag.
- </p>
-
- <p id="vardef_args"><strong>Arguments</strong></p>
-<ul>
- <li><code>name</code>: The name of the variable.
- <i>(String; required)</i><br/>
- Convention is to use names consisting of ALL CAPS. This name must
- be a unique identifier in this package.
- </li>
- <li><code>value</code>: The value to assign to this variable.
- <i>(String; required)</i><br/>
- The value may make use of variables you know are defined in the "Make"
- environment.
- </li>
- <li><code>platform</code>: Conditionally define this variable for a given
- platform.
- <i>(String; optional)</i><br/>
-
- <code>vardef</code> binds the <code>name</code> to <code>value</code> if we're
- compiling for <code>platform</code>.
- </li>
-</ul>
-
-<p id="vardef_notes"><strong>Notes</strong></p>
-<p>
- Because references to "Make" variables are expanded <i>after</i>
- BUILD file evaluation, the relative order of <code>vardef</code>
- statements and rule declarations is unimportant; it is order of
- <code>vardef</code> statements relative to each other, and hence the
- state of the "Make" environment at the end of evaluation that
- matters.
-</p>
-<p>
- If there are multiple matching <code>vardef</code> definitions for
- the same variable, the definition that wins is
- the <strong>last</strong> matching definition
- <strong>that specifies a platform</strong>, unless there are no matching
- definitions that specify a platform, in which case the definition
- that wins is the <strong>last</strong> definition <strong>without
- a platform</strong>.
-</p>
-
-<!-- =================================================================
- varref()
- =================================================================
- -->
-
-<h4 id="varref">varref</h4>
-
-<p><code>varref(name)</code></p>
-
-<p>
-<code>varref("FOO")</code> is equivalent of writing "$(FOO)". It is used to
-dereference variables defined with <a href="#vardef"><code>vardef</code></a>
-as well as <a href="#predefined_variables">predefined variables</a>.
-</p>
-
-<p>
- In rule attributes that are subject to "Make" variable
- substitution, the string produced by <code>varref(<i>name</i>)</code>
- will expand to the value of variable <i>name</i>.
-</p>
-
-<p><code>varref(name)</code> may not be used in rule attributes that are
-not subject to "Make" variable substitution.</p>
-
-<p id="varref_args"><strong>Arguments</strong></p>
-<ul>
- <li><code>name</code>: The name of the variable to dereference.
- </li>
-</ul>
-
-<p id="varref_notes"><strong>Notes</strong></p>
-<ul>
- <li><code>varref</code> can access either local or global variables.
- It prefers the local variable, if both a local and a global exist with
- the same name.
- </li>
-</ul>
-
-<p id="varref_examples"><strong>Examples</strong></p>
-<p>See <a href="#vardef_examples">vardef()</a> examples.</p>
-
-
-<!-- ============================================
- other
- ============================================
--->
-<h2 id="misc">Other Stuff</h2>
-
-<h3 id="filegroup">filegroup</h3>
-
-
-<p class="rule-signature">
-filegroup(<a href="#filegroup.name">name</a>,
-<a href="#filegroup.srcs">srcs</a>,
-<a href="#filegroup.data">data</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#binary.output_licenses">output_licenses</a>,
-<a href="#filegroup.path">path</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>Use <code>filegroup</code> to give a convenient name to a
- collection of targets. These can then be referenced from other
- rules, e.g. the <code>srcs</code> attribute of a genrule, or
- the <code>data</code> attribute of a *_binary rule.
-</p>
-
-<p>Motivation: this mechanism aims to replace the practice of referencing
-directory names as data dependencies. Referencing directory names
-is unsound as the build system does not have full knowledge of all
-files below the directory, so it may or may not rebuild as these files
-change. When combined with <a href="#glob">glob</a>, filegroup can
-ensure that all files are explicitly known to the build system.
-</p>
-
-<h4 id="filegroup">Arguments</h4>
-<ul>
-<li id="filegroup.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="filegroup.srcs"><code>srcs</code>:
- The list of targets that are members of the file group.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
- <p>It is common to use the result of a <a href="#glob">glob</a>
- expression for the value of the <code>srcs</code> attribute.
- If a glob matches a source file with the same name as a build rule,
- the rule will override the file.
- </p>
-</li>
-<li id="filegroup.data"><code>data</code>:
- The list of files needed by this rule at runtime.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- Targets named in the <code>data</code> attribute will be considered
- belonging to the runfiles of the filegroup rule. This means in practice
- that when the filegroup is put in the <code>data</code> attribute of a
- rule, the files referred to by this attribute will also be considered to be
- data of the rule referring to the <code>filegroup</code>. See the
- <a href="build-ref.html#data">data dependencies</a> section for more
- information about how to depend on and use data files.
-</li>
-<li id="filegroup.path"><code>path</code>:
- An optional string giving a path to the files in the group.
- <i>(String; optional)</i><br/>
- This attribute is used internally by Bazel to find the name of the
- directory holding the files.
-</li>
-</ul>
-
-
-<h4 id="filegroup_example">Examples</h4>
-
-<p>
-To create a filegroup consisting of two source files, do
-</p>
-<pre class="code">
-filegroup(
- name = "mygroup",
- srcs = [
- "a_file.txt",
- "another_file.txt",
- ],
-)
-</pre>
-<p>Or, use a glob to grovel a testdata directory:</p>
-<pre class="code">
-filegroup(
- name = "exported_testdata",
- srcs = glob([
- "testdata/*.dat",
- "testdata/logs/*.log",
- ]),
-)
-</pre>
-<p>To make use of these definitions, reference the filegroup with a label
-from any rule:</p>
-<pre class="code">
-cc_library(
- name = "my_library",
- srcs = ["foo.cc"],
- data = [
- "//my_package:exported_testdata",
- "//my_package:mygroup",
- ],
-)
-</pre>
-
-
-<h3 id="test_suite">test_suite</h3>
-
-
-<p class="rule-signature">
-test_suite(<a href="#test_suite.name">name</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#test_suite.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#test_suite.tests">tests</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
-A <code>test_suite</code> defines a set of tests that are considered
-"useful" to humans. This allows projects to define sets of tests,
-such as "tests you must run before checkin", "our project's stress
-tests" or "all small tests."
-</p>
-
-<h4 id="test_suite">Arguments</h4>
-<ul>
-<li id="test_suite.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="test_suite.tags"><code>tags</code>:
- List of text tags such as "small" or "database" or "-flaky".
- Tags may be any valid string.
- <p>
- Tags which begin with a "-" character are considered negative tags. The
- preceding "-" character is not considered part of the tag, so a suite tag
- of "-small" matches a test's "small" size. All other tags are considered
- positive tags.
- </p>
- <p>
- Optionally, to make positive tags more explicit, tags may also begin with the
- "+" character, which will not be evaluated as part of the text of the tag. It
- merely makes the positive and negative distinction easier to read.
- </p>
- <p>
- Only test rules that match ALL of the positive tags and NONE of the negative
- tags will be included in the test suite. Note that this does not mean that
- error checking for dependencies on tests that are filtered out is skipped;
- you will still need to ensure that the dependencies on skipped tests are
- legal (e.g. not blocked by visibility or obsoleteness constraints)
- </p>
- <p>
- There is one exception to this rule:
- a <code>manual</code> tag keyword is used to mark the <code>test_suite</code>
- target as "manual" so that will be ignored by the wildcard
- expansion and automated testing facilities, not as a filter on the set
- of tests in the suite. So when the <code>manual</code> tag is used on a
- test_suite, test rules do not have to be tagged as <code>manual</code> to be
- included in the test suite. At this point only Bazel has proper support
- for the <code>manual</code> tag keyword. Other test runners will apply
- it as a filter, in most cases resulting in the empty test suite.
- </p>
- <p>
- Note that a test's <code>size</code> is considered a tag for the
- purpose of filtering.
- </p>
- <p>
- To create a suite containing tests with mutually exclusive tags,
- e.g. all small and medium tests,
- you need to create a <code>test_suite</code> of all small
- tests, a <code>test_suite</code> of all medium tests, and then a
- <code>test_suite</code> that includes the small and medium
- <code>test_suite</code>s.
- </p>
-</li>
-<li id="test_suite.tests"><code>tests</code>:
- A list of test suites and test targets of any language.
- <p>
- You can freely mix languages and rule styles. Thus any
- <code>*_test</code> will work, but not an <code>*_binary</code> that
- happens to run a test. Filtering by the specified <code>tags</code> will
- be applied only to the tests in this attribute, but not to test suites or
- tests included from other test suites. The <code>tests</code> and
- <code>suites</code> attributes can be used interchangeably.
- </p>
- <p>
- If the <code>tests</code> and the <code>suites</code> parameters are both
- unspecified or empty, the rule will default to including all test rules in
- the current BUILD file that are not tagged as <code>manual</code> or
- marked as <code>obsolete</code>. These rules are still subject to
- <code>tag</code> filtering.
- </p>
-</li>
-</ul>
-
-
-<h3 id="android_device">android_device</h3>
-
-
-<p class="rule-signature">
-android_device(<a href="#android_device.name">name</a>,
-<a href="#android_device.cache">cache</a>,
-<a href="#android_device.default_properties">default_properties</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#android_device.horizontal_resolution">horizontal_resolution</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#android_device.ram">ram</a>,
-<a href="#android_device.screen_density">screen_density</a>,
-<a href="#android_device.system_image">system_image</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#android_device.vertical_resolution">vertical_resolution</a>,
-<a href="#common.visibility">visibility</a>,
-<a href="#android_device.vm_heap">vm_heap</a>)
-</p>
-
-
-<p>This rule creates an android emulator configured with the given
- specifications. This emulator may be started via a bazel run
- command or by executing the generated script directly.
-</p>
-
-<h4 id="android_device_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>name</var>_images/userdata.dat</code>:
- Contains image files and snapshots to start the emulator</li>
- <li><code><var>name</var>_images/emulator-meta-data.pb</code>:
- Contains serialized information necessary to pass on to the emulator to
- restart it.</li>
- </ul>
-
-
-<h4 id="android_device">Arguments</h4>
-<ul>
-<li id="android_device.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="android_device.cache"><code>cache</code>:
- The size in megabytes of the emulator's cache partition. The minimum value
- of this is 16 megabytes.
-</li>
-<li id="android_device.default_properties"><code>default_properties</code>:
- <code>default_properties</code>
- A single properties file to be placed in /default.prop on the emulator. This
- allows the rule author to further configure the emulator to appear more like
- a real device (In particular controlling its UserAgent strings and other
- behaviour that might cause an application or server to behave differently to
- a specific device). The properties in this file will override read only
- properties typically set by the emulator such as ro.product.model.
-</li>
-<li id="android_device.horizontal_resolution"><code>horizontal_resolution</code>:
- <code>horizontal_resolution</code>:
- The horizontal screen resolution in pixels to emulate. The minimum value is 240.
-</li>
-<li id="android_device.ram"><code>ram</code>:
- The amount of ram in megabytes to emulate for the device. This is for the
- entire device, not just for a particular app installed on the device. The
- minimum value is 64 megabytes.
-</li>
-<li id="android_device.screen_density"><code>screen_density</code>:
- The density of the emulated screen in pixels per inch. The minimum value of
- this is 30 ppi.
-</li>
-<li id="android_device.system_image"><code>system_image</code>:
- A filegroup containing the following files:
- <ul>
- <li>system.img: The system partition.</li>
- <li>kernel-qemu: The Linux kernel the emliator will load</li>
- <li>ramdisk.img: The initrd image to use at boot time</li>
- <li>userdata.img: The initial userdata partition.</li>
- <li>source.properties: A properties file containing information about the
- images</li>
- </ul>
- These files are part of the android sdk or provided by third parties (for
- example Intel provides x86 images).
-</li>
-<li id="android_device.vertical_resolution"><code>vertical_resolution</code>:
- The vertical screen resolution in pixels to emulate. The minimum value is 240.
-</li>
-<li id="android_device.vm_heap"><code>vm_heap</code>:
- The size in megabytes of the virtual machine heap Android will use for each
- process. The minimum value is 16 megabytes.
-</li>
-</ul>
-
-
-<h3 id="android_manifest_merge">android_manifest_merge</h3>
-
-
-<p class="rule-signature">
-android_manifest_merge(<a href="#android_manifest_merge.name">name</a>,
-<a href="#android_manifest_merge.deps">deps</a>,
-<a href="#android_manifest_merge.srcs">srcs</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#android_manifest_merge.exclude_permissions">exclude_permissions</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>This rule merges an <code>AndroidManifest.xml</code> file with other android
- manifests that your app depends on (mergees). Other manifests might come
- from android libraries that your project depends on (e.g.: userfeedback
- library), or on your test manifest used to produce test version of your app's
- binary. Optionally, permissions from the mergees can be excluded.
-</p>
-
-<h4 id="android_manifest_merge_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>name</var>/AndroidManifest.xml</code>:
- Merged android manifest file.</li>
- </ul>
-
-
-<h4 id="android_manifest_merge">Arguments</h4>
-<ul>
-<li id="android_manifest_merge.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="android_manifest_merge.deps"><code>deps</code>:
- The list of AndroidManifest.xml files to be merged into the main
- <code>AndroidManifest.xml</code> (merger).
- <i>(List of <a href="build-ref.html#labels">labels</a>; required)</i><br/>
- <p>AndroidManifest files of type <code>.xml</code>.
- Other android_manifest_merge targets are allowed here.
- </p>
- <p>Mergee(s) will be merged into the merger. Class references from the
- mergee(s) that are not in a fully qualified format.
- </p>
- <p>Duplicates from the mergees (that also exist in the merger) will be
- omitted during the merge. (e.g.: Duplicate permissions entries)
- </p>
- <p>Mergees contribute following elements to the merger:<br>
- From Manifest element:<br>
- <code>instrumentation</code>, <code>permission</code>,
- <code>uses-permission</code>, <code>uses-feature</code><br>
- From Application element:<br>
- <code>activity</code>, <code>provider</code>, <code>receiver</code>,
- <code>service</code>, <code>uses-library</code>
- </p>
-</li>
-<li id="android_manifest_merge.srcs"><code>srcs</code>:
- The list of one manifest file to merge other manifest files (mergees) into.
- <i>(<a href="build-ref.html#labels">labels</a>; required)</i>
- <p>AndroidManifest file of type <code>.xml</code>.
- Usually it is your main app's manifest. This is the merger manifest file -
- Manifest that other manifests (mergees) would be merged into.
- Your app will use merger's package name, versioning, application attributes
- and permissions. This srcs list is allowed to have only one label.
- </p>
-</li>
-<li id="android_manifest_merge.exclude_permissions"><code>exclude_permissions</code>:
- <code>exclude_permissions</code>:
- The permission(s) to be excluded from the mergee(s).
- <i>(List of strings; optional)</i><br/>
- If specified, permissions in the list will be excluded from all the mergees.
- If an excluded permission is in merger, then it will remain in the resulting
- merged manifest.
-</li>
-</ul>
-
-
-<h3 id="android_resources">android_resources</h3>
-
-
-<p class="rule-signature">
-android_resources(<a href="#android_resources.name">name</a>,
-<a href="#android_resources.resources">resources</a>,
-<a href="#android_resources.assets">assets</a>,
-<a href="#android_resources.assets_dir">assets_dir</a>,
-<a href="#android_resources.custom_package">custom_package</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#android_resources.exports_manifest">exports_manifest</a>,
-<a href="#android_resources.inline_constants">inline_constants</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#android_resources.manifest">manifest</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#android_resources.rename_manifest_package">rename_manifest_package</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>
- Generates <code><var>name</var>.srcjar</code> which contains R.java,
- Manifest.java and any other java resources generated by aapt.
-</p>
-
-<h4 id="android_resources_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>name</var>.srcjar</code>: A <code>.srcjar</code> file
- containing all java generated sources.</li>
- <li><code><var>name</var>.ap_</code>: An Android application package file
- containing the manifest, all resources and assets.</li>
- </ul>
-
-
-<h4 id="android_resources">Arguments</h4>
-<ul>
-<li id="android_resources.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="android_resources.resources"><code>resources</code>:
- The list of resources to be packaged.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/><br/>
- This is typically a <code>glob</code> of all files under the
- <code>res</code> directory.
- If you depend on resources in other packages, you should reference their
- rules or exported files here. This enables bazel to resolve any conflicts
- with file names or attribute names.<br/>
- The only restriction is that the outputs must be under the
- same directory in the corresponding package.
-</li>
-<li id="android_resources.assets"><code>assets</code>:
- The list of assets to be packaged.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
- This is typically a <code>glob</code> of all files under the
- <code>assets</code> directory. You can also reference other rules or
- exported files in the other packages, as long as all their outputs are
- under the <code>assets_dir</code> directory in the corresponding package.
-</li>
-<li id="android_resources.assets_dir"><code>assets_dir</code>:
- The string giving the path to the files in <code>assets</code>.
- <i>(String; optional)</i><br/>
- The pair <code>assets</code> and <code>assets_dir</code> describe packaged
- assets and either both attributes should be provided or none of them.
-</li>
-<li id="android_resources.custom_package"><code>custom_package</code>:
- Java package for which java sources will be generated.
- <i>(String; optional)</i><br/>
- By default the package is inferred from the directory where the BUILD file
- containing the rule is. You can specify a different package but this is
- highly discouraged since it can introduce classpath conflicts with other
- libraries that will only be detected at runtime.
-</li>
-<li id="android_resources.exports_manifest"><code>exports_manifest</code>:
- Whether to export manifest entries to <code>android_binary</code> targets
- that depend on this target. <code>uses-permissions</code> attributes are never exported.
- <i>(Boolean; optional; default is 0)</i><br/>
-</li>
-<li id="android_resources.inline_constants"><code>inline_constants</code>:
- Let the compiler inline the constants defined in the generated java sources.
- <i>(Boolean; optional; default is 1)</i><br/>
- This attribute must be set to 0 for all <code>android_resources</code> rules
- used directly by an <code>android_library</code> (android library project)
- and for any <code>android_binary</code> that has an android library project
- in its transitive closure.
-</li>
-<li id="android_resources.manifest"><code>manifest</code>:
- The name of the Android manifest file.
- Current Android toolchain expects <code>AndroidManifest.xml</code> name.
- <i>(<a href="build-ref.html#labels">Label</a>; required)</i><br/>
-</li>
-<li id="android_resources.rename_manifest_package"><code>rename_manifest_package</code>:
- Changes the app package name.
- <i>(String; optional)</i><br/>
- Default package name is specified in your AndroidManifest.xml under package
- attribute, and that will be used if this attribute is not specified.
- Passes the value to aapt flag --rename-manifest-package. Rewrite the
- manifest so that its package name is the package name given here.
- Relative class names (for example .Foo) will be changed to absolute names
- with the old package so that the code does not need to change. This is to
- be used if desired outcome is to rename the package to other than the
- actual package is, without modifying the AndroidManifest.xml, class paths
- or code. This allows releasing the app under different name in the
- android market.
-</li>
-</ul>
-
-
-<h4 id="android_resources_examples">Examples</h4>
-<p>Please see examples under
-<a href="#android_binary_examples">android_binary</a>.</p>
-
-<p>Here is an example of combining multiple assets sources. Let
-<code>//java/android/o/BUILD</code> contain</p>
-<pre class="code">
-exports_files(["assets/other"])
-</pre>
-<p>Then in the other package you can say:</p>
-<pre class="code">
-android_resources(
- name = "r",
- assets = [
- "assets/source",
- "//java/android/o:assets/other",
- ],
- assets_dir = "assets",
- manifest = "AndroidManifest.xml",
-)
-</pre>
-<pre class="code">
-android_resources(
- name = "r",
- assets = glob(["assets/**"])
- assets_dir = "moreassets",
- manifest = "AndroidManifest.xml",
-)
-</pre>
-
-<h3 id="genrule">genrule</h3>
-
-
-<p class="rule-signature">
-genrule(<a href="#genrule.name">name</a>,
-<a href="#genrule.srcs">srcs</a>,
-<a href="#genrule.outs">outs</a>,
-<a href="#genrule.cmd">cmd</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#genrule.executable">executable</a>,
-<a href="#genrule.heuristic_label_expansion">heuristic_label_expansion</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#genrule.local">local</a>,
-<a href="#genrule.message">message</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#genrule.output_licenses">output_licenses</a>,
-<a href="#genrule.output_to_bindir">output_to_bindir</a>,
-<a href="#genrule.stamp">stamp</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#genrule.tools">tools</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
-<p>A <code>genrule</code> generates one or more files, where the generation of
- those files is done with custom shell commands running in bash. While this
- makes them very flexible, they are also difficult to use correctly.
-</p>
-
-<h4>When not to use a genrule?</h4>
-
-<ul>
- <li>Do not use a genrule for running tests - there are special dispensations
- for tests and test results, including caching policies and environment
- variables. Tests generally need to be run for the target architecture,
- possibly on special machines, whereas genrules are run during
- the build. If you need a general purpose testing rule, use sh_test.
- <li>If there is a more specific rule, use that. All the heavy
- lifting has already been done for you. For example, most built-in binary rules
- already have support stamping - file a bug if the existing support is
- insufficient.
-</ul>
-
-<h4>Cross-compilation Considerations</h4>
-
-<p>While genrules run during a build, their outputs are often used after the
- build, for deployment or testing. The build system uses the host configuration to describe
- the machines on
- which the build runs, and the target configuration to describe the machines on
- which the output of the build is supposed to run. It provides options to
- configure each of these, and it segregates the corresponding files into
- separate directories to avoid conflicts.
-</p>
-<p>For genrules, the build system ensures that dependencies are built
- appropriately - <code>srcs</code> are built (if necessary) for the target
- configuration, tools are built for the host configuration, and the output is
- considered to be for the target configuration. It also provides
- <a href="#make_variables">"Make" variable</a> that genrule
- commands can pass to the corresponding tools.
-</p>
-<p>It is intentional that genrule does not have a deps attribute - other
- built-in rules use language-dependent meta information passed between the
- rules to automatically determine how to handle dependent rules, but this level
- of automation is not possible for genrules. Genrules work purely at the file
- and runfiles level.
-</p>
-
-<h4>Special Cases</h4>
-
-<p><i>Host-host compilation</i> - in some cases, the build system needs to run
- genrules such that the output can also be run during the build. In that case,
- the build system automatically builds the <code>srcs</code> and
- <code>outs</code> for the host configuration, and sets the variables
- accordingly.
-</p>
-
-<h4>Genrule Environment</h4>
-
-<p>Genrules are executed in a sandbox that only allows access to declared
- inputs. Genrules that are run locally are currently an exception, but this may
- change in the future, i.e., local genrules will also be run in a sandbox. The
- declared output files from a genrule are copied out of the sandbox, whereas
- all other files are dropped.
-</p>
-<p>Furthermore, the build system sets environment variables it sets
- <code>PATH</code> to point to a set of standard utilities). At least awk, bash, echo, diff, find,
- grep, gzip, m4, md5sum, patch, perl, sed, tar, and xargs are provided.
- It sets <code>LANG</code> to <code>en_US</code>. No other
- environment variables are set; in particular, no environment variables are
- passed through from the build system invocation.
-</p>
-<p>The genrule command is executed in a bash shell. The bash
- shell is configured to fail when a command fails (<code>set -e</code>); at
- some point in the future, it will also fail when a command in a pipline fails
- (<code>set -o pipefail</code>). Genrules should not access the network (except
- to create connections between processes running within the same genrule on the
- same machine), though this is not currently enforced in all cases.
-</p>
-<p>The build system automatically deletes any existing output files, but creates
- any necessary parent directories before it runs a genrule. It also removes any
- output files in case of a failure.
-</p>
-
-<h4>General Advice</h4>
-
-<ul>
- <li>Do ensure that tools run by a genrule are deterministic and hermetic. They
- should not write timestamps to their output, use stable ordering for sets and
- maps, as well as only write relative paths to output.
- <li>Do use <code>$(location)</code> extensively, including for outputs and
- sources. Due to the segregation of output files for different
- configurations, genrules cannot rely on hard-coded paths.
- <li>Do make sure that the exit code correctly indicates success or failure of
- the genrule.
- <li>Do refer directly to the output file or files of a genrule from other
- rules, rather than to the genrule itself; the build system figures out
- automatically that it has to run the genrule.
- <li>Do extract the genrule command into a separate script or rewrite it as a
- binary if it becomes too long. This also improves testability.
- <li>Do not write informational messages to stdout or stderr. While useful for
- debugging, this is generally considered noise; a successful genrule should
- be silent. On the other hand, a failing genrule should emit good error
- messages.
- <li><code>$$</code> evaluates to a <code>$</code>, a literal dollar-sign - so,
- to invoke a shell command containing dollar-signs such as
- <code>ls $(dirname $x)</code>, one must escape it thus:
- <code>ls $$(dirname $$x)</code>.
- <li>Do not create symlinks or directories, or, if you must,
- use <code>local = 1</code> at your own risk.
-</ul>
-
-<h4 id="genrule">Arguments</h4>
-<ul>
-<li id="genrule.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i> <br/>You may refer to this rule by name in the
- <code>srcs</code> or <code>deps</code> section of other <code>BUILD</code>
- rules. If the rule generates source files, you should use the
- <code>srcs</code> attribute.
-</li>
-<li id="genrule.srcs"><code>srcs</code>:
- A list of inputs for this rule.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
- <p>The build system ensures these prerequisites are built before
- running the genrule command; they are built using the same
- configuration as the original build request. The names of the
- files of these prerequisites are available to the command as a
- space-separated list in <code>$(SRCS)</code>; alternatively the
- path of an individual <code>srcs</code> target <code>//x:y</code>
- can be obtained using <code>$(location //x:y)</code>.</p>
- <p>Most rules, when used in <code>genrule.srcs</code>, behave the same way:
- their outputs are made available to the <code>genrule</code>.</p>
-</li>
-<li id="genrule.outs"><code>outs</code>:
- A list of files generated by this command.
- <i>(List of <a href="build-ref.html#filename">filenames</a>; required)</i><br/>
- <p>All output files must be generated into the same directory and must not
- cross package boundaries.
- Output filenames are interpreted as relative to the package root.</p>
- <p>If the <code>executable</code> flag is set, <code>outs</code> must
- contain exactly one label.</p>
-</li>
-<li id="genrule.cmd"><code>cmd</code>:
- The command to run.
- <i>(String; required; subject to
- <a href="#make_variables">"Make" variable</a> substitution.)</i><br/>
- <ol>
- <li>
- Firstly, all occurrences of <code>$(location
- <i>label</i>)</code> are replaced by the path to the file
- denoted by <i>label</i>. If <i>label</i> is malformed, or
- not a declared dependency of this rule, or expands to a
- number of files other than exactly one, an error is raised.
- <i>label</i> need not be in canonical form:
- <code>foo</code>, <code>:foo</code> and
- <code>//thispkg:foo</code> are all equivalent. It may also
- be the name of an output file from the <code>outs</code>
- attribute, in which case only the unqualified
- form <code>foo</code> (no <code>//</code>
- or <code>:</code>) may be used.
- </li>
- <li>
- Secondly, all occurrences of <code>$(locations
- <i>label</i>)</code> are replaced by the space separated paths
- to the files denoted by <i>label</i>. If <i>label</i> is malformed,
- or not a declared dependency of this rule, or expands to no
- files, an error is raised.
- <p>This is essentially the same substitution as
- <code>$(location)</code>, but without the upper limit on the
- number of files.</p>
- </li>
- <li>
- <p>Thirdly, if <code>heuristic_label_expansion</code> is enabled, a
- heuristic pass is applied to the string to replace all occurrences of
- the labels occurring in the <code>srcs</code>, <code>tools</code> and
- <code>data</code> attributes of the rule, by their
- corresponding filenames.</p>
- <p>(In effect, this is the same substitution as
- <code>$(location)</code>, but in some cases, the heuristic
- may fail to detect certain labels, for example, when
- constructing a command-line such as <code>$(JAVA) -classpath
- <i>label1</i>:<i>label2</i>:<i>label3</i> foo.jar</code>.
- We recommend that in all new code, the explicit
- <code>$(location)</code> form is used in preference to the
- heuristic.)</p>
- <p>Note that <code>outs</code> are <i>not</i> included in
- this substitution. Output files are
- always generated into a predictable location (available via
- <code>$(@D)</code>, see below).</p>
- </li>
- <li>
- Next, <a href="#make_variables">"Make" variables</a> are expanded. Note
- that predefined variables <code>$(JAVA)</code>, <code>$(JAVAC)</code> and
- <code>$(JAVABASE)</code> expand under the
- <i>host</i> configuration, so Java invocations that run as part of a
- build step can correctly load shared libraries and other dependencies.
- </li>
- <li>
- Finally, the resulting command is executed using the Bash
- shell. If its exit-status is non-zero, the command is
- considered to have failed.
- </li>
- </ol>
- <p>
- The command may refer to binaries; it should use a <a
- href="build-ref.html#labels">label</a> for this. The following
- variables are available within the <code>cmd</code> sublanguage:</p>
- <ul>
- <li>
- <a href="#predefined_variables.genrule.cmd">"Make" variables</a>
- </li>
- <li>
- Variables defined in the BUILD file (using <code>vardef</code>).
- </li>
- <li>
- "Make" variables that are predefined by the build tools.
- Please use these variables instead of hardcoded values.
- See <a href="#predefined_variables">Predefined "Make" Variables</a> in
- this document for a list of supported values.
- </li>
- </ul>
-</li>
-<li id="genrule.executable"><code>executable</code>:
- Declare output to be executable.
- <i>(Boolean; optional; default is 0)</i> <br/>
- <p>Setting this flag to 1 means the output is an executable file and can be
- run using the <code>bazel run</code> command. The genrule must produce
- exactly one output in this case. If this attribute is set, <code>bazel
- run</code> will try executing the file regardless of its file type.</p>
- <p>Note that for legacy compatibility the use of this attribute is not
- always necessary for <code>bazel run</code> to work. If the output is
- <ul>
- <li>a Shell Script (<code>.sh</code>),</li>
- <li>has no extension at all,</li>
- </ul>
- then <code>bazel run</code> will execute the target even if this flag is
- set to 0 or unset. For new targets, please explicitly specify this
- attribute as needed.</p>
- <p>Unfortunately there is no way to declare data dependencies yet (but it
- is being worked on).</p>
-</li>
-<li id="genrule.heuristic_label_expansion"><code>heuristic_label_expansion</code>:
- Whether to perform heuristic label expansion
- <i>(Boolean; optional; default is true)</i><br/>
- If disabled, bazel does not attempt to find labels in the command. Instead,
- you must use the location function <code>$(location)</code> to expand
- labels.
-</li>
-<li id="genrule.message"><code>message</code>:
- A progress message
- <i>(String; optional)</i><br/>
- A progress message that will be printed as this build step is
- executed. By default, the message is "Generating <i>output</i>"
- (or something equally bland) but you may provide a more specific
- one. Use this attribute instead of <code>echo</code> or other
- print statements in your <code>cmd</code> command, as this allows
- the build tool to control whether such progress messages are
- printed or not.
-</li>
-<li id="genrule.output_licenses"><code>output_licenses</code>:
- See <a href="#binary.output_licenses"><code>common attributes</code></a>
-</li>
-<li id="genrule.output_to_bindir"><code>output_to_bindir</code>:
- Place output files in the <code>bin</code> directory.
- <i>(Boolean; optional; default is 0)</i> <br/>
- If set to 1, this option causes output files to be written into the
- <code>bin</code> directory instead of the <code>genfiles</code> directory.
-</li>
-<li id="genrule.stamp"><code>stamp</code>:
- Whether to give access to build stamp information to the genrule
- <i>(Boolean; optional; default is false)</i><br/>
- The possible values are:
- <ul>
- <li><code>stamp = 1</code>: Always make the build information available to
- the genrule. Use this with caution, since this potentially affects
- caching if many things depend on this genrule.</li>
- <li><code>stamp = 0</code>: Never make build information available to
- the genrule.</li>
- </ul>
- <p>The build information files are available as
- <code>bazel-out/build-info.txt</code> and
- <code>bazel-out/build-changelist.txt</code>.</p>
- <p>Note that the handling of this attribute is different from that of every
- other rule.</p>
-</li>
-<li id="genrule.tools"><code>tools</code>:
- A list of <i>tool</i> dependencies for this rule.
- <i>(List of
- <a href="build-ref.html#labels">labels</a>; optional)</i><br />
- See the definition of <a href="build-ref.html#deps">dependencies</a> for
- more information. <br/>
- The build system ensures these prerequisites are built before
- running the genrule command; they are built using the <a
- href='bazel-user-manual.html#configurations'><i>host</i>
- configuration</a>, since they must run on your workstation during the
- build itself. The path of an individual <code>tools</code>
- target <code>//x:y</code> can be obtained using <code>$(location
- //x:y)</code>.
- Any binaries or tools to be executed by <code>cmd</code>
- must appear in this list, not in <code>srcs</code>, to ensure they
- are built in the correct configuration.
-</li>
-</ul>
-
-
-<h4 id="genrule_examples">Examples</h4>
-
-<p>The following example shows how to process
-
-<pre class="code">
-genrule(
- name = "concat_all_files",
- srcs = [
- "//some:file",
- "//other:file",
- ],
- outs = ["concatenated.txt"],
- cmd = "cat $(location //some:file) $(location //other:file) > $@"
-)
-</pre>
-
-<h3 id="java_plugin">java_plugin</h3>
-
-
-<p class="rule-signature">
-java_plugin(<a href="#java_plugin.name">name</a>,
-<a href="#java_library.deps">deps</a>,
-<a href="#java_library.srcs">srcs</a>,
-<a href="#java_library.data">data</a>,
-<a href="#java_binary.resources">resources</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#java_plugin.generates_api">generates_api</a>,
-<a href="#java_binary.javacopts">javacopts</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#java_library.neverlink">neverlink</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#java_binary.plugins">plugins</a>,
-<a href="#java_plugin.processor_class">processor_class</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
- <p>
- java_plugin() defines plugins for the Java compiler run by Bazel.
- At the moment, the only supported kind of plugins are annotation
- processors. A <code>java_library</code> or <code>java_binary</code>
- rule can run plugins by depending on them via the
- <code>plugins</code> attribute. A <code>java_library</code> can also export
- plugins automatically to libraries that directly depend on it using
- <code><a href="#java_library.exported_plugins">exported_plugins</a></code>.
- </p>
-
-<h4 id="java_plugin_implicit_outputs">Implicit output targets</h4>
- <ul>
- <li><code><var>libname</var>.jar</code>: A Java archive.</li>
- </ul>
-
-
-<h4 id="java_plugin">Arguments</h4>
-<ul>
-<li id="java_plugin.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="java_plugin.generates_api"><code>generates_api</code>:
- This attribute marks annotation processors that generate API code.
- <i>(Boolean; optional, default is 0)</i><br/>
- If a rule uses an API-generating annotation processor, other rules
- depending on it can refer to the generated code only if their compilation
- actions are scheduled after the generating rule, which happens with
- --nouse_src_ijars. This attribute instructs Bazel to introduce scheduling
- constraints when --use_src_ijars is enabled.
-</li>
-<li id="java_plugin.processor_class"><code>processor_class</code>:
- <i>(<a href="build-ref.html#name">Name</a>; optional)</i><br/>
- The processor class is the fully qualified type of the class that the Java
- compiler should use as entry point to the annotation processor.
- If not specified, the <code>java_plugin</code> will not contribute an
- annotation processor to the Java compiler's annotation processing,
- but its runtime classpath will still be included on the compiler's
- annotation processor path.
-</li>
-</ul>
-
-
-<p>Arguments are identical to <a href="#java_library">java_library()</a>,
-except for the addition of the <code>processor_class</code> argument.</p>
-
-<h3 id="java_wrap_cc">java_wrap_cc</h3>
-
-
-<p class="rule-signature">
-java_wrap_cc(<a href="#java_wrap_cc.name">name</a>,
-<a href="#java_wrap_cc.deps">deps</a>,
-<a href="#java_wrap_cc.srcs">srcs</a>,
-<a href="#common.data">data</a>,
-<a href="#cc_binary.copts">copts</a>,
-<a href="#common.deprecation">deprecation</a>,
-<a href="#common.distribs">distribs</a>,
-<a href="#java_wrap_cc.javacopts">javacopts</a>,
-<a href="#java_wrap_cc.legacy_override_module">legacy_override_module</a>,
-<a href="#common.licenses">licenses</a>,
-<a href="#common.obsolete">obsolete</a>,
-<a href="#java_wrap_cc.package">package</a>,
-<a href="#cc_binary.plugins">plugins</a>,
-<a href="#java_wrap_cc.swig_includes">swig_includes</a>,
-<a href="#java_wrap_cc.swig_top">swig_top</a>,
-<a href="#common.tags">tags</a>,
-<a href="#common.testonly">testonly</a>,
-<a href="#common.visibility">visibility</a>)
-</p>
-
-
- <p>
- java_wrap_cc() turns a <code>.swig</code> file and some C++ libraries into
- a Java swigging. The outputs are a static archive file and a Java archive that
- provides the Java interface. The archive file is linked into the swigdeps.so
- shared library, or if using a <a href="#java_binary.launcher">java launcher</a>,
- linked into the launcher itself.
- </p>
-
-<h4 id="java_wrap_cc_implicit_outputs">Implicit output targets</h4>
- <ul><li><code>lib<var>name</var>.jar</code>: A Java archive.</li></ul>
-
-
-<h4 id="java_wrap_cc">Arguments</h4>
-<ul>
-<li id="java_wrap_cc.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
-<li id="java_wrap_cc.deps"><code>deps</code>:
- The libraries to compile into the module.
- <i>(List of <a href="build-ref.html#labels">labels</a>; required)</i><br/>
- See general comments about <code>deps</code>
- at <a href="#common-attributes">Attributes common to all build
- rules</a>.
- These can be C++ libraries, Java libraries, or other
- <code>java_wrap_cc</code> rules. Plain files such as <code>.i</code> or
- <code>.swig</code> files are currently also allowed, but should be avoided,
- if possible.
-</li>
-<li id="java_wrap_cc.srcs"><code>srcs</code>:
- A list of one <code>swig</code> source.
- <i>(List of <a href="build-ref.html#labels">labels</a>; required)</i>
-</li>
-<li id="java_wrap_cc.javacopts"><code>javacopts</code>:
- See <a href="#java_binary.javacopts"><code>java_binary</code></a>
-</li>
-<li id="java_wrap_cc.legacy_override_module"><code>legacy_override_module</code>:
- <i>(Boolean; optional; default 1)</i><br/>
- By default, the <code>-module main</code> option is passed to the swig tool,
- which overrides any module declaration in the source file. This option can
- be used to disable that behavior.
-</li>
-<li id="java_wrap_cc.package"><code>package</code>:
- <i>(String; optional; default current_package.target_name)</i><br/>
- The package of the generated Java classes.
-</li>
-<li id="java_wrap_cc.swig_includes"><code>swig_includes</code>:
- <i>(Label list; optional)</i><br/>
- List of files that are included by the swig file.
-</li>
-<li id="java_wrap_cc.swig_top"><code>swig_top</code>:
- <i>(Label; optional)</i><br/>
- Label of a <a href="#filegroup"><code>filegroup</code></a> containing
- the file <code>swig</code>.
-</li>
-</ul>
-
-
-<!-- =================================================================
- package()
- =================================================================
--->
-
-<h3 id="package">package</h3>
-
-<p>This function declares metadata that applies to every subsequent rule in the
-package.</p>
-
-<p>The <a href="build-ref.html#package">package</a>
- function is used at most once within a build package (BUILD file).
- It is recommended that the package function is called at the top of the
- file, before any rule.</p>
-
-<h4 id="package_args">Arguments</h4>
-
-<ul>
-
- <li id="package.default_visibility"><code>default_visibility</code>:
- The default visibility of the rules in this package.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
-
- <p>Every rule in this package has the visibility specified in this
- attribute, unless otherwise specified in the <code>visibility</code>
- attribute of the rule. For detailed information about the syntax of this
- attribute, see the documentation of the <a href="#common.visibility">visibility</a>
- attribute.
- </li>
-
- <li id="package.default_obsolete"><code>default_obsolete</code>:
- The default value of <a href="#common.obsolete"><code>obsolete</code></a> property
- for all rules in this package. <i>(Boolean; optional; default is 0)</i>
- </li>
-
- <li id="package.default_deprecation"><code>default_deprecation</code>:
- Sets the default <a href="#common.deprecation"><code>deprecation</code></a> message
- for all rules in this package. <i>(String; optional)</i>
- </li>
-
- <li id="package.default_testonly"><code>default_testonly</code>:
- Sets the default <a href="#common.testonly"><code>testonly</code></a> property
- for all rules in this package. <i>(Boolean; optional; default is 0 except as noted)</i>
-
- <p>In packages under <code>javatests</code> the default value is 1.</p>
- </li>
-
-</ul>
-
-<h4 id="package_example">Examples</h4>
-
-The declaration below declares that the rules in this package are
-visible only to members of package
-group <code>//foo:target</code>. Individual visibility declarations
-on a rule, if present, override this specification.
-
-<pre class="code">
-package(default_visibility = ["//foo:target"])
-</pre>
-
-<!-- =================================================================
- package_group()
- =================================================================
--->
-
-<h3 id="package_group">package_group</h3>
-
-<p><code>package_group(name, packages, includes)</code></p>
-
-<p>This function defines a set of build packages.
-
-Package groups are used for visibility control. You can grant access to a rule
-to one or more package groups, every rule, or only to rules declared
-in the same package. For more detailed description of the visibility system, see
-the <a href="#common.visibility">visibility</a> attribute.
-
-<h4 id="package_group_args">Arguments</h4>
-
-<ul>
- <li id="package_group.name"><code>name</code>:
- A unique name for this rule.
- <i>(<a href="build-ref.html#name">Name</a>; required)</i>
- </li>
-
- <li id="package_group.packages"><code>packages</code>:
- A complete enumeration of packages in this group.
- <i>(List of <a href="build-ref.html#s4">Package</a>; optional)</i><br/>
-
- <p>Packages should be referred to using their full names,
- starting with a double slash. For
- example, <code>//foo/bar/main</code> is a valid element
- of this list.</p>
-
- <p>You can also specify wildcards: the specification
- <code>//foo/...</code> specifies every package under
- <code>//foo</code>, including <code>//foo</code> itself.
-
- <p>If this attribute is missing, the package group itself will contain
- no packages (but it can still include other package groups).</p>
- </li>
-
- <li id="package_group.includes"><code>includes</code>:
- Other package groups that are included in this one.
- <i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
-
- <p>The labels in this attribute must refer to other package
- groups. Packages in referenced package groups are taken to be part
- of this package group. This is transitive, that is, if package
- group <code>a</code> contains package group <code>b</code>,
- and <code>b</code> contains package group <code>c</code>, every
- package in <code>c</code> will also be a member of <code>a</code>.</p>
- </li>
-</ul>
-
-
-<h4 id="package_group_example">Examples</h4>
-
-The following <code>package_group</code> declaration specifies a
-package group called "tropical" that contains tropical fruits.
-
-<pre class="code">
-package_group(
- name = "tropical",
- packages = [
- "//fruits/mango",
- "//fruits/orange",
- "//fruits/papaya/...",
- ],
-)
-</pre>
-
-The following declarations specify the package groups of a fictional
-application:
-
-<pre class="code">
-package_group(
- name = "fooapp",
- includes = [
- ":controller",
- ":model",
- ":view",
- ],
-)
-
-package_group(
- name = "model",
- packages = ["//fooapp/database"],
-)
-
-package_group(
- name = "view",
- packages = [
- "//fooapp/swingui",
- "//fooapp/webui",
- ],
-)
-
-package_group(
- name = "controller",
- packages = ["//fooapp/algorithm"],
-)
-</pre>
-
-
-<!-- =================================================================
- DESCRIPTION
- =================================================================
- -->
-
-<h3 id="description">Description</h3>
-
-<p><code># Description: <var>...</var></code></p>
-
- <p>
- Each BUILD file should contain a <code>Description</code> comment.
- </p>
-
- <p>
- Description comments may contain references to other
- documentation. A string that starts with "http" will become a
- link. HTML markup is
- allowed in description comments, but please keep the BUILD files readable.
- We encourage you to list the URLs of relevant design docs and howtos
- in these description comments.
- </p>
-
-<h3 id="distribs">distribs</h3>
-
-<p><code>distribs(distrib_methods)</code></p>
-
-<p><code>distribs()</code> specifies the default distribution method (or
- methods) of the build rules in a <code>BUILD</code> file. The <code>distribs()</code>
- directive
- should appear close to the beginning of the <code>BUILD</code> file,
- before any build rules, as it sets the <code>BUILD</code>-file scope
- default for build rule distribution methods.
-</p>
-
-<h4 id="distribs_args">Arguments</h4>
-
-<p>The argument, <code id="distribs.distrib_methods">distrib_methods</code>,
- is a list of distribution-method strings.
-</p>
-
-<!-- =================================================================
- exports_files([label, ...])
- =================================================================
- -->
-
-<h3 id="exports_files">exports_files</h3>
-
-<p><code>exports_files([<i>label</i>, ...], visibility, licenses)</code></p>
-
-<p>
- <code>exports_files()</code> specifies a list of files belonging to
- this package that are exported to other packages but not otherwise
- mentioned in the BUILD file.
-</p>
-
-<p>
- The BUILD file for a package may only refer to files belonging to another
- package if they are mentioned somewhere in the other packages's BUILD file,
- whether as an input to a rule or an explicit or implicit output from a rule.
- The remaining files are not associated with a specific rule but are just "data",
- and for these, <code>exports_files</code> ensures that they may be referenced by
- other packages. (One kind of data for which this is particularly useful are
- shell and Perl scripts.)
-</p>
-
-<p>
- Note: A BUILD file only consisting of <code>exports_files()</code> statements
- is needless though, as there are no BUILD rules that could own any files.
- The files listed can already be accessed through the containing package and
- exported from there if needed.
-</p>
-
-<h4 id="exports_files_args">Arguments</h4>
-
-<p>
- The argument is a list of names of files within the current package. A
- visibility declaration can also be specified; in this case, the files will be
- visible to the targets specified. If no visibility is specified, the files
- will be visible to every package, even if a package default visibility was
- specified in the <code><a href="#package">package</a></code> function. The
- <a href="#common.licenses">licenses</a> can also be specified.
-</p>
-
-<!-- =================================================================
- glob()
- =================================================================
- -->
-
-<h3 id="glob">glob</h3>
-
-<p><code>glob(include, exclude=[], exclude_directories=1)</code>
-</p>
-
-<p>
-Glob is a helper function that can be used anywhere a list of filenames
-is expected. It takes one or two lists of filename patterns containing
-the <code>*</code> wildcard: as per the Unix shell, this wildcard
-matches any string excluding the directory separator <code>/</code>.
-In addition filename patterns can contain the recursive <code>**</code>
-wildcard. This wildcard will match zero or more complete
-path segments separated by the directory separator <code>/</code>.
-This wildcard can only be used as a complete path segment. For example,
-<code>"x/**/*.java"</code> is legal, but <code>"test**/testdata.xml"</code>
-and <code>"**.java"</code> are both illegal. No other wildcards are supported.
-</p>
-<p>
-Glob returns a list of every file in the current build package that:
-</p>
-<ul>
- <li style="margin-bottom: 0">
- Matches at least one pattern in <code>include</code>. </li>
- <li>
- Does not match any of the patterns in <code>exclude</code> (default []).</li>
-</ul>
-<p>
-If the <code>exclude_directories</code> argument is enabled (1), files of
-type directory will be omitted from the results (default 1).
-</p>
-<p>
-There are several important limitations and caveats:
-</p>
-
-<ol>
- <li>
- Globs only match files in your source tree, never
- generated files. If you are building a target that requires both
- source and generated files, create an explicit list of generated
- files, and use <code>+</code> to add it to the result of the
- <code>glob()</code> call.
- </li>
-
- <li>
- Globs may match files in subdirectories. And subdirectory names
- may be wildcarded. However...
- </li>
-
- <li>
- Labels are not allowed to cross the package boundary and glob does
- not match files in subpackages.
-
- For example, the glob expression <code>**/*.cc</code> in package
- <code>x</code> does not include <code>x/y/z.cc</code> if
- <code>x/y</code> exists as a package (either as
- <code>x/y/BUILD</code>, or somewhere else on the package-path). This
- means that the result of the glob expression actually depends on the
- existence of BUILD files — that is, the same glob expression would
- include <code>x/y/z.cc</code> if there was no package called
- <code>x/y</code>.
- </li>
-
- <li>
- The restriction above applies to all glob expressions,
- no matter which wildcards they use.
- </li>
-</ol>
-
-<p>
-In general, you should <b>try to provide an appropriate extension (e.g. *.html)
-instead of using a bare '*'</b> for a glob pattern. The more explicit name
-is both self documenting and ensures that you don't accidentally match backup
-files, or emacs/vi/... auto-save files.
-</p>
-
-<h4 id="glob_example">Glob Examples</h4>
-
-<p>Include all txt files in directory testdata except experimental.txt.
-Note that files in subdirectories of testdata will not be included. If
-you want those files to be included, use a recursive glob (**).</p>
-<pre class="code">
-java_test(
- name = "myprog",
- srcs = ["myprog.java"],
- data = glob(
- ["testdata/*.txt"],
- exclude = ["testdata/experimental.txt"],
- ),
-)
-</pre>
-
-<h4 id="recursive_glob_example">Recursive Glob Examples</h4>
-
-<p>Create a library built from all java files in this directory and all
-subdirectories except those whose path includes a directory named testing.
-Subdirectories containing a BUILD file are ignored.
-<b>This should be a very common pattern.</b>
-</p>
-<pre class="code">
-java_library(
- name = "mylib",
- srcs = glob(
- ["**/*.java"],
- exclude = ["**/testing/**"],
- ),
-)
-</pre>
-
-<p>Make the test depend on all txt files in the testdata directory,
- its subdirectories</p>
-<pre class="code">
-java_test(
- name = "mytest",
- srcs = ["mytest.java"],
- data = glob(["testdata/**/*.txt"]),
-)
-</pre>
-
-<!-- =================================================================
- licenses()
- =================================================================
--->
-
-<h3 id="licenses">licenses</h3>
-
-<p><code>licenses(license_types)</code></p>
-
-<p><code>licenses()</code> specifies the default license type (or types)
- of the build rules in a <code>BUILD</code> file. The <code>licenses()</code>
- directive should appear close to the
- beginning of the <code>BUILD</code> file, before any build rules, as it
- sets the <code>BUILD</code>-file scope default for build rule license
- types.</p>
-
-<h4 id="licenses_args">Arguments</h4>
-
-<p>The argument, <code id="licenses.licence_types">license_types</code>,
- is a list of license-type strings.
-</p>
-
-<!-- =================================================================
- include()
- =================================================================
--->
-
-<h3 id="include">include</h3>
-
-<p><code>include(name)</code></p>
-
-<p><code>include()</code> incorporates build
- language definitions from an external file into the evaluation of the
- current <code>BUILD</code> file.</p>
-
-</body>
-</html>
diff --git a/docs/historical/images/package_targets.png b/docs/historical/images/package_targets.png
deleted file mode 100644
index d2759eb..0000000
--- a/docs/historical/images/package_targets.png
+++ /dev/null
Binary files differ
diff --git a/docs/historical/images/source_rules_generated_files.png b/docs/historical/images/source_rules_generated_files.png
deleted file mode 100644
index cd6143a..0000000
--- a/docs/historical/images/source_rules_generated_files.png
+++ /dev/null
Binary files differ
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..6bfbe2e
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,5 @@
+Home
+====
+
+Skylark is a work-in-progress project, which allows extending Bazel with new
+rules or macros (composition of rules and macros).
diff --git a/docs/macros.md b/docs/macros.md
new file mode 100644
index 0000000..9b2e1ad
--- /dev/null
+++ b/docs/macros.md
@@ -0,0 +1,63 @@
+Macros
+======
+
+**Status: Stable**
+
+Macro creation
+--------------
+
+A macro is a function called from the BUILD file. It can instantiate native
+or Skylark rules. By the end of the loading phase, macros don't exist
+anymore: Bazel sees only the set of rules they created.
+
+Native rules can be instantiated from the `native` module, e.g.
+
+```python
+native.cc_library(name = x)
+```
+
+If you need to know the package name (i.e. which BUILD file is calling the
+macro), use the constant `PACKAGE_NAME`.
+
+Examples
+--------
+
+* [Macro creating native rules](cookbook.md#macro_native).
+
+* [Macro creating Skylark rules](cookbook.md#macro_skylark).
+
+Debugging
+---------
+
+* `bazel query --output=build ///my/path:all` will show you how the BUILD
+file looks like after evaluation. All macros, globs, loops are expanded.
+
+* You can also use `print` for debugging. It displays the message as a
+warning during the loading phase. Except in rare cases, remove your `print`
+calls before submitting the code to the depot.
+
+Errors
+------
+
+If you want to throw an error, use the `fail` function. Explain clearly to
+the user what went wrong and how to fix their BUILD file. It is not possible
+to catch an error.
+
+Conventions
+-----------
+
+* All public functions (functions that don't start with underscore) that
+instantiate rules must have a `name` argument. This argument should not be
+optional (don't give a default value).
+
+* Public functions should use a docstring following [Python
+ conventions](https://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments).
+
+* In BUILD files, the `name` argument of the macros must a be a keyword
+ argument (not a positional argument).
+
+* The `name` attribute of rules generated by a macro should include the name
+ argument as a prefix. For example, `macro(name = "foo")` can generate a
+ cc_library `foo` and a genrule `foo_gen`.
+
+* Macros should have an optional `visibility` argument.
diff --git a/docs/rules.md b/docs/rules.md
new file mode 100644
index 0000000..e7092f2
--- /dev/null
+++ b/docs/rules.md
@@ -0,0 +1,263 @@
+Rules
+=====
+
+**Status: Experimental**
+
+[TOC]
+
+Rule creation
+-------------
+
+In a Skylark extension, use the `rule` function to create a new rule and store
+it in a global variable. [See example](cookbook.md#empty).
+
+Attributes
+----------
+
+An attribute is a rule argument, such as `srcs` or `deps`. You have to list
+the attributes and their type when you define a rule.
+
+```python
+sum = rule(
+ implementation=impl,
+ attr = {
+ "number": attr.int(default = 1),
+ "deps": attr.label_list(),
+ },
+)
+```
+
+If an attribute starts with `_`, it is private and users cannot set it. It
+is useful in particular for label attributes (your rule will have an
+implicit dependency on this label).
+
+The rule implementation function
+--------------------------------
+
+Every rule has to have an implementation function. This contains the actual
+logic of the rule and is executed strictly in the Analysis Phase. The function
+has exactly one input parameter, `ctx` and it may return
+the [runfiles](#runfiles) and [providers](#providers)
+of the rule. The input parameter `ctx` can be used to access attribute values,
+outputs and dependent targets and files. It also has some helper functions.
+See [the library](library.html#ctx) for more context. Example:
+
+```python
+def impl(ctx):
+ ...
+ return struct(
+ runfiles = ...,
+ my_provider = ...,
+ ...
+ )
+
+my_rule = rule(
+ implementation=impl,
+ ...
+)
+```
+
+Files
+-----
+
+There are two kinds of files: files stored in the file system and generated
+files. For each generated file, there must be one and only one generating
+action, and each action must generate one ore more output files. Otherwise
+Bazel will throw an error.
+
+Targets
+-------
+
+Every build rule corresponds to exactly one target. A target can create
+[actions](#actions), can have dependencies (which can be files or
+other build rules), [output files](#output_files) (generated by
+its actions) and [providers](#providers).
+
+A target `y` is depending on target `x` if `y` has a label or label list type
+attribute where `x` is declared:
+
+```python
+my_rule(
+ name = "x"
+)
+
+my_rule(
+ name = "y",
+ deps = [":x"]
+)
+```
+
+In the above case it's possible to access targets declared in `my_rule.deps`:
+
+```python
+def impl(ctx):
+ for dep in ctx.targets.deps:
+ # Do something with dep
+ ...
+
+my_rule = rule(
+ implementation=impl,
+ attrs = {
+ "deps": attr.label_list()
+ }
+ ...
+)
+```
+
+Output files
+------------
+
+A target can declare output files, which must be generated by the target's
+actions. There are three ways to create output files in Skylark:
+
+* If the rule is marked `executable`, it creates an output file of the same name
+ as the rule's. [See example](cookbook.md#outputs-executable)
+
+* The rule can declare default `outputs`, which are always generated.
+ [See example](cookbook.md#outputs-default)
+
+* The rule can have output or output list type attributes. In that case the
+ output files come from the actual attribute values.
+ [See example](cookbook.md#outputs-custom)
+
+All output files must have exactly one generating action. See the
+[library](library.html#outputs) for more context.
+
+
+Actions
+-------
+
+There are three ways to create actions:
+
+* `ctx.action`
+* `ctx.file_action`
+* `ctx.template_action`
+
+Actions take a set (can be empty) of input files and generate a (non-empty)
+set of output files.
+The set of input and output files must be known during the analysis phase. It
+might depend on the value of attributes and information from dependencies, but
+it cannot depend on the result of the execution. For example, if your action
+runs the zip command, you must specify which files you expect (before running
+zip).
+
+Actions are comparable to pure functions: They should depend only on the
+provided inputs, and avoid accessing computer information, username, clock,
+network or I/O devices (except for reading inputs and writing outputs).
+
+**If a command generates a file that is not listed in the outputs**: It is fine.
+The file will be ignored and cannot be used by other rules.
+
+**If a command does not generate a file that is listed in the outputs**: It is an
+execution error and the build will fail. This happens for instance when a
+compilation fails.
+
+**If a command generates an unknown number of outputs and you want to keep them
+all**, you may group them in a zip file. This way, you will be able to declare
+your output.
+
+**If a command does not list a file it uses as an input**, the action execution
+will most likely result in an error. The file is not guaranteed to be available
+to the action, so if it **is** there, it's due to a coincidence or error.
+
+**If a command lists a file as an input, but does not use it**: It is fine. However
+it can affect the action execution order resulting in sub-optimal performance.
+
+Dependencies are resolved by Bazel, which will decide which actions are
+executed. It is an error if there is a cycle in the dependency graph. Creating
+an action does not guarantee that it will be executed: It depends on whether
+its outputs are needed for the build.
+
+Providers
+---------
+
+Providers are used to access information from another rule. A rule depending on
+another rule has access to the data the latter provides. These data can be e.g.
+output files, the libraries the dependent rule is using to link or compile, or
+anything the depending rule should know about. Using providers is the only way
+to exchange data between rules.
+
+A rule can only access data provided by its direct dependencies, not that of
+transitive dependencies: if rule `top` depends on `middle` and `middle` depends
+on `bottom`, then `middle` is a direct dependency of `top` and `bottom` is a
+transitive dependency of `top`. In this scenario `top` can only access data
+provided by `middle`. If `middle` also provides the data that `bottom` provided
+to it then and only then can `top` access it.
+
+Only the following data types are allowed to pass using providers:
+
+* `boolean`
+* `integer`
+* `string`
+* `file`
+* `label`
+* `None`
+* anything composed of these types and `lists`, `dicts`, `sets` or `structs`
+
+Providers are created from the return value of the rule implementation function:
+
+```python
+def dependent_rule_implementation(ctx):
+ ...
+ return struct(
+ transitive_data = set(["a", "b", "c"])
+ )
+```
+
+A depending rule might access these data as struct fields of the depending
+`target`:
+
+```python
+def depending_rule_implementation(ctx):
+ ...
+ s = set()
+ for dep_target in ctx.targets.deps:
+ s += dep_target.transitive_data
+ ...
+```
+
+Providers are only available during the analysis phase. Examples of usage:
+
+* [mandatory providers](cookbook.md#mandatory-providers)
+* [optional providers](cookbook.md#optional-providers)
+
+Runfiles
+---------
+
+Runfiles are a set of files used by the (often executable) output of a rule
+during runtime (as opposed to build time, i.e. when the binary itself is
+generated).
+Bazel creates a directory tree containing symlinks pointing to the
+runfiles during execution, to stage this environment for the binary which can
+thus access them during runtime.
+
+Runfiles can be added manually during rule creation and/or collected
+transitively from dependent rules:
+
+```python
+def rule_implementation(ctx):
+ ...
+ transitive_runfiles = set()
+ for dep in ctx.targets.special_dependencies:
+ transitive_runfiles += dep.transitive_runtime_files
+
+ runfiles = ctx.runfiles(
+ # Add some files manually.
+ files = [ctx.file.some_data_file]
+ # Add transitive files from dependencies manually.
+ transitive_files = transitive_runfiles
+ # Collect runfiles from the common locations: transitively from srcs,
+ # deps and data attributes.
+ collect_default = True
+ )
+ # Add a field named "runfiles" to the return struct in order to actually
+ # create the symlink tree.
+ return struct(runfiles = runfiles)
+```
+
+Note that non-executable rule outputs can also have runfiles. For example, a
+library might need some external files during runtime, and every depending
+binary should know about it.
+
+Also note that if an action uses an executable, the executable's runfiles can
+be used when the action executes.
diff --git a/src/main/java/BUILD b/src/main/java/BUILD
index b78e832..65a585a 100644
--- a/src/main/java/BUILD
+++ b/src/main/java/BUILD
@@ -106,7 +106,7 @@
srcs = [":gen_be_sources"],
outs = ["build-encyclopedia.html"],
cmd = ("$(location docgen_bin)" +
- " $$PWD/java/com/google/devtools/build/lib" +
+ " $$PWD/src/main/java/com/google/devtools/build/lib" +
" $$PWD" +
"; cp $$PWD/build-encyclopedia.html $@"),
tools = [":docgen_bin"],
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be-body.html b/src/main/java/com/google/devtools/build/docgen/templates/be-body.html
index d1fc7ce..46e65ce 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be-body.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be-body.html
@@ -18,7 +18,7 @@
<p>A <code>*_library()</code> rule compiles some sources into a library.
In general, a <code><var>language</var>_library</code> rule works like
the corresponding <code><var>language</var>_binary</code> rule, but
- doesn't generate something executable.</p>
+ doesn't generate an executable.</p>
${SECTION_LIBRARY}
@@ -28,9 +28,8 @@
-->
<h2 id="test">*_test</h2>
-<p>A <code>*_test</code> rule compiles a
-test. See <a href="#common-attributes-tests">Common attributes for
-tests</a> for an explanation of the common attributes.
+<p>A <code>*_test</code> rule compiles a test.
+
${SECTION_TEST}
@@ -48,19 +47,16 @@
-->
<h2 id="make_variables">"Make" Variables</h2>
+
<p>
- This section describes how to use or define a special class of string
- variables that are called the "Make" environment. Bazel defines a set of
- standard "Make" variables, and you can also define your own.
+ This section describes how to use a special class of built-in string variables
+ that are called the "Make" environment.
+
+ Defining custom "Make" variables is not supported.
</p>
<p>(The reason for the term "Make" is historical: the syntax and semantics of
- these variables are somewhat similar to those of GNU Make, and in the
- original implementation, were implemented by GNU Make. The
- scare-quotes are present because newer build tools support
- "Make" variables without being implemented using GNU Make; therefore
- it is important to read the specification below carefully to
- understand the differences.)
+ these variables are somewhat similar to those of GNU Make.)
</p>
<p>To see the list of all common "Make" variables and their values,
@@ -73,8 +69,10 @@
<h3 id='make-var-substitution'>"Make" variable substitution</h3>
-<p>Variables can be referenced in attributes and other variables using either
- <code>$(FOO)</code> or <code>varref('FOO')</code>, where <code>FOO</code> is
+<p>Variables can be referenced in attributes
+
+ using <code>$(FOO)</code>
+ where <code>FOO</code> is
the variable name. In the attribute documentation of rules, it is mentioned
when an attribute is subject to "Make" variable substitution. For those
attributes this means that any substrings of the form <code>$(X)</code>
@@ -102,26 +100,51 @@
<p>Bazel defines a set of "Make" variables for you.</p>
-<p>The build system also provides a consistent PATH for genrules and tests which
- need to execute shell commands. For genrules, you can indirect your commands
- using the Make variables below. For basic Unix utilities, prefer relying on
- the PATH variable to guarantee correct results. For genrules involving
- compiler and platform invocation, you must use the Make variable syntax.
- The same basic command set is also available during tests. Simply rely on the
- PATH.</p>
+<p>The build system also provides a consistent PATH environment variable for
+genrules and tests which need to execute shell commands. For genrules, you can
+indirect your commands using the "Make" variables below. For basic Unix
+utilities, prefer relying on the PATH environment variable to guarantee correct
+results. For genrules involving compiler and platform invocation, you must use
+the "Make" variable syntax. The same basic command set is also available during
+tests. Simply rely on the PATH.</p>
-<p>Bazel uses a tiny Unix distribution to guarantee consistent behavior of
- build and test steps which execute shell code across all build execution
- hosting environments but it does not enforce a pure chroot. As such, do
- <b>not</b> use hard coded paths, such as
- <code>/usr/bin/foo</code>. Binaries referenced in hardcoded paths are not
- hermetic and can lead to unexpected and non-reproducible build behavior.</p>
+<p><strong>Compiler and Platforms available to genrules</strong></p>
+These tools may not be in the PATH, therefore you must use "Make" variable syntax
+in your genrule's cmd attribute.
+<ul>
+ <li> <code>CC</code>: The C compiler command. It is strongly recommended to
+ always use <code>CC_FLAGS</code> when invoking the C compiler.</li>
+ <li> <code>JAVA</code>: The "java" command (a Java virtual machine). Note that
+ this can be a relative path. If you must change directories before invoking
+ <code>java</code>, you need to capture the working directory before changing
+ it.</li>
+ <li> <code>JAVAC</code>: The "javac" command (a Java compiler). Note that
+ this can be a relative path. Also, this may not be the same compiler that is
+ used to compile normal Java rules (this may change in the future).</li>
-<p><strong>Command Variables for genrules</strong></p>
+ <li> <code>STRIP</code>: The strip command from the same suite as the C
+ compiler.</li>
+ <li> <code>AR</code>: The "ar" command from crosstool. </li>
+ <li> <code>NM</code>: The "nm" command from crosstool. </li>
+ <li> <code>OBJCOPY</code>: The objcopy command from the same suite as the C
+ compiler. </li>
+ <li> <code>C_COMPILER</code>:
+ The C compiler frontend, e.g. "gcc". </li>
+</ul>
-<p>Note that in general, you should simply refer to many common utilities as
-bare commands that the $PATH variable will correctly resolve to hermetic
-versions for you.</p>
+<p><strong>Tool option Variables</strong></p>
+
+<ul><!-- keep alphabetically sorted -->
+ <li><code>BINMODE</code>: "-dbg" or "-opt"
+
+ . (<i>When using Bazel's <code>-c fastbuild</code> option,
+ this variable has the value <code>-dbg</code>.</i>) </li>
+ <li><code>CC_FLAGS</code>: A minimal set of flags for the C compiler to be
+ used by genrules. In particular, it contains flags to select the correct
+ architecture if CC supports multiple architectures. </li>
+ <li><code>COMPILATION_MODE</code>: "fastbuild", "dbg", or "opt".</li>
+
+</ul>
<p><strong>Path Variables</strong></p>
@@ -144,10 +167,18 @@
<p><strong>Architecture Variables</strong></p>
<ul><!-- keep alphabetically sorted -->
- <li><code>ABI</code>: The C++ ABI version. </li>
- <li><code>ANDROID_CPU</code>: The Android target architecture's cpu. </li>
- <li><code>JAVA_CPU</code>: The Java target architecture's cpu. </li>
- <li> <code>TARGET_CPU</code>: The target architecture's cpu. </li>
+ <li><code>ABI</code>:
+ The C++ ABI version; currently "gcc-3.4". </li>
+ <li><code>ABI_GLIBC_VERSION</code>:
+ The minimal version of glibc required for <code>ABI</code>. For precompiled
+ third_party libraries, this usually represents the version of glibc
+ that was used to compile the library. </li>
+
+ <li><code>GLIBC_VERSION</code>: The version of glibc. </li>
+ <li><code>JAVA_CPU</code>: The Java target architecture's cpu,
+ "k8" by default. </li>
+ <li> <code>TARGET_CPU</code>: The target architecture's cpu,
+ e.g. "piii" or "k8". </li>
</ul>
<p id="predefined_variables.genrule.cmd">
@@ -177,132 +208,17 @@
<code>@D</code> (although <code>/tmp</code> will also be
writable), and to remove any such generated temporary files.
Especially, avoid writing to directories containing inputs -
- they may be on read-only filesystems. </li>
+ they may be on read-only filesystems, and even if they aren't,
+ doing so would trash the source tree.</li>
</ul>
-</ul>
+<h2 id="predefined-python-variables">Predefined Python Variables</h2>
-<h3 id="define_your_own_make_vars">Defining Your Own Variables</h3>
-
+<h3 id="packagename">PACKAGE_NAME</h3>
<p>
-You may want to use Python-style variable assignments rather than "Make"
-variables, because they work in more use cases and are less surprising. "Make"
-variables will work in the <a href="#genrule.cmd">cmd</a> attribute of genrules
-and in the key of the <a href="#cc_library.abi_deps">abi_deps</a> attribute of
-a limited number of rules, but only in very few other places.
-
+ This is a string variable with the name
+ of the package being evaluated. The value is unaffected by subinclude.
</p>
-<p>To define your "Make" own variables, first call <a
- href="#vardef">vardef()</a> to define your variable, then call <a
- href="#varref">varref(name)</a> to retrieve it. varref can be embedded as part
- of a larger string. Custom "Make" variables differ from ordinary "Python"
- variables in the BUILD language in two important ways:
-</p>
-<ul>
- <li>Only string values are supported,</li>
- <li>The "Make" environment is parameterized over the build
- platform, so that variables can be conditionally defined based on
- the target architecture, ABI or compiler, and</li>
- <li>The values of custom "Make" variables are <i>not available</i> during
- BUILD-file evaluation. To work around this, you must call <a
- href="#varref">varref()</a> to retrieve the value of a variable (unlike
- predefined values, which can be retrieved using <code>$(FOO)</code>.
- varref defers evaluation until after BUILD file evaluation.</li>
-</ul>
-
-<h4 id="vardef">vardef()</h4>
-
-<p><code>vardef(name, value, platform)</code></p>
-
- <p>
- Define a variable for use within this <code>BUILD</code> file only.
- This variable can then be used by <a href="#varref">varref()</a>.
- The value of the variable can be overridden on the command line by using the
- <code class='flag'><a href='bazel-user-manual.html#flag--define'>--define</a></code>
- flag.
- </p>
-
- <p id="vardef_args"><strong>Arguments</strong></p>
-<ul>
- <li><code>name</code>: The name of the variable.
- <i>(String; required)</i><br/>
- Convention is to use names consisting of ALL CAPS. This name must
- be a unique identifier in this package.
- </li>
- <li><code>value</code>: The value to assign to this variable.
- <i>(String; required)</i><br/>
- The value may make use of variables you know are defined in the "Make"
- environment.
- </li>
- <li><code>platform</code>: Conditionally define this variable for a given
- platform.
- <i>(String; optional)</i><br/>
-
- <code>vardef</code> binds the <code>name</code> to <code>value</code> if we're
- compiling for <code>platform</code>.
- </li>
-</ul>
-
-<p id="vardef_notes"><strong>Notes</strong></p>
-<p>
- Because references to "Make" variables are expanded <i>after</i>
- BUILD file evaluation, the relative order of <code>vardef</code>
- statements and rule declarations is unimportant; it is order of
- <code>vardef</code> statements relative to each other, and hence the
- state of the "Make" environment at the end of evaluation that
- matters.
-</p>
-<p>
- If there are multiple matching <code>vardef</code> definitions for
- the same variable, the definition that wins is
- the <strong>last</strong> matching definition
- <strong>that specifies a platform</strong>, unless there are no matching
- definitions that specify a platform, in which case the definition
- that wins is the <strong>last</strong> definition <strong>without
- a platform</strong>.
-</p>
-
-<!-- =================================================================
- varref()
- =================================================================
- -->
-
-<h4 id="varref">varref</h4>
-
-<p><code>varref(name)</code></p>
-
-<p>
-<code>varref("FOO")</code> is equivalent of writing "$(FOO)". It is used to
-dereference variables defined with <a href="#vardef"><code>vardef</code></a>
-as well as <a href="#predefined_variables">predefined variables</a>.
-</p>
-
-<p>
- In rule attributes that are subject to "Make" variable
- substitution, the string produced by <code>varref(<i>name</i>)</code>
- will expand to the value of variable <i>name</i>.
-</p>
-
-<p><code>varref(name)</code> may not be used in rule attributes that are
-not subject to "Make" variable substitution.</p>
-
-<p id="varref_args"><strong>Arguments</strong></p>
-<ul>
- <li><code>name</code>: The name of the variable to dereference.
- </li>
-</ul>
-
-<p id="varref_notes"><strong>Notes</strong></p>
-<ul>
- <li><code>varref</code> can access either local or global variables.
- It prefers the local variable, if both a local and a global exist with
- the same name.
- </li>
-</ul>
-
-<p id="varref_examples"><strong>Examples</strong></p>
-<p>See <a href="#vardef_examples">vardef()</a> examples.</p>
-
<!-- ============================================
other
@@ -311,3 +227,4 @@
<h2 id="misc">Other Stuff</h2>
${SECTION_OTHER}
+
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be-footer.html b/src/main/java/com/google/devtools/build/docgen/templates/be-footer.html
index fb4cc67..7fd649d 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be-footer.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be-footer.html
@@ -1,3 +1,4 @@
+
<!-- =================================================================
package()
=================================================================
@@ -5,18 +6,24 @@
<h3 id="package">package</h3>
-<p>This function declares metadata that applies to every subsequent rule in the
-package.</p>
+<p><code>package(
-<p>The <a href="build-ref.html#package">package</a>
- function is used at most once within a build package (BUILD file).
- It is recommended that the package function is called at the top of the
- file, before any rule.</p>
+ default_deprecation,
+ default_obsolete,
+ default_testonly,
+ default_visibility,
+ features</code>
+</p>
+
+<p>This function declares metadata that applies to every subsequent rule in the
+package. It is used at most once within a package (BUILD file).</p>
+
+<p>It is recommended that the package function is called at the top of the
+file, before any rule.</p>
<h4 id="package_args">Arguments</h4>
<ul>
-
<li id="package.default_visibility"><code>default_visibility</code>:
The default visibility of the rules in this package.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
@@ -25,7 +32,10 @@
attribute, unless otherwise specified in the <code>visibility</code>
attribute of the rule. For detailed information about the syntax of this
attribute, see the documentation of the <a href="#common.visibility">visibility</a>
- attribute.
+ attribute. The package default visibility applies neither to the
+ <a href="#exports_files">exports_files</a> function nor to the
+ <a href="#cc_public_library">cc_public_library</a> rule (which are
+ public by default).
</li>
<li id="package.default_obsolete"><code>default_obsolete</code>:
@@ -45,6 +55,15 @@
<p>In packages under <code>javatests</code> the default value is 1.</p>
</li>
+ <li id="package.features"><code>features</code>:
+ Sets various flags that affect the semantics of this BUILD file.
+ <i>(List strings; optional)</i>
+
+ <p>This feature is mainly used by the people working on the build system to
+ tag packages that need some kind of special handling. Do not use this unless
+ explicitly requested by someone working on the build system.</p>
+ </li>
+
</ul>
<h4 id="package_example">Examples</h4>
@@ -67,10 +86,11 @@
<p><code>package_group(name, packages, includes)</code></p>
-<p>This function defines a set of build packages.
+<p>This function defines a set of packages and assigns a label to the
+group. The label can be referenced in <code>visibility</code> attributes.</p>
-Package groups are used for visibility control. You can grant access to a rule
-to one or more package groups, every rule, or only to rules declared
+<p>Package groups are used for visibility control. You can grant access to a rule
+to one or more package groups, every rule in the entire source tree, or only to rules declared
in the same package. For more detailed description of the visibility system, see
the <a href="#common.visibility">visibility</a> attribute.
@@ -163,46 +183,6 @@
<!-- =================================================================
- DESCRIPTION
- =================================================================
- -->
-
-<h3 id="description">Description</h3>
-
-<p><code># Description: <var>...</var></code></p>
-
- <p>
- Each BUILD file should contain a <code>Description</code> comment.
- </p>
-
- <p>
- Description comments may contain references to other
- documentation. A string that starts with "http" will become a
- link. HTML markup is
- allowed in description comments, but please keep the BUILD files readable.
- We encourage you to list the URLs of relevant design docs and howtos
- in these description comments.
- </p>
-
-<h3 id="distribs">distribs</h3>
-
-<p><code>distribs(distrib_methods)</code></p>
-
-<p><code>distribs()</code> specifies the default distribution method (or
- methods) of the build rules in a <code>BUILD</code> file. The <code>distribs()</code>
- directive
- should appear close to the beginning of the <code>BUILD</code> file,
- before any build rules, as it sets the <code>BUILD</code>-file scope
- default for build rule distribution methods.
-</p>
-
-<h4 id="distribs_args">Arguments</h4>
-
-<p>The argument, <code id="distribs.distrib_methods">distrib_methods</code>,
- is a list of distribution-method strings.
-</p>
-
-<!-- =================================================================
exports_files([label, ...])
=================================================================
-->
@@ -224,7 +204,7 @@
The remaining files are not associated with a specific rule but are just "data",
and for these, <code>exports_files</code> ensures that they may be referenced by
other packages. (One kind of data for which this is particularly useful are
- shell and Perl scripts.)
+ shell scripts.)
</p>
<p>
@@ -245,6 +225,21 @@
<a href="#common.licenses">licenses</a> can also be specified.
</p>
+<h4 id="exports_files_example">Example</h4>
+
+<p>
+ The following example exports <code>golden.txt</code>, a
+ text file from the <code>test_data</code> package, so that other
+ packages may use it, for example, in the <code>data</code> attribute
+ of tests.
+</p>
+
+<pre class="code">
+# from //test_data/BUILD
+
+exports_files(["golden.txt"])
+</pre>
+
<!-- =================================================================
glob()
=================================================================
@@ -268,16 +263,14 @@
and <code>"**.java"</code> are both illegal. No other wildcards are supported.
</p>
<p>
-Glob returns a list of every file in the current build package that:
+Glob returns a list of every file in the current package that:
</p>
<ul>
- <li style="margin-bottom: 0">
- Matches at least one pattern in <code>include</code>. </li>
- <li>
- Does not match any of the patterns in <code>exclude</code> (default []).</li>
+ <li>Matches at least one pattern in <code>include</code>. </li>
+ <li>Does not match any of the patterns in <code>exclude</code> (default []).</li>
</ul>
<p>
-If the <code>exclude_directories</code> argument is enabled (1), files of
+If the <code>exclude_directories</code> argument is enabled (set to 1), files of
type directory will be omitted from the results (default 1).
</p>
<p>
@@ -309,13 +302,20 @@
means that the result of the glob expression actually depends on the
existence of BUILD files — that is, the same glob expression would
include <code>x/y/z.cc</code> if there was no package called
- <code>x/y</code>.
+ <code>x/y</code> or it was marked as deleted using the
+ <a href="bazel-user-manual.html#flag--deleted_packages">--deleted_packages</a>
+ flag.
+
</li>
<li>
The restriction above applies to all glob expressions,
no matter which wildcards they use.
</li>
+ <li>
+ A hidden file with filename starting with <code>.</code> is matched by
+ both the <code>**</code> and the <code>*</code> wildcards.
+ </li>
</ol>
<p>
@@ -325,15 +325,40 @@
files, or emacs/vi/... auto-save files.
</p>
+<p>
+When writing build rules you can enumerate the elements of the glob. This
+enables generating individual rules for every input, for example. See the
+<a href="#expanded_glob_example">expanded glob example</a> section below.
+</p>
+
<h4 id="glob_example">Glob Examples</h4>
+<p> Create a Java library built from all java files in this directory,
+and all files generated by the <code>:gen_java_srcs</code> rule.</p>
+<pre class="code">
+java_library(
+ name = "mylib",
+ srcs = glob(["*.java"]) + [":localize_strings"],
+ deps = "...",
+)
+
+genrule(
+ name = "gen_java_srcs",
+ outs = [
+ "Foo.java",
+ "Bar.java",
+ ],
+ ...
+)
+</pre>
+
<p>Include all txt files in directory testdata except experimental.txt.
Note that files in subdirectories of testdata will not be included. If
you want those files to be included, use a recursive glob (**).</p>
<pre class="code">
-java_test(
- name = "myprog",
- srcs = ["myprog.java"],
+sh_test(
+ name = "mytest",
+ srcs = ["mytest.sh"],
data = glob(
["testdata/*.txt"],
exclude = ["testdata/experimental.txt"],
@@ -361,13 +386,43 @@
<p>Make the test depend on all txt files in the testdata directory,
its subdirectories</p>
<pre class="code">
-java_test(
+sh_test(
name = "mytest",
- srcs = ["mytest.java"],
+ srcs = ["mytest.sh"],
data = glob(["testdata/**/*.txt"]),
)
</pre>
+<h4 id="expanded_glob_example">Expanded Glob Examples</h4>
+
+<p>
+Create an individual genrule for *_test.cc in the current directory
+that counts the number of lines in the file.
+</p>
+
+<pre class="code">
+# Conveniently, the build language supports list comprehensions.
+[genrule(
+ name = "count_lines_" + f[:-3], # strip ".cc"
+ srcs = [f],
+ outs = ["%s-linecount.txt" % f[:-3]],
+ cmd = "wc -l $< >$@",
+ ) for f in glob(["*_test.cc"])]
+</pre>
+
+<p>
+If the BUILD file above is in package //foo and the package contains three
+matching files, a_test.cc, b_test.cc and c_test.cc then running
+<code>bazel query '//foo:all'</code> will list all rules that were generated:
+
+<pre>
+$ bazel query '//foo:all' | sort
+//foo:count_lines_a_test
+//foo:count_lines_b_test
+//foo:count_lines_c_test
+</pre>
+
+
<!-- =================================================================
licenses()
=================================================================
@@ -378,8 +433,9 @@
<p><code>licenses(license_types)</code></p>
<p><code>licenses()</code> specifies the default license type (or types)
- of the build rules in a <code>BUILD</code> file. The <code>licenses()</code>
- directive should appear close to the
+ of the build rules in a <code>BUILD</code> file.
+
+ The <code>licenses()</code> directive should appear close to the
beginning of the <code>BUILD</code> file, before any build rules, as it
sets the <code>BUILD</code>-file scope default for build rule license
types.</p>
@@ -388,20 +444,126 @@
<p>The argument, <code id="licenses.licence_types">license_types</code>,
is a list of license-type strings.
+ <!-- TODO(bazel-team): specify some examples -->
+
</p>
+<h4 id="licenses_example">Examples</h4>
+
+<p>The following example specifies a single license type of
+ <code>"notice"</code>. Third-party software licenses that do not require
+ publishing of source code changes but require some sort of copyright or
+ other public notice are included in this license type.
+</p>
+
+<pre class="code">
+
+licenses(["notice"]) # MIT license
+
+exports_files(["jquery-2.1.1.js"])
+</pre>
+
<!-- =================================================================
- include()
+ load()
=================================================================
-->
-<h3 id="include">include</h3>
+<h3 id="load">load</h3>
-<p><code>include(name)</code></p>
+<p><code>load(path, symbols...)</code></p>
-<p><code>include()</code> incorporates build
- language definitions from an external file into the evaluation of the
- current <code>BUILD</code> file.</p>
+<p><code>load()</code> is a statement that imports definitions from a
+ Skylark module. For example:
+</p>
+<pre class="code">
+load("/tools/build_rules/build_test", "build_test")
+
+build_test(name = ...)
+</pre>
+
+<p>This will execute the
+
+ Skylark
+ module <code>tools/build_rules/build_test.bzl</code> and import the symbol
+ <code>build_test</code> in the local environment. By using more arguments, you
+ can load more symbols at once.</p>
+
+
+<!-- =================================================================
+ select()
+ =================================================================
+-->
+
+<h3 id="select">select</h3>
+
+<p><code>select({conditionA: valuesA, conditionB: valuesB, ...})</code>
+</p>
+
+<p><code>select()</code> is the helper function that makes an
+ attribute for a
+ rule <a href="#configurable-attributes">configurable</a>. It can
+ replace the right-hand side of
+
+ <i>almost</i>
+ any attribute assignment so that the attribute's value depends on the
+ Bazel flags passed in at the command line. This can be used, for
+ example, to define platform-specific dependencies or to embed
+ different resources depending on whether a rule is built in
+ "developer" vs. "release" mode.
+</p>
+
+<p>Basic usage is as follows:</p>
+
+<pre class="code">
+sh_binary(
+ name = "myrule",
+ srcs = select({
+ ":conditionA": ["myrule_a.sh"],
+ ":conditionB": ["myrule_b.sh"],
+ "//conditions:default": ["myrule_default.sh"]
+ })
+)
+</pre>
+
+<p>This makes the <code>srcs</code> attribute of
+ a <code>sh_binary</code> configurable by replacing its normal label
+ list assignment with a <code>select</code> call that maps
+ configuration conditions to matching values. Each condition is a label
+ reference to
+ a <code><a href="#config_setting">config_setting</a></code> instance,
+ which "matches" if the rule's configuration matches an expected set of
+ values. The value of <code>myrule#srcs</code> then becomes whichever
+ label list matches the current invocation.
+</p>
+
+<p>Further notes:</p>
+
+<ul>
+ <li>Exactly one condition is selected on any invocation.
+ </li>
+ <li>If two conditions match and one is a specialization of the other
+ (e.g. it matches on the same flags as the other plus additional flags),
+ the specialization takes precedence.
+ </li>
+ <li>If two conditions match and neither is a specialization of the other,
+ Bazel fails with an error.
+ </li>
+ <li>The special pseudo-label <code>//conditions:default</code> is
+ considered to match if no other condition matches. If this condition
+ is left out, some other rule must match to avoid an error.
+ </li>
+ <li><code>select</code> cannot currently be embedded <i>within</i> an
+ attribute assignment. In other words, <code>srcs = ["common.sh"]
+ + select({ "conditionA": ["myrule_a.sh"], ...})</code> does not
+ currently work.
+ </li>
+ <li><code>select</code> works with most, but not all, attributes.
+
+ </li>
+</ul>
+
+</div>
+</div>
</body>
</html>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be-header.html b/src/main/java/com/google/devtools/build/docgen/templates/be-header.html
index cdebf9b..3e8fdff 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be-header.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be-header.html
@@ -1,8 +1,7 @@
-<!DOCTYPE html>
<html>
<head>
- <title>Bazel BUILD Encyclopedia of Functions</title>
+ <title>Bazel BUILD Encyclopedia of Functions</title>
<style type="text/css" id="internalStyle">
body {
background-color: #ffffff;
@@ -47,16 +46,16 @@
margin-bottom: 0;
}
- /* Use the <code> tag for bits of code and <var> for variable and object names. */
+ /* 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> tag for file and directory paths and names. */
+ /* Use the <file></file> tag for file and directory paths and names. */
file {
color: #905050;
font-family: monospace;
}
- /* Use the <kbd> tag for stuff the user should type. */
+ /* Use the <kbd></kbd> tag for stuff the user should type. */
kbd {
color: #600000;
}
@@ -85,7 +84,7 @@
/* 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> things the user types)
+ (Within pre.interaction, use <kbd></kbd> for things the user types)
*/
pre.code {
background-color: #FFFFEE;
@@ -143,7 +142,6 @@
color: gray;
}
</style>
-
<style type="text/css">
.rule-signature {
color: #006000;
@@ -153,8 +151,26 @@
</head>
<body>
+<div style="width:100%;">
+<div id="left-panel" style="margin-left:-80px;height:97%;float:left;position:fixed;overflow-y:scroll;overflow-x:hidden;border-right:thin solid #000000;resize:horizontal;">
+<h3 style="margin-left:0px">Rules:</h3>
+
+${LEFT_PANEL}
+
+</div>
+<div id="main-panel" style="margin-left:200px">
<h1>Bazel BUILD Encyclopedia of Functions</h1>
+<h2>Related Documentation</h2>
+<ul class="toc">
+ <li><a href="write_build_file.html">Getting Started with BUILD files</a></li>
+ <li><a href="build-ref.html">BUILD Concept Reference</a></li>
+ <li><a href="build-encyclopedia.html">Build Encyclopedia</a></li>
+
+ <li><a href="bazel-user-manual.html">Bazel User Manual</a></li>
+ <li><a href="bazel-query-v2.html">Bazel Query Reference</a></li>
+
+</ul>
<h2>Contents</h2>
@@ -168,6 +184,7 @@
<li><a href="#common-attributes">Common attributes</a></li>
<li><a href="#common-attributes-tests">Common attributes for tests</a></li>
<li><a href="#common-attributes-binaries">Common attributes for binaries</a></li>
+ <li><a href="#configurable-attributes">Configurable attributes</a></li>
<li><a href="#implicit-outputs">Implicit output targets</a></li>
</ul>
</li>
@@ -178,28 +195,26 @@
<ul class="toc">
<li><a href="#make-var-substitution">"Make" variable substitution</a></li>
<li><a href="#predefined_variables">Predefined variables</a></li>
- <li><a href="#define_your_own_make_vars">Defining your own variables</a>
- <ul>
- <li><a href="#vardef">vardef</a></li>
- <li><a href="#varref">varref</a></li>
- </ul>
- </li>
+
</ul>
<li><a href="#predefined-python-variables">Predefined Python Variables</a></li>
</ul>
</td><td>
<ul class="toc">
- <li><a href="#include">include</a></li>
+ <li><a href="#load">load</a></li>
+
<li><a href="#package">package</a></li>
<li><a href="#package_group">package_group</a></li>
- <li><a href="#description">Description</a></li>
- <li><a href="#distribs">distribs</a></li>
+
<li><a href="#licenses">licenses</a></li>
<li><a href="#exports_files">exports_files</a></li>
<li><a href="#glob">glob</a></li>
+ <li><a href="#select">select</a></li>
</ul>
</td></tr></table>
+ <h3>Rules</h3>
+
${HEADER_TABLE}
<h2 id="common-definitions">Common definitions</h2>
@@ -208,8 +223,6 @@
many functions or build rules below.
</p>
-<!-- we haven't defined 'rules' or 'attributes' yet. -->
-
<h3 id='sh-tokenization'>Bourne shell tokenization</h3>
<p>
Certain string attributes of some rules are split into multiple
@@ -225,9 +238,9 @@
<p>
Attributes subject to "Make" variable expansion and Bourne shell
tokenization are typically used for passing arbitrary options to
- compilers and other tools, such as the <code>copts</code> attribute
- of <code>cc_library</code>, or the <code>javacopts</code> attribute of
- <code>java_library</code>. Together these substitutions allow a
+ compilers and other tools. Examples of such attributes are
+ <code>cc_library.copts</code> and <code>java_library.javacopts</code>.
+ Together these substitutions allow a
single string variable to expand into a configuration-specific list
of option words.
</p>
@@ -235,15 +248,15 @@
<h3 id='label-expansion'>Label expansion</h3>
<p>
Some string attributes of a very few rules are subject to label
- expansion: if those strings contain a valid build label as a
+ expansion: if those strings contain a valid label as a
substring, such as <code>//mypkg:target</code>, and that label is a
declared prerequisite of the current rule, it is expanded into the
pathname of the file represented by the target <code>//mypkg:target</code>.
</p>
+
<p>
- Example attributes include the <code>cmd</code> attribute of
- genrule, and the <code>linkopts</code> attribute
- of <code>cc_library</code>. The details may vary significantly in
+ Example attributes include <code>genrule.cmd</code> and
+ <code>cc_binary.linkopts</code>. The details may vary significantly in
each case, over such issues as: whether relative labels are
expanded; how labels that expand to multiple files are
treated, etc. Consult the rule attribute documentation for
@@ -257,310 +270,34 @@
labels attribute.
</p>
-<ul>
-<li id="common.deps"><code>deps</code>:
-A list of dependencies of this rule.
-<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
-The precise semantics of what it means for this rule to depend on
-another using <code>deps</code> are specific to the kind of this rule,
-and the rule-specific documentation below goes into more detail.
-At a minimum, though, the targets named via <code>deps</code> will
-appear in the <code>*.runfiles</code> area of this rule, if it has
-one.
-<p>Most often, a <code>deps</code> dependency is used to allow one
-module to use symbols defined in another module written in the
-same programming language and separately compiled. Cross-language
-dependencies are also permitted in many cases: for example,
-a <code>java_library</code> rule may depend on C++ code in
-a <code>cc_library</code> rule, by declaring the latter in
-the <code>deps</code> attribute. See the definition
-of <a href="build-ref.html#deps">dependencies</a> for more
-information.</p>
-<p>Almost all rules permit a <code>deps</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.</p></li>
-<li id="common.data"><code>data</code>:
-The list of files needed by this rule at runtime.
-<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
-Targets named in the <code>data</code> attribute will appear in
-the <code>*.runfiles</code> area of this rule, if it has one. This
-may include data files needed by a binary or library, or other
-programs needed by it. See the
-<a href="build-ref.html#data">data dependencies</a> section for more
-information about how to depend on and use data files.
-<p>Almost all rules permit a <code>data</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.</p></li>
-<li id="common.deprecation"><code>deprecation</code>:
-<i>(String; optional)</i><br/>
-An explanatory warning message associated with this rule.
-Typically this is used to notify users that a rule has become obsolete,
-or has become superseded by another rule, is private to a package, or is
-perhaps "considered harmful" for some reason. It is a good idea to include
-some reference (like a webpage, a bug number or example migration CLs) so
-that one can easily find out what changes are required to avoid the message.
-If there is a new target that can be used as a drop in replacement, it is a good idea
-to just migrate all users of the old target.
-<p>
-This attribute has no effect on the way things are built, but it
-may affect a build tool's diagnostic output. The build tool issues a
-warning when a rule with a <code>deprecation</code> attribute is
-depended upon by another rule.</p>
-<p>
-Intra-package dependencies are exempt from this warning, so that,
-for example, building the tests of a deprecated rule does not
-encounter a warning.</p>
-<p>
-If a deprecated rule depends on another deprecated rule, no warning
-message is issued.</p>
-<p>
-Once people have stopped using it, the package can be removed or marked as
-<a href="#common.obsolete"><code>obsolete</code></a>.</p></li>
-<li id="common.distribs"><code>distribs</code>:
-<i>(List of strings; optional)</i><br/>
-A list of distribution-method strings to be used for this particular build rule.
-Overrides the <code>BUILD</code>-file scope defaults defined by the
-<a href="#distribs"><code>distribs()</code></a> directive.</li>
-<li id="common.licenses"><code>licenses</code>:
-<i>(List of strings; optional)</i><br/>
-A list of license-type strings to be used for this particular build rule.
-Overrides the <code>BUILD</code>-file scope defaults defined by the
-<a href="#licenses"><code>licenses()</code></a> directive.</li>
-<li id="common.obsolete"><code>obsolete</code>:
-<i>(Boolean; optional; default 0)</i><br/>
-If 1, only obsolete targets can depend on this target. It is an error when
-a non-obsolete target depends on an obsolete target.
-<p>
-As a transition, one can first mark a package as in
-<a href="#common.deprecation"><code>deprecation</code></a>.</p>
-<p>
-This attribute is useful when you want to prevent a target from
-being used but are yet not ready to delete the sources.</p></li>
-<li id="common.tags"><code>tags</code>:
-List of arbitrary text tags. Tags may be any valid string; default is the
-empty list.<br/>
-<i>Tags</i> can be used on any rule; but <i>tags</i> are most useful
-on test and <code>test_suite</code> rules. Tags on non-test rules
-are only useful to humans and/or external programs.
-<i>Tags</i> are generally used to annotate a test's role in your debug
-and release process. The use of tags and size elements
-gives flexibility in assembling suites of tests based around codebase
-check-in policy.
-<p>
-A few tags have special meaning to the build tool; consult
-the <a href='bazel-user-manual.html#tags_keywords'>Bazel
-documentation</a> for details.
-</p></li>
-<li id="common.testonly"><code>testonly</code>:
-<i>(Boolean; optional; default 0 except as noted)</i><br />
-If 1, only testonly targets (such as tests) can depend on this target.
-<p>Equivalently, a rule that is not <code>testonly</code> is not allowed to
-depend on any rule that is <code>testonly</code>.</p>
-<p>Tests (<code>*_test</code> rules)
-and test suites (<a href="#test_suite">test_suite</a> rules)
-are <code>testonly</code> by default.</p>
-<p>By virtue of
-<a href="#package.default_testonly"><code>default_testonly</code></a>,
-targets under <code>javatests</code> are <code>testonly</code> by default.</p>
-<p>This attribute is intended to mean that the target should not be
-contained in binaries that are released to production.</p>
-<p>Because testonly is enforced at build time, not run time, and propagates
-virally through the dependency tree, it should be applied judiciously. For
-example, stubs and fakes that
-are useful for unit tests may also be useful for integration tests
-involving the same binaries that will be released to production, and
-therefore should probably not be marked testonly. Conversely, rules that
-are dangerous to even link in, perhaps because they unconditionally
-override normal behavior, should definitely be marked testonly.</p></li>
-<li id="common.visibility"><code>visibility</code>:
-<i>(List of <a href="build-ref.html#labels">labels</a>; optional; default private)</i><br/>
-<p>The <code>visibility</code> attribute on a rule controls whether
-the rule can be used by other packages. Rules are always visible to
-other rules declared in the same package.</p>
-<p>There are five forms (and one temporary form) a visibility label can take:
-<ul>
-<li><code>['//visibility:public']</code>: Anyone can use this rule.</li>
-<li><code>['//visibility:private']</code>: Only rules in this package
-can use this rule. Rules in <code>javatests/foo/bar</code>
-can always use rules in <code>java/foo/bar</code>.
-</li>
-<li><code>['//some/package:__pkg__', '//other/package:__pkg__']</code>:
-Only rules in <code>some/package</code> and <code>other/package</code>
-(defined in <code>some/package/BUILD</code> and
-<code>other/package/BUILD</code>) have access to this rule. Note that
-sub-packages do not have access to the rule; for example,
-<code>//some/package/foo:bar</code> or
-<code>//other/package/testing:bla</code> wouldn't have access.
-<code>__pkg__</code> is a special target and must be used verbatim.
-It represents all of the rules in the package.
-</li>
-<li><code>['//project:__subpackages__', '//other:__subpackages__']</code>:
-Only rules in packages <code>project</code> or <code>other</code> or
-in one of their sub-packages have access to this rule. For example,
-<code>//project:rule</code>, <code>//project/library:lib</code> or
-<code>//other/testing/internal:munge</code> are allowed to depend on
-this rule (but not <code>//independent:evil</code>)
-</li>
-<li><code>['//some/package:my_package_group']</code>:
-A <a href="#package_group">package group</a> is
-a named set of package names. Package groups can also grant access rights
-to entire subtrees, e.g.<code>//myproj/...</code>.
-</li>
-</ul>
-<p>The visibility specifications of <code>//visibility:public</code>,
-<code>//visibility:private</code> and
-<code>//visibility:legacy_public</code>
-can not be combined with any other visibility specifications.
-A visibility specification may contain a combination of package labels
-(i.e. //foo:__pkg__) and package_groups.</p>
-<p>If a rule does not specify the visibility attribute,
-the <code><a href="#package">default_visibility</a></code>
-attribute of the <code><a href="#package">package</a></code>
-statement in the BUILD file containing the rule is used
-(except <a href="#exports_files">exports_files</a> and
-<a href="#cc_public_library">cc_public_library</a>, which always default to
-public).</p>
-<p><b>Example</b>:</p>
-<p>
-File <code>//frobber/bin/BUILD</code>:
-</p>
-<pre class="code">
-# This rule is visible to everyone
-java_binary(
- name = "executable",
- visibility = ["//visibility:public"],
- deps = [":library"],
-)
-
-# This rule is visible only to rules declared in the same package
-java_library(
- name = "library",
- visibility = ["//visibility:private"],
-)
-
-# This rule is visible to rules in package //object and //noun
-java_library(
- name = "subject",
- visibility = [
- "//noun:__pkg__",
- "//object:__pkg__",
- ],
-)
-
-# See package group //frobber:friends (below) for who can access this rule.
-java_library(
- name = "thingy",
- visibility = ["//frobber:friends"],
-)
-</pre>
-<p>
-File <code>//frobber/BUILD</code>:
-</p>
-<pre class="code">
-# This is the package group declaration to which rule //frobber/bin:thingy refers.
-#
-# Our friends are packages //frobber, //fribber and any subpackage of //fribber.
-package_group(
- name = "friends",
- packages = [
- "//fribber/...",
- "//frobber",
- ],
-)
-</pre></li>
-</ul>
-
+${COMMON_ATTRIBUTE_DEFINITION}
<h3 id="common-attributes-tests">Attributes common to all test rules (*_test)</h3>
<p>This section describes attributes that are common to all test rules.</p>
-<ul>
-<li id="test.args"><code>args</code>:
-Add these arguments to the <code>--test_arg</code>
-when executed by <code>bazel test</code>.
-<i>(List of strings; optional; subject to
-<a href="#make_variables">"Make variable"</a> substitution and
-<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
-These arguments are passed before the <code>--test_arg</code> values
-specified on the <code>bazel test</code> command line.</li>
-<li id="test.flaky"><code>flaky</code>:
-Marks test as flaky. <i>(Boolean; optional)</i><br/>
-If set, executes the test up to 3 times before being declared as failed.
-By default this attribute is set to 0 and test is considered to be stable.
-Note, that use of this attribute is generally discouraged - we do prefer
-all tests to be stable.</li>
-<li id="test.local"><code>local</code>:
-Forces the test to be run locally. <i>(Boolean; optional)</i><br/>
-By default this attribute is set to 0 and the default testing strategy is
-used. This is equivalent to providing 'local' as a tag
-(<code>tags=["local"]</code>).</li>
-<li id="test.shard_count"><code>shard_count</code>:
-Specifies the number of parallel shards
-to use to run the test. <i>(Non-negative integer less than or equal to 50;
-optional)</i><br/>
-This value will override any heuristics used to determine the number of
-parallel shards with which to run the test.</li>
-<li id="test.size"><code>size</code>:
-How "heavy" the test is
-<i>(String "enormous", "large" "medium" or "small",
-default is "medium")</i><br/>
-A classification of the test's "heaviness": how much time/resources
-it needs to run. This is useful when deciding which tests to run.
-Before checking in a change, you might run the small tests.
-Before a big release, you might run the large tests.
-</li>
-<li id="test.timeout"><code>timeout</code>:
-How long the test is
-normally expected to run before returning.
-<i>(String "eternal", "long", "moderate", or "short"
-with the default derived from a test's size attribute)</i><br/>
-While a test's size attribute controls resource estimation, a test's
-timeout may be set independently. If not explicitly specified, the
-timeout is based on the test's size (with "small" ⇒ "short",
-"medium" ⇒ "moderate", etc...). While size and runtime are generally
-heavily correlated, they are not strictly causal, hence the ability to set
-them independently.</li>
-</ul>
-
+${TEST_ATTRIBUTE_DEFINITION}
<h3 id="common-attributes-binaries">Attributes common to all binary rules (*_binary)</h3>
<p>This section describes attributes that are common to all binary rules.</p>
-<ul>
-<li id="binary.args"><code>args</code>:
-Add these arguments to the target when executed by
-<code>bazel run</code>.
-<i>(List of strings; optional; subject to
-<a href="#make_variables">"Make variable"</a> substitution and
-<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
-These arguments are passed to the target before the target options
-specified on the <code>bazel run</code> command line.
-<p>Most binary rules permit an <code>args</code> attribute, but where
-this attribute is not allowed, this fact is documented under the
-specific rule.</p></li>
-<li id="binary.output_licenses"><code>output_licenses</code>:
-The licenses of the output files that this binary generates.
-<i>(List of strings; optional)</i><br/>
-Describes the licenses of the output of the binary generated by
-the rule. When a binary is referenced in a host attribute (for
-example, the <code>tools</code> attribute of
-a <code>genrule</code>), this license declaration is used rather
-than the union of the licenses of its transitive closure. This
-argument is useful when a binary is used as a tool during the
-build of a rule, and it is not desirable for its license to leak
-into the license of that rule. If this attribute is missing, the
-license computation proceeds as if the host dependency was a
-regular dependency.
-<p><em class="harmful">WARNING: in some cases (specifically, in
-genrules) the build tool cannot guarantee that the binary
-referenced by this attribute is actually used as a tool, and is
-not, for example, copied to the output. In these cases, it is the
-responsibility of the user to make sure that this is
-true.</em></p></li>
-</ul>
+${BINARY_ATTRIBUTE_DEFINITION}
+<h3 id="configurable-attributes">Configurable attributes</h3>
+
+<p>
+ Most rule attributes can be "configured" so that their values can
+ depend on the command-line flags passed to Bazel. This can be used,
+ for example, to declare platform-dependent <code>srcs</code> or custom
+ compiler flags depending on the
+ <a href="bazel-user-manual.html#flag--compilation_mode">compilation
+ mode</a>. This feature is very close in spirit to
+ <a href="#cc_library.abi_deps">abi_deps</a>, except that it's not
+ limited to <code>cc_*</code> rules and the <code>deps</code> attribute.
+</p>
+
+</p>
<h3 id="implicit-outputs">Implicit output targets</h3>
@@ -578,7 +315,7 @@
</p>
<p>
- Implicit output targets are first-class members of the build
+ Implicit output targets are first-class members of the global
target graph. Just like other targets, they are built on demand,
either when specified in the top-level built command, or when they
are necessary prerequisites for other build targets. They can be
@@ -593,8 +330,8 @@
</p>
<p>
- Please note an important but somewhat subtle distinction between the
- two namespaces used by the build system. Build
+ An important but somewhat subtle distinction between the
+ two namespaces used by the build system:
<a href="build-ref.html#labels">labels</a> identify <em>targets</em>,
which may be rules or files, and file targets may be divided into
either source (or input) file targets and derived (or output) file
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-body.html b/src/main/java/com/google/devtools/build/docgen/templates/skylark-body.html
new file mode 100644
index 0000000..5becb1a
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-body.html
@@ -0,0 +1,58 @@
+<html>
+<head>
+ <title>Skylark documentation</title>
+
+ <style type="text/css" id="internalStyle">
+ h1 { margin-bottom: 5px; }
+ .toc { margin: 0px; }
+ ul li { margin-bottom: 1em; }
+ ul.toc li { margin-bottom: 0px; }
+ em.harmful { color: red; }
+
+ .deprecated { text-decoration: line-through; }
+ .discouraged { text-decoration: line-through; }
+
+ #rules { width: 980px; border-collapse: collapse; }
+ #rules td { border-top: 1px solid gray; padding: 4px; vertical-align: top; }
+ #rules th { text-align: left; padding: 4px; }
+
+ table.layout { width: 980px; }
+ table.layout td { vertical-align: top; }
+
+ #maintainer { text-align: right; }
+
+ dt {
+ font-weight: bold;
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+ }
+ dd dt {
+ font-weight: normal;
+ text-decoration: underline;
+ color: gray;
+ }
+ a.anchor {
+ color:inherit;
+ text-decoration: none;
+ }
+ </style>
+
+ <style type="text/css">
+ .rule-signature {
+ color: #006000;
+ font-family: monospace;
+ }
+ </style>
+</head>
+
+<body>
+<h1>Skylark documentation</h1>
+
+<h2>Built-in objects and functions in the Skylark Environment</h2>
+
+
+${SECTION_BUILTIN}
+
+</body>
+</html>
+
