diff options
Diffstat (limited to 'site/versions/master/docs/query.html')
| -rw-r--r-- | site/versions/master/docs/query.html | 1803 |
1 files changed, 0 insertions, 1803 deletions
diff --git a/site/versions/master/docs/query.html b/site/versions/master/docs/query.html deleted file mode 100644 index a5068c8eef..0000000000 --- a/site/versions/master/docs/query.html +++ /dev/null @@ -1,1803 +0,0 @@ ---- -layout: documentation -title: Query Language ---- -<h1>The Bazel Query Reference</h1> - -<p> - When you use <code>bazel query</code> to analyze build - dependencies, you use a little language, the <em>Bazel Query - Language</em>. This document is the reference manual for that - language. This document also describes the output - formats <code>bazel query</code> supports. -</p> - -<h2>Examples</h2> - -<p> - How do people use <code>bazel query</code>? Here are typical examples: -</p> - -<p> - Why does the <code>//foo</code> tree depend on <code>//bar/baz</code>? - Show a path:</p> - <pre>somepath(foo/..., //bar/baz:all)</pre> - - -<p> - 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> - -<p> - Expressions in the query language are composed of the following - tokens:</p> - <ul> - <li> - <p> - <b>Keywords</b>, such as <code>somepath</code> or - <code>let</code>. Keywords are the reserved words of the - language, and each of them is described below. The complete set - of keywords is: - </p> - -<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="#loadfiles">loadfiles</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> - <p> - <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. - If a character sequence is not quoted, it may still be parsed as a word. - Unquoted words are sequences of characters drawn from - the set of alphabet characters, numerals, slash <code>/</code>, - hyphen <code>-</code>, underscore <code>_</code>, star <code>*</code>, and - period <code>.</code>. Unquoted words may not start with a - hyphen or period. - </p> - - <p>We chose this syntax so that quote marks aren't needed in most cases. - The (unusual) <code>".*test rule"</code> example needs quotes: it - starts with a period and contains a space. - Quoting <code>"cc_library"</code> is unnecessary but harmless. - </p> - - <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. - //foo:bar=wiz # WRONG: scanned as //foo:bar = wiz. - "//foo:bar+wiz" # ok. - "//foo:bar=wiz" # ok. - </pre> - <p> - Note that this quoting is in addition to any quoting that may - be required by your shell. e.g. - </p> - <pre>% bazel query ' "//foo:bar=wiz" ' # single-quotes for shell, double-quotes for Bazel.</pre> - - <p> - Keywords, when quoted, are treated as ordinary words, thus - <code>some</code> is a keyword but <code>"some"</code> is a word. - Both <code>foo</code> and <code>"foo"</code> are words. - </p> - - <li><b>Punctuation</b>, such as parens <code>()</code>, period - <code>.</code> and comma <code>,</code>, etc. Words containing - punctuation (other than the exceptions listed above) must be quoted. - </ul> - -<p> - Whitespace characters outside of a quoted word are ignored. -</p> - -<h2 id='concepts'>Bazel Query Language Concepts</h2> -<p> - The Bazel query language is a language of expressions. Every - expression evaluates to a <b>partially-ordered set</b> of targets, - or equivalently, a <b>graph</b> (DAG) of targets. This is the only - datatype. -</p> -<p> - In some expressions, the partial order of the graph is - not interesting; In this case, we call the values - "sets". In cases where the partial order of elements - is significant, we call values "graphs". Note - that both terms refer to the same datatype, but merely emphasize - different aspects of it. -</p> - -<h3>Cycles in the dependency graph</h3> -<p> - Build dependency graphs should be acyclic. - - 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> - -<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 be 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. -</p> - -<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 - use the query tool to compute the set of all source files needed - during a build, it may report more than are actually necessary - because, for example, the query tool will include all the files - needed to support message translation, even though you don't intend - to use that feature in your build. -</p> - -<h3 id='graph-order'>On the preservation of graph order</h3> - -<p> - Operations preserve any ordering - constraints inherited from their subexpressions. You can think of - this as "the law of conservation of partial order". Consider an - example: if you issue a query to determine the transitive closure of - dependencies of a particular target, the resulting set is ordered - according to the dependency graph. If you filter that set to - include only the targets of <code>file</code> kind, the same - <em>transitive</em> partial ordering relation holds between every - pair of targets in the resulting subset—even though none of - these pairs is actually directly connected in the original graph. - (There are no file–file edges in the build dependency graph). -</p> - -<p> - However, while all operators <em>preserve</em> order, some - operations, such as the <a href='#set-operations'>set operations</a> - don't <em>introduce</em> any ordering constraints of their own. - Consider this expression: -</p> - -<pre>deps(x) union y</pre> - -<p> - The order of the final result set is guaranteed to preserve all the - ordering constraints of its subexpressions, namely, that all the - transitive dependencies of <code>x</code> are correctly ordered with - respect to each other. However, the query guarantees nothing about - the ordering of the targets in <code>y</code>, nor about the - ordering of the targets in <code>deps(x)</code> relative to those in - <code>y</code> (except for those targets in - <code>y</code> that also happen to be in <code>deps(x)</code>). -</p> - -<p> - Operators that introduce ordering constraints include: - <code>allpaths</code>, - <code>deps</code>, - <code>rdeps</code>, - <code>somepath</code>, - and the target pattern wildcards - <code>package:*</code>, - <code>dir/...</code>, etc. -</p> - -<h2>Expressions: syntax and semantics of the grammar</h2> - -<p> - This is the grammar of the Bazel query language, expressed in EBNF - notation: -</p> - - -<pre>expr ::= <var>word</var> - | let <var>name</var> = <var>expr</var> in <var>expr</var> - | (<var>expr</var>) - | <var>expr</var> intersect <var>expr</var> - | <var>expr</var> ^ <var>expr</var> - | <var>expr</var> union <var>expr</var> - | <var>expr</var> + <var>expr</var> - | <var>expr</var> except <var>expr</var> - | <var>expr</var> - <var>expr</var> - | deps(<var>expr</var>) - | deps(<var>expr</var>, <var>depth</var>) - | rdeps(<var>expr</var>, <var>expr</var>) - | rdeps(<var>expr</var>, <var>expr</var>, <var>depth</var>) - | some(<var>expr</var>) - | somepath(<var>expr</var>, <var>expr</var>) - | allpaths(<var>expr</var>, <var>expr</var>) - | kind(<var>word</var>, <var>expr</var>) - | labels(<var>word</var>, <var>expr</var>) - | filter(<var>word</var>, <var>expr</var>) - | set(<var>word</var> *) - | attr(<var>word</var>, <var>word</var>, <var>expr</var>) -</pre> - -<p> - We will examine each of the productions of this grammar in order. -</p> - -<h3 id="target-patterns">Target patterns</h3> -<pre>expr ::= <var>word</var></pre> -<p> - Syntactically, a <em>target pattern</em> is just a word. It - 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>//foo:bar</code> evaluates to a set - containing one element, the target, the <code>bar</code> - rule. -</p> - -<p> - Target patterns generalize labels to include wildcards over packages - and targets. For example, <code>foo/...:all</code> (or - 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>bar/baz:all</code> is a target pattern that - evaluates to a set containing all the rules in the - <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>bar/baz:*</code> evaluates to a set containing - all the targets in the - <code>bar/baz</code> package, but not its subpackages. -</p> - -<p> - Because the <code>:*</code> wildcard matches files as well as rules, - it is often more useful than <code>:all</code> for queries. - Conversely, the <code>:all</code> wildcard (implicit in target - patterns like <code>foo/...</code>) is typically more useful for - builds. -</p> - -<p> - <code>bazel query</code> target patterns work the same as - <code>bazel build</code> build targets do; - 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> - Target patterns may evaluate to a singleton set (in the case of a - label), to a set containing many elements (as in the case of - <code>foo/...</code>, which has thousands of elements) or to the - empty set, if the target pattern matches no targets. -</p> - -<p> - All nodes in the result of a target pattern expression are correctly - ordered relative to each other according to the dependency relation. - So, the result of <code>foo:*</code> is not just the set of targets - in package <code>foo</code>, it is also the <em>graph</em> over - those targets. (No guarantees are made about the relative ordering - of the result nodes against other nodes.) See the section - on <a href='#graph-order'>graph order</a> for more details. -</p> - -<h3 id="variables">Variables</h3> -<pre>expr ::= let <var>name</var> = <var>expr</var><sub>1</sub> in <var>expr</var><sub>2</sub> - | <var>$name</var></pre> -<p> - The Bazel query language allows definitions of and references to - variables. The - result of evaluation of a <code>let</code> expression is the same as - that of <var>expr</var><sub>2</sub>, with all free occurrences of - variable <var>name</var> replaced by the value of - <var>expr</var><sub>1</sub>. -</p> - -<p> - For example, <code>let v = foo/... in allpaths($v, //common) - intersect $v</code> is equivalent to the <code>allpaths(foo/..., - //common) intersect foo/...</code>. -</p> - -<p> - An occurrence of a variable reference <code>name</code> other than in - an enclosing <code>let <var>name</var> = ...</code> expression is an - error. In other words, toplevel query expressions cannot have free - variables. -</p> - -<p> - In the above grammar productions, <code>name</code> is like - <em>word</em>, but with the additional constraint that it be a legal - identifier in the C programming language. References to the variable - must be prepended with the "$" character. -</p> - -<p> - Each <code>let</code> expression defines only a single variable, - but you can nest them. -</p> - -<p> - (Both <a - href='#target-patterns'>target patterns</a> and variable references - consist of just a single token, a word, creating a syntactic - ambiguity. However, there is no semantic ambiguity, because the - subset of words that are legal variable names is disjoint from the - subset of words that are legal target patterns.) -</p> - -<p> - (Technically speaking, <code>let</code> expressions do not increase - the expressiveness of the query language: any query expressible in - the language can also be expressed without them. However, they - improve the conciseness of many queries, and may also lead to more - efficient query evaluation.) -</p> - -<h3 id="parentheses">Parenthesized expressions</h3> -<pre>expr ::= (<var>expr</var>)</pre> - -<p> - Parentheses associate subexpressions to force an - order of evaluation. - A parenthesized expression evaluates - to the value of its argument. -</p> - -<h3 id="set-operations">Algebraic set operations: - intersection, union, set difference</h3> - -<pre>expr ::= <var>expr</var> intersect <var>expr</var> - | <var>expr</var> ^ <var>expr</var> - | <var>expr</var> union <var>expr</var> - | <var>expr</var> + <var>expr</var> - | <var>expr</var> except <var>expr</var> - | <var>expr</var> - <var>expr</var> -</pre> - -<p> - These three operators compute the usual set operations over their - arguments. Each operator has two forms, a nominal form such - as <code>intersect</code> and a symbolic form such - as <code>^</code>. Both forms are equivalent; - the symbolic forms are quicker to type. (For clarity, the rest of - this manual uses the nominal forms.) For example, -</p> - -<pre>foo/... except foo/bar/...</pre> - - evaluates to the set of targets that match - <code>foo/...</code> but not - <code>foo/bar/...</code> . Equivalently: - -<pre>foo/... - foo/bar/...</pre> - - The <code>intersect</code> (<code>^</code>) - and <code>union</code> (<code>+</code>) operations are commutative - (symmetric); <code>except</code> (<code>-</code>) is - asymmetric. The parser treats all three operators as - left-associative and of equal precedence, so you might want parentheses. - For example, the first two of these expressions are - equivalent, but the third is not: - -<pre>x intersect y union z -(x intersect y) union z -x intersect (y union z)</pre> - -<p> - (We strongly recommend that you use parentheses where there is - any danger of ambiguity in reading a query expression.) -</p> - -<h3 id="set">Read targets from an external source: set</h3> -<pre>expr ::= set(<var>word</var> *) </pre> -<p> - The <code>set(<var>a</var> <var>b</var> <var>c</var> ...)</code> - operator computes the union of a set of zero or - more <a href='#target-patterns'>target patterns</a>, separated by - whitespace (no commas). -</p> - -<p> - In conjunction with the Bourne shell's <code>$(...)</code> - feature, <code>set()</code> provides a means of saving the results - of one query in a regular text file, manipulating that text file - using other programs (e.g. standard UNIX shell tools), and then - introducing the result back into the query tool as a value for - further processing. For example: -</p> -<pre> - % 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(//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(//some_dir/foo:main)' --output maxrank | - awk '($1 < 5) { print $2;} ' > foo - % bazel query "kind(cc_library, set($(<foo)))" -</pre> -<p> - In these examples, <code>$(<foo)</code> is a shorthand - for <code>$(cat foo)</code>, but shell commands other - than <code>cat</code> may be used too—such as - the previous <code>awk</code> command. -</p> - -<p> - Note, <code>set()</code> introduces no graph ordering constraints, - so path information may be lost when saving and reloading sets of - nodes using it. See the <a href='#graph-order'>graph order</a> - section below for more detail. -</p> - -<h3 id="deps">Transitive closure of dependencies: deps</h3> -<pre>expr ::= deps(<var>expr</var>) - | deps(<var>expr</var>, <var>depth</var>)</pre> -<p> - The <code>deps(<var>x</var>)</code> operator evaluates to the graph - formed by the transitive closure of dependencies of its argument set - <var>x</var>. For example, the value of <code>deps(//foo)</code> is - the dependency graph rooted at the single node <code>foo</code>, - including all its dependencies. The value of - <code>deps(foo/...)</code> is the dependency graphs whose roots are - all rules in every package beneath the <code>foo</code> directory. - Please note that 'dependencies' means only rule and file targets - in this context, therefore the BUILD, - - and Skylark files needed to - create these targets are not included here. For that you should use the - <a href="#buildfiles"><code>buildfiles</code></a> operator. -</p> - -<p> - The resulting graph is ordered according to the dependency relation. - See the section on <a href='#graph-order'>graph order</a> for more - details. -</p> - -<p> - The <code>deps</code> operator accepts an optional second argument, - which is an integer literal specifying an upper bound on the depth - of the search. So <code>deps(foo:*, 1)</code> evaluates to all the - direct prerequisites of any target in the <code>foo</code> package, - and <code>deps(foo:*, 2)</code> further includes the nodes directly - reachable from the nodes in <code>deps(foo:*, 1)</code>, and so on. - (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, i.e. it computes the reflexive transitive closure of - prerequsites. -</p> - -<h3 id="rdeps">Transitive closure of reverse dependencies: rdeps</h3> -<pre>expr ::= rdeps(<var>expr</var>, <var>expr</var>) - | rdeps(<var>expr</var>, <var>expr</var>, <var>depth</var>)</pre> -<p> - The <code>rdeps(<var>u</var>, <var>x</var>)</code> operator evaluates - to the reverse dependencies of the argument set <var>x</var> within the - transitive closure of the universe set <var>u</var>. -</p> - -<p> - The resulting graph is ordered according to the dependency relation. See the - section on <a href='#graph-order'>graph order</a> for more details. -</p> - -<p> - The <code>rdeps</code> operator accepts an optional third argument, - which is an integer literal specifying an upper bound on the depth of the - 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 - <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. -</p> - -<h3 id="some">Arbitrary choice: some</h3> -<pre>expr ::= some(<var>expr</var>)</pre> -<p> - 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: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: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:main intersect //bar:baz)</code>. -</p> - -<h3 id="path-operators">Path operators: somepath, allpaths</h3> -<pre>expr ::= somepath(<var>expr</var>, <var>expr</var>) - | allpaths(<var>expr</var>, <var>expr</var>)</pre> -<p> - The <code>somepath(<var>S</var>, <var>E</var>)</code> and - <code>allpaths(<var>S</var>, <var>E</var>)</code> operators compute - paths between two sets of targets. Both queries accept two - arguments, a set <var>S</var> of starting points and a set - <var>E</var> of ending points. <code>somepath</code> returns the - graph of nodes on <em>some</em> arbitrary path from a target in - <var>S</var> to a target in <var>E</var>; <code>allpaths</code> - returns the graph of nodes on <em>all</em> paths from any target in - <var>S</var> to any target in <var>E</var>. -</p> - -<p> - The resulting graphs are ordered according to the dependency relation. - See the section on <a href='#graph-order'>graph order</a> for more - details. -</p> - -<table style='margin: auto'><tr> -<td style='text-align: center'> -<svg width="153pt" height="288pt" - viewBox="0.00 0.00 153.40 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.839179 0.839179) rotate(0) translate(4 339.193)"> -<title>somepath1</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-339.193 178.798,-339.193 178.798,4 -4,4"/> -<!-- n1 --> -<g id="node1" class="node"> -<title>n1</title> -<ellipse fill="none" stroke="black" cx="40" cy="-314.394" rx="18" ry="18"/> -</g> -<!-- n2 --> -<g id="node2" class="node"> -<title>n2</title> -<ellipse fill="pink" stroke="black" cx="41" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n1->n2 --> -<g id="edge1" class="edge"> -<title>n1->n2</title> -<path fill="none" stroke="black" d="M40.2269,-296.24C40.3484,-287.058 40.5009,-275.531 40.6382,-265.147"/> -<polygon fill="black" stroke="black" points="44.1413,-264.93 40.774,-254.884 37.1419,-264.837 44.1413,-264.93"/> -</g> -<!-- n3 --> -<g id="node3" class="node"> -<title>n3</title> -<ellipse fill="pink" stroke="black" cx="18" cy="-162" rx="18" ry="18"/> -</g> -<!-- n2->n3 --> -<g id="edge2" class="edge"> -<title>n2->n3</title> -<path fill="none" stroke="black" d="M35.7809,-219.279C32.9579,-210.344 29.4064,-199.103 26.2211,-189.021"/> -<polygon fill="black" stroke="black" points="29.5485,-187.935 23.1984,-179.454 22.8737,-190.044 29.5485,-187.935"/> -</g> -<!-- n10 --> -<g id="node10" class="node"> -<title>n10</title> -<ellipse fill="pink" stroke="black" cx="37" cy="-90" rx="18" ry="18"/> -</g> -<!-- n2->n10 --> -<g id="edge9" class="edge"> -<title>n2->n10</title> -<path fill="none" stroke="black" d="M42.9371,-218.86C44.7656,-200.425 46.9578,-170.088 45,-144 44.3634,-135.518 43.1616,-126.336 41.8792,-118.036"/> -<polygon fill="black" stroke="black" points="45.3237,-117.412 40.2483,-108.112 38.4164,-118.547 45.3237,-117.412"/> -</g> -<!-- n3->n10 --> -<g id="edge10" class="edge"> -<title>n3->n10</title> -<path fill="none" stroke="black" d="M22.5027,-144.411C24.7033,-136.304 27.404,-126.354 29.8755,-117.248"/> -<polygon fill="black" stroke="black" points="33.2878,-118.038 32.5296,-107.47 26.5322,-116.204 33.2878,-118.038"/> -</g> -<!-- n4 --> -<g id="node4" class="node"> -<title>n4</title> -<ellipse fill="pink" stroke="black" cx="87" cy="-18" rx="18" ry="18"/> -<text text-anchor="middle" x="87" y="-14.3" font-family="arial" font-size="14.00">E</text> -</g> -<!-- n5 --> -<g id="node5" class="node"> -<title>n5</title> -<ellipse fill="none" stroke="black" cx="97" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n6 --> -<g id="node6" class="node"> -<title>n6</title> -<ellipse fill="none" stroke="black" cx="121" cy="-162" rx="18" ry="18"/> -</g> -<!-- n5->n6 --> -<g id="edge5" class="edge"> -<title>n5->n6</title> -<path fill="none" stroke="black" d="M102.446,-219.279C105.413,-210.281 109.15,-198.944 112.492,-188.808"/> -<polygon fill="black" stroke="black" points="115.851,-189.796 115.658,-179.203 109.203,-187.604 115.851,-189.796"/> -</g> -<!-- n6->n4 --> -<g id="edge6" class="edge"> -<title>n6->n4</title> -<path fill="none" stroke="black" d="M115.99,-144.365C112.931,-133.96 109.038,-120.252 106,-108 100.867,-87.3 95.8646,-63.6851 92.2822,-45.9844"/> -<polygon fill="black" stroke="black" points="95.6398,-44.9258 90.2466,-35.8064 88.7758,-46.2987 95.6398,-44.9258"/> -</g> -<!-- n9 --> -<g id="node9" class="node"> -<title>n9</title> -<ellipse fill="none" stroke="black" cx="133" cy="-90" rx="18" ry="18"/> -</g> -<!-- n6->n9 --> -<g id="edge8" class="edge"> -<title>n6->n9</title> -<path fill="none" stroke="black" d="M123.905,-144.055C125.261,-136.145 126.907,-126.54 128.425,-117.688"/> -<polygon fill="black" stroke="black" points="131.882,-118.237 130.122,-107.789 124.982,-117.054 131.882,-118.237"/> -</g> -<!-- n7 --> -<g id="node7" class="node"> -<title>n7</title> -<ellipse fill="pink" stroke="black" cx="97" cy="-314.394" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="97" y="-310.694" font-family="arial" font-size="14.00">S1</text> -</g> -<!-- n7->n2 --> -<g id="edge4" class="edge"> -<title>n7->n2</title> -<path fill="none" stroke="black" d="M84.8488,-296.991C76.7726,-286.089 66.0734,-271.646 57.2656,-259.756"/> -<polygon fill="black" stroke="black" points="60.0158,-257.588 51.2509,-251.636 54.391,-261.755 60.0158,-257.588"/> -</g> -<!-- n7->n5 --> -<g id="edge3" class="edge"> -<title>n7->n5</title> -<path fill="none" stroke="black" d="M97,-293.532C97,-284.887 97,-274.612 97,-265.254"/> -<polygon fill="black" stroke="black" points="100.5,-265.213 97,-255.213 93.5001,-265.213 100.5,-265.213"/> -</g> -<!-- n8 --> -<g id="node8" class="node"> -<title>n8</title> -<ellipse fill="none" stroke="black" cx="154" cy="-236.798" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="154" y="-233.098" font-family="arial" font-size="14.00">S2</text> -</g> -<!-- n8->n6 --> -<g id="edge7" class="edge"> -<title>n8->n6</title> -<path fill="none" stroke="black" d="M145.673,-217.428C141.606,-208.456 136.653,-197.53 132.254,-187.827"/> -<polygon fill="black" stroke="black" points="135.411,-186.313 128.095,-178.651 129.036,-189.204 135.411,-186.313"/> -</g> -<!-- n10->n4 --> -<g id="edge11" class="edge"> -<title>n10->n4</title> -<path fill="none" stroke="black" d="M47.1182,-74.8345C53.9632,-65.2515 63.1483,-52.3924 70.9784,-41.4303"/> -<polygon fill="black" stroke="black" points="73.9325,-43.3162 76.8968,-33.1445 68.2363,-39.2475 73.9325,-43.3162"/> -</g> -<!-- n11 --> -<g id="node11" class="node"> -<title>n11</title> -<ellipse fill="none" stroke="black" cx="33" cy="-18" rx="18" ry="18"/> -</g> -<!-- n10->n11 --> -<g id="edge12" class="edge"> -<title>n10->n11</title> -<path fill="none" stroke="black" d="M36.0112,-71.6966C35.5704,-63.9827 35.0407,-54.7125 34.5493,-46.1124"/> -<polygon fill="black" stroke="black" points="38.0423,-45.8883 33.9774,-36.1043 31.0537,-46.2878 38.0423,-45.8883"/> -</g> -</g> -</svg> -<p><code>somepath(S1 + S2, E)</code>,<br/>one possible result.</p> -</td> -<td style='padding: 40px; text-align: center'> -<svg width="153pt" height="288pt" - viewBox="0.00 0.00 153.40 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.839179 0.839179) rotate(0) translate(4 339.193)"> -<title>somepath2</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-339.193 178.798,-339.193 178.798,4 -4,4"/> -<!-- n1 --> -<g id="node1" class="node"> -<title>n1</title> -<ellipse fill="none" stroke="black" cx="40" cy="-314.394" rx="18" ry="18"/> -</g> -<!-- n2 --> -<g id="node2" class="node"> -<title>n2</title> -<ellipse fill="none" stroke="black" cx="41" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n1->n2 --> -<g id="edge1" class="edge"> -<title>n1->n2</title> -<path fill="none" stroke="black" d="M40.2269,-296.24C40.3484,-287.058 40.5009,-275.531 40.6382,-265.147"/> -<polygon fill="black" stroke="black" points="44.1413,-264.93 40.774,-254.884 37.1419,-264.837 44.1413,-264.93"/> -</g> -<!-- n3 --> -<g id="node3" class="node"> -<title>n3</title> -<ellipse fill="none" stroke="black" cx="18" cy="-162" rx="18" ry="18"/> -</g> -<!-- n2->n3 --> -<g id="edge2" class="edge"> -<title>n2->n3</title> -<path fill="none" stroke="black" d="M35.7809,-219.279C32.9579,-210.344 29.4064,-199.103 26.2211,-189.021"/> -<polygon fill="black" stroke="black" points="29.5485,-187.935 23.1984,-179.454 22.8737,-190.044 29.5485,-187.935"/> -</g> -<!-- n10 --> -<g id="node10" class="node"> -<title>n10</title> -<ellipse fill="none" stroke="black" cx="37" cy="-90" rx="18" ry="18"/> -</g> -<!-- n2->n10 --> -<g id="edge9" class="edge"> -<title>n2->n10</title> -<path fill="none" stroke="black" d="M42.9371,-218.86C44.7656,-200.425 46.9578,-170.088 45,-144 44.3634,-135.518 43.1616,-126.336 41.8792,-118.036"/> -<polygon fill="black" stroke="black" points="45.3237,-117.412 40.2483,-108.112 38.4164,-118.547 45.3237,-117.412"/> -</g> -<!-- n3->n10 --> -<g id="edge10" class="edge"> -<title>n3->n10</title> -<path fill="none" stroke="black" d="M22.5027,-144.411C24.7033,-136.304 27.404,-126.354 29.8755,-117.248"/> -<polygon fill="black" stroke="black" points="33.2878,-118.038 32.5296,-107.47 26.5322,-116.204 33.2878,-118.038"/> -</g> -<!-- n4 --> -<g id="node4" class="node"> -<title>n4</title> -<ellipse fill="pink" stroke="black" cx="87" cy="-18" rx="18" ry="18"/> -<text text-anchor="middle" x="87" y="-14.3" font-family="arial" font-size="14.00">E</text> -</g> -<!-- n5 --> -<g id="node5" class="node"> -<title>n5</title> -<ellipse fill="none" stroke="black" cx="97" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n6 --> -<g id="node6" class="node"> -<title>n6</title> -<ellipse fill="pink" stroke="black" cx="121" cy="-162" rx="18" ry="18"/> -</g> -<!-- n5->n6 --> -<g id="edge5" class="edge"> -<title>n5->n6</title> -<path fill="none" stroke="black" d="M102.446,-219.279C105.413,-210.281 109.15,-198.944 112.492,-188.808"/> -<polygon fill="black" stroke="black" points="115.851,-189.796 115.658,-179.203 109.203,-187.604 115.851,-189.796"/> -</g> -<!-- n6->n4 --> -<g id="edge6" class="edge"> -<title>n6->n4</title> -<path fill="none" stroke="black" d="M115.99,-144.365C112.931,-133.96 109.038,-120.252 106,-108 100.867,-87.3 95.8646,-63.6851 92.2822,-45.9844"/> -<polygon fill="black" stroke="black" points="95.6398,-44.9258 90.2466,-35.8064 88.7758,-46.2987 95.6398,-44.9258"/> -</g> -<!-- n9 --> -<g id="node9" class="node"> -<title>n9</title> -<ellipse fill="none" stroke="black" cx="133" cy="-90" rx="18" ry="18"/> -</g> -<!-- n6->n9 --> -<g id="edge8" class="edge"> -<title>n6->n9</title> -<path fill="none" stroke="black" d="M123.905,-144.055C125.261,-136.145 126.907,-126.54 128.425,-117.688"/> -<polygon fill="black" stroke="black" points="131.882,-118.237 130.122,-107.789 124.982,-117.054 131.882,-118.237"/> -</g> -<!-- n7 --> -<g id="node7" class="node"> -<title>n7</title> -<ellipse fill="none" stroke="black" cx="97" cy="-314.394" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="97" y="-310.694" font-family="arial" font-size="14.00">S1</text> -</g> -<!-- n7->n2 --> -<g id="edge4" class="edge"> -<title>n7->n2</title> -<path fill="none" stroke="black" d="M84.8488,-296.991C76.7726,-286.089 66.0734,-271.646 57.2656,-259.756"/> -<polygon fill="black" stroke="black" points="60.0158,-257.588 51.2509,-251.636 54.391,-261.755 60.0158,-257.588"/> -</g> -<!-- n7->n5 --> -<g id="edge3" class="edge"> -<title>n7->n5</title> -<path fill="none" stroke="black" d="M97,-293.532C97,-284.887 97,-274.612 97,-265.254"/> -<polygon fill="black" stroke="black" points="100.5,-265.213 97,-255.213 93.5001,-265.213 100.5,-265.213"/> -</g> -<!-- n8 --> -<g id="node8" class="node"> -<title>n8</title> -<ellipse fill="pink" stroke="black" cx="154" cy="-236.798" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="154" y="-233.098" font-family="arial" font-size="14.00">S2</text> -</g> -<!-- n8->n6 --> -<g id="edge7" class="edge"> -<title>n8->n6</title> -<path fill="none" stroke="black" d="M145.673,-217.428C141.606,-208.456 136.653,-197.53 132.254,-187.827"/> -<polygon fill="black" stroke="black" points="135.411,-186.313 128.095,-178.651 129.036,-189.204 135.411,-186.313"/> -</g> -<!-- n10->n4 --> -<g id="edge11" class="edge"> -<title>n10->n4</title> -<path fill="none" stroke="black" d="M47.1182,-74.8345C53.9632,-65.2515 63.1483,-52.3924 70.9784,-41.4303"/> -<polygon fill="black" stroke="black" points="73.9325,-43.3162 76.8968,-33.1445 68.2363,-39.2475 73.9325,-43.3162"/> -</g> -<!-- n11 --> -<g id="node11" class="node"> -<title>n11</title> -<ellipse fill="none" stroke="black" cx="33" cy="-18" rx="18" ry="18"/> -</g> -<!-- n10->n11 --> -<g id="edge12" class="edge"> -<title>n10->n11</title> -<path fill="none" stroke="black" d="M36.0112,-71.6966C35.5704,-63.9827 35.0407,-54.7125 34.5493,-46.1124"/> -<polygon fill="black" stroke="black" points="38.0423,-45.8883 33.9774,-36.1043 31.0537,-46.2878 38.0423,-45.8883"/> -</g> -</g> -</svg> -<p><code>somepath(S1 + S2, E)</code>,<br/>another possible result.</p> -</td> -<td style='text-align: center'> -<svg width="153pt" height="288pt" - viewBox="0.00 0.00 153.40 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.839179 0.839179) rotate(0) translate(4 339.193)"> -<title>allpaths</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-339.193 178.798,-339.193 178.798,4 -4,4"/> -<!-- n1 --> -<g id="node1" class="node"> -<title>n1</title> -<ellipse fill="none" stroke="black" cx="40" cy="-314.394" rx="18" ry="18"/> -</g> -<!-- n2 --> -<g id="node2" class="node"> -<title>n2</title> -<ellipse fill="pink" stroke="black" cx="41" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n1->n2 --> -<g id="edge1" class="edge"> -<title>n1->n2</title> -<path fill="none" stroke="black" d="M40.2269,-296.24C40.3484,-287.058 40.5009,-275.531 40.6382,-265.147"/> -<polygon fill="black" stroke="black" points="44.1413,-264.93 40.774,-254.884 37.1419,-264.837 44.1413,-264.93"/> -</g> -<!-- n3 --> -<g id="node3" class="node"> -<title>n3</title> -<ellipse fill="pink" stroke="black" cx="18" cy="-162" rx="18" ry="18"/> -</g> -<!-- n2->n3 --> -<g id="edge2" class="edge"> -<title>n2->n3</title> -<path fill="none" stroke="black" d="M35.7809,-219.279C32.9579,-210.344 29.4064,-199.103 26.2211,-189.021"/> -<polygon fill="black" stroke="black" points="29.5485,-187.935 23.1984,-179.454 22.8737,-190.044 29.5485,-187.935"/> -</g> -<!-- n10 --> -<g id="node10" class="node"> -<title>n10</title> -<ellipse fill="pink" stroke="black" cx="37" cy="-90" rx="18" ry="18"/> -</g> -<!-- n2->n10 --> -<g id="edge9" class="edge"> -<title>n2->n10</title> -<path fill="none" stroke="black" d="M42.9371,-218.86C44.7656,-200.425 46.9578,-170.088 45,-144 44.3634,-135.518 43.1616,-126.336 41.8792,-118.036"/> -<polygon fill="black" stroke="black" points="45.3237,-117.412 40.2483,-108.112 38.4164,-118.547 45.3237,-117.412"/> -</g> -<!-- n3->n10 --> -<g id="edge10" class="edge"> -<title>n3->n10</title> -<path fill="none" stroke="black" d="M22.5027,-144.411C24.7033,-136.304 27.404,-126.354 29.8755,-117.248"/> -<polygon fill="black" stroke="black" points="33.2878,-118.038 32.5296,-107.47 26.5322,-116.204 33.2878,-118.038"/> -</g> -<!-- n4 --> -<g id="node4" class="node"> -<title>n4</title> -<ellipse fill="pink" stroke="black" cx="87" cy="-18" rx="18" ry="18"/> -<text text-anchor="middle" x="87" y="-14.3" font-family="arial" font-size="14.00">E</text> -</g> -<!-- n5 --> -<g id="node5" class="node"> -<title>n5</title> -<ellipse fill="pink" stroke="black" cx="97" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n6 --> -<g id="node6" class="node"> -<title>n6</title> -<ellipse fill="pink" stroke="black" cx="121" cy="-162" rx="18" ry="18"/> -</g> -<!-- n5->n6 --> -<g id="edge5" class="edge"> -<title>n5->n6</title> -<path fill="none" stroke="black" d="M102.446,-219.279C105.413,-210.281 109.15,-198.944 112.492,-188.808"/> -<polygon fill="black" stroke="black" points="115.851,-189.796 115.658,-179.203 109.203,-187.604 115.851,-189.796"/> -</g> -<!-- n6->n4 --> -<g id="edge6" class="edge"> -<title>n6->n4</title> -<path fill="none" stroke="black" d="M115.99,-144.365C112.931,-133.96 109.038,-120.252 106,-108 100.867,-87.3 95.8646,-63.6851 92.2822,-45.9844"/> -<polygon fill="black" stroke="black" points="95.6398,-44.9258 90.2466,-35.8064 88.7758,-46.2987 95.6398,-44.9258"/> -</g> -<!-- n9 --> -<g id="node9" class="node"> -<title>n9</title> -<ellipse fill="none" stroke="black" cx="133" cy="-90" rx="18" ry="18"/> -</g> -<!-- n6->n9 --> -<g id="edge8" class="edge"> -<title>n6->n9</title> -<path fill="none" stroke="black" d="M123.905,-144.055C125.261,-136.145 126.907,-126.54 128.425,-117.688"/> -<polygon fill="black" stroke="black" points="131.882,-118.237 130.122,-107.789 124.982,-117.054 131.882,-118.237"/> -</g> -<!-- n7 --> -<g id="node7" class="node"> -<title>n7</title> -<ellipse fill="pink" stroke="black" cx="97" cy="-314.394" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="97" y="-310.694" font-family="arial" font-size="14.00">S1</text> -</g> -<!-- n7->n2 --> -<g id="edge4" class="edge"> -<title>n7->n2</title> -<path fill="none" stroke="black" d="M84.8488,-296.991C76.7726,-286.089 66.0734,-271.646 57.2656,-259.756"/> -<polygon fill="black" stroke="black" points="60.0158,-257.588 51.2509,-251.636 54.391,-261.755 60.0158,-257.588"/> -</g> -<!-- n7->n5 --> -<g id="edge3" class="edge"> -<title>n7->n5</title> -<path fill="none" stroke="black" d="M97,-293.532C97,-284.887 97,-274.612 97,-265.254"/> -<polygon fill="black" stroke="black" points="100.5,-265.213 97,-255.213 93.5001,-265.213 100.5,-265.213"/> -</g> -<!-- n8 --> -<g id="node8" class="node"> -<title>n8</title> -<ellipse fill="pink" stroke="black" cx="154" cy="-236.798" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="154" y="-233.098" font-family="arial" font-size="14.00">S2</text> -</g> -<!-- n8->n6 --> -<g id="edge7" class="edge"> -<title>n8->n6</title> -<path fill="none" stroke="black" d="M145.673,-217.428C141.606,-208.456 136.653,-197.53 132.254,-187.827"/> -<polygon fill="black" stroke="black" points="135.411,-186.313 128.095,-178.651 129.036,-189.204 135.411,-186.313"/> -</g> -<!-- n10->n4 --> -<g id="edge11" class="edge"> -<title>n10->n4</title> -<path fill="none" stroke="black" d="M47.1182,-74.8345C53.9632,-65.2515 63.1483,-52.3924 70.9784,-41.4303"/> -<polygon fill="black" stroke="black" points="73.9325,-43.3162 76.8968,-33.1445 68.2363,-39.2475 73.9325,-43.3162"/> -</g> -<!-- n11 --> -<g id="node11" class="node"> -<title>n11</title> -<ellipse fill="none" stroke="black" cx="33" cy="-18" rx="18" ry="18"/> -</g> -<!-- n10->n11 --> -<g id="edge12" class="edge"> -<title>n10->n11</title> -<path fill="none" stroke="black" d="M36.0112,-71.6966C35.5704,-63.9827 35.0407,-54.7125 34.5493,-46.1124"/> -<polygon fill="black" stroke="black" points="38.0423,-45.8883 33.9774,-36.1043 31.0537,-46.2878 38.0423,-45.8883"/> -</g> -</g> -</svg> -<p><code>allpaths(S1 + S2, E)</code>.</p> -</td> -</tr></table> - -<h3 id="kind">Target kind filtering: kind</h3> -<pre>expr ::= kind(<var>word</var>, <var>expr</var>) </pre> -<p> - The <code>kind(<var>pattern</var>, <var>input</var>)</code> operator - applies a filter to a set of targets, and discards those targets - that are not of the expected kind. The <var>pattern</var> parameter specifies - what kind of target to match. -</p> -<ul> -<li><b>file</b> patterns can be one of: - <ul> - <li><code>source file</code> - <li><code>generated file</code> - </ul> -<li><b>rule</b> patterns can be one of: - <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. - </ul> -<li><b>package group</b> patterns should simply be: - <ul> - <li><code>package group</code> - </ul> -</ul> -<p> - For example, the kinds for the four targets defined by the BUILD file - (for package <code>p</code>) shown below are illustrated in the - table: -</p> - -<table style='margin: auto'><tr><td style='padding-right:10px'> -<pre style='margin-left: 0em;'> -genrule( - name = "a", - srcs = ["a.in"], - outs = ["a.out"], - cmd = "...", -) -</pre> -</td><td> - <table class="grid"> - <tr><th>Target</th><th>Kind</th></tr> - <tr class='tt'><td>//p:a</td><td>genrule rule</td></tr> - <tr class='tt'><td>//p:a.in</td><td>source file</td></tr> - <tr class='tt'><td>//p:a.out</td><td>generated file</td></tr> - <tr class='tt'><td>//p:BUILD</td><td>source file</td></tr> - </table> -</td></tr></table> - -<p> - Thus, <code>kind("cc_.* rule", foo/...)</code> evaluates to the set - of all <code>cc_library</code>, <code>cc_binary</code>, etc, - rule targets beneath - <code>foo</code>, and <code>kind("source file", deps(//foo))</code> - evaluates to the set of all source files in the transitive closure - of dependencies of the <code>//foo</code> target. -</p> - -<p> - Quotation of the <var>pattern</var> argument is often required - because without it, many regular expressions, such as <code>source - file</code> and <code>.*_test</code>, are not considered words by - the parser. -</p> - -<p> - When matching for <code>package group</code>, targets ending in - <code>:all</code> may not yield any results. - Use <code>:all-targets</code> instead. -</p> - -<h3 id="filter">Target name filtering: filter</h3> -<pre>expr ::= filter(<var>word</var>, <var>expr</var>) </pre> -<p> - The <code>filter(<var>pattern</var>, <var>input</var>)</code> operator - applies a filter to a set of targets, and discards targets whose - labels (in absolute form) do not match the pattern; it - evaluates to a subset of its input. -</p> - -<p> - The first argument, <var>pattern</var> is a word containing a - regular expression over target names. A <code>filter</code> expression - evaluates to the set containing all targets <var>x</var> such that - <var>x</var> is a member of the set <var>input</var> and the - label (in absolute form, e.g. <code>//foo:bar</code>) - of <var>x</var> contains an (unanchored) match - for the regular expression <var>pattern</var>. Since all - target names start with <code>//</code>, it may be used as an alternative - to the <code>^</code> regular expression anchor. -</p> - -<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 - <code>bar</code> dependencies of the <code>//foo:foo</code> target, one could - evaluate -</p> -<pre>deps(//foo) intersect //bar/...</pre> -<p> - This statement, however, will require parsing of all BUILD files in the - <code>bar</code> tree, which will be slow and prone to errors in - irrelevant BUILD files. An alternative would be: -</p> -<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>//bar</code> as a - substring. -</p> - -<p> - Another common use of the <code>filter(<var>pattern</var>, - <var>expr</var>)</code> operator is to filter specific files by their - name or extension. For example, -</p> -<pre>filter("\.cc$", deps(//foo))</pre> -<p> - 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> -<pre>expr ::= attr(<var>word</var>, <var>word</var>, <var>expr</var>) </pre> -<p> - The <code>attr(<var>name</var>, <var>pattern</var>, <var>input</var>)</code> - operator applies a filter to a set of targets, and discards targets that - are not rules, rule targets that do not have attribute <var>name</var> - defined or rule targets where the attribute value does not match the provided - regular expression <var>pattern</var>; it evaluates to a subset of its input. -</p> - -<p> - The first argument, <var>name</var> is the name of the rule attribute that - should be matched against the provided regular expression pattern. The second - argument, <var>pattern</var> is a regular expression over the attribute - values. An <code>attr</code> expression evaluates to the set containing all - targets <var>x</var> such that <var>x</var> is a member of the set - <var>input</var>, is a rule with the defined attribute <var>name</var> and - the attribute value contains an (unanchored) match for the regular expression - <var>pattern</var>. Please note, that if <var>name</var> is an optional - attribute and rule does not specify it explicitly then default attribute - value will be used for comparison. For example, -</p> -<pre>attr(linkshared, 0, deps(//foo))</pre> -<p> - will select all <code>//foo</code> dependencies that are allowed to have a - linkshared attribute (e.g., <code>cc_binary</code> rule) and have it either - explicitly set to 0 or do not set it at all but default value is 0 (e.g. for - <code>cc_binary</code> rules). -</p> - -<p> - List-type attributes (such as <code>srcs</code>, <code>data</code>, etc) are - converted to strings of the form <code>[value<sub>1</sub>, ..., value<sub>n</sub>]</code>, - starting with a <code>[</code> bracket, ending with a <code>]</code> bracket - and using "<code>, </code>" (comma, space) to delimit multiple values. - Labels are converted to strings by using the absolute form of the - label. For example, an attribute <code>deps=[":foo", - "//otherpkg:bar", "wiz"]</code> would be converted to the - string <code>[//thispkg:foo, //otherpkg:bar, //thispkg:wiz]</code>. - Brackets - are always present, so the empty list would use string value <code>[]</code> - for matching purposes. For example, -</p> -<pre>attr("srcs", "\[\]", deps(//foo))</pre> -<p> - will select all rules among <code>//foo</code> dependencies that have an - empty <code>srcs</code> attribute, while -</p> -<pre>attr("data", ".{3,}", deps(//foo))</pre> -<p> - will select all rules among <code>//foo</code> dependencies that specify at - least one value in the <code>data</code> attribute (every label is at least - 3 characters long due to the <code>//</code> and <code>:</code>). -</p> - -<h3 id="visible">Rule visibility filtering: visible</h3> -<pre>expr ::= visible(<var>expr</var>, <var>expr</var>) </pre> -<p> - The <code>visible(<var>predicate</var>, <var>input</var>)</code> operator - applies a filter to a set of targets, and discards targets without the - required visibility. -</p> - -<p> - The first argument, <var>predicate</var>, is a set of targets that all targets - in the output must be visible to. A <var>visible</var> expression - evaluates to the set containing all targets <var>x</var> such that <var>x</var> - is a member of the set <var>input</var>, and for all targets <var>y</var> in - <var>predicate</var> <var>x</var> is visible to <var>y</var>. For example: -</p> -<pre>visible(//foo, //bar:*)</pre> -<p> - will select all targets in the package <code>//bar</code> that <code>//foo</code> - can depend on without violating visibility restrictions. -</p> - -<h3 id="labels">Evaluation of rule attributes of type label: labels</h3> -<pre>expr ::= labels(<var>word</var>, <var>expr</var>) </pre> -<p> - The <code>labels(<var>attr_name</var>, <var>inputs</var>)</code> - operator returns the set of targets specified in the - attribute <var>attr_name</var> of type "label" or "list of label" in - some rule in set <var>inputs</var>. -</p> - -<p> - For example, <code>labels(srcs, //foo)</code> returns the set of - targets appearing in the <code>srcs</code> attribute of - the <code>//foo</code> rule. If there are multiple rules - with <code>srcs</code> attributes in the <var>inputs</var> set, the - union of their <code>srcs</code> is returned. -</p> - -<p> - Please note, <code>deps</code> is a reserved word in the query - language, so you must quote it if you wish to query the rule - attribute of that name in a <code>labels</code> expression: - <code>labels("deps", //foo)</code>. -</p> - -<h3 id="tests">Expand and filter test_suites: tests</h3> -<pre>expr ::= tests(<var>expr</var>)</pre> -<p> - 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 - 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> - -<p> - For example, the query <code>kind(test, foo:*)</code> lists all - the <code>*_test</code> and <code>test_suite</code> rules - in the <code>foo</code> package. All the results are (by - definition) members of the <code>foo</code> package. In contrast, - the query <code>tests(foo:*)</code> will return all of the - individual tests that would be executed by <code>bazel test - foo:*</code>: this may include tests belonging to other packages, - that are referenced directly or indirectly - via <code>test_suite</code> rules. -</p> - - -<h3 id="buildfiles">Package definition files: buildfiles</h3> -<pre>expr ::= buildfiles(<var>expr</var>)</pre> -<p> - The <code>buildfiles(<var>x</var>)</code> operator returns the set - 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>load</code>. Note that this also returns the BUILD files of the - packages containing these <code>load</code>ed files. -</p> - -<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 files - that are <code>load()</code>'ed - - will be missing. -</p> - -<h3 id="loadfiles">Package definition files: loadfiles</h3> -<pre>expr ::= loadfiles(<var>expr</var>)</pre> -<p> - The <code>loadfiles(<var>x</var>)</code> operator returns the set of - Skylark files that are needed to load the packages of each target in - set <var>x</var>. In other words, for each package, it returns the - .bzl files that are referenced from its BUILD files. -</p> - -<h2>Output formats</h2> - -<p> - <code>bazel query</code> generates a graph. - You specify the content, format, and ordering by which - <code>bazel query</code> presents this graph - by means of the <code>--output</code> - command-line option. - </p> - -<p> - Some of the output formats accept additional options. The name of - each output option is prefixed with the output format to which it - applies, so <code>--graph:factored</code> applies only - when <code>--output=graph</code> is being used; it has no effect if - an output format other than <code>graph</code> is used. Similarly, - <code>--xml:line_numbers</code> applies only when <code>--output=xml</code> - 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. Moreover, nodes that are - equivalent in the dependency order may or may not be ordered alphabetically. - The <code>--order_output</code> flag can be used to control this behavior. - (The <code>--[no]order_results</code> flag has a subset of the functionality - of the <code>--order_output</code> flag and is deprecated.) -</p> -<p> - The default value of this flag is <code>auto</code>, which is equivalent to - <code>full</code> for every output format except for <code>proto</code>, - <code>graph</code>, <code>minrank</code>, and <code>maxrank</code>, for which - it is equivalent to <code>deps</code>. -</p> -<p> - When this flag is <code>no</code> and <code>--output</code> is one of - <code>build</code>, <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 the fastest option</b>. It is not - supported though when <code>--output</code> is one of <code>graph</code>, - <code>min_rank</code> or <code>max_rank</code>: with these formats, bazel will - always print results ordered by the dependency order or rank. -</p> -<p> - When this flag is <code>deps</code>, bazel will print results ordered by the - dependency order. However, nodes that are unordered by the dependency order - (because there is no path from either one to the other) may be printed in any - order. -</p> -<p> - When this flag is <code>full</code>, bazel will print results ordered by the - dependency order, with unordered nodes ordered alphabetically or reverse - alphabetically, depending on the output format. This may be slower than the - other options, and so should only be used when deterministic results are - important — it is guaranteed with this option that running the same query - multiple times will always produce the same output. -</p> - -<h3 id="output-build">Print the source form of targets as they would appear in BUILD</h3> -<pre>--output build</pre> -<p> - With this option, the representation of each target is as if it were - hand-written in the BUILD language. All variables and function calls - (e.g. glob, macros) are expanded, which is useful for seeing the effect - of Skylark macros. Additionally, each effective rule is annotated with - the name of the macro (if any, see <code>generator_name</code> and - <code>generator_function</code>) that produced it. -</p> -<p> - Although the output uses the same syntax as BUILD files, it is not - guaranteed to produce a valid BUILD file. -</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 (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. - - When printing the output of a <code>somepath</code> query, the order - in which the nodes are printed is the order of the path. -</p> - -<p> - Caveat: in some corner cases, there may be two distinct targets with - the same label; for example, a <code>sh_binary</code> rule and its - sole (implicit) <code>srcs</code> file may both be called - <code>foo.sh</code>. If the result of a query contains both of - these targets, the output (in <code>label</code> format) will appear - to contain a duplicate. When using the <code>label_kind</code> (see - below) format, the distinction becomes clear: the two targets have - the same name, but one has kind <code>sh_binary rule</code> and the - other kind <code>source file</code>. -</p> - -<h3 id="output-label_kind">Print the label and kind of each target</h3> -<pre>--output label_kind</pre> -<p> - Like <code>label</code>, this output format prints the labels of - each target in the resulting graph, in topological order, but it - additionally precedes the label by - the <a href='#kind'><em>kind</em></a> of the target. -</p> - -<h3 id="output-ranked">Print the label of each target, in rank order</h3> -<pre>--output minrank ---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. 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> - There are two variants of this format: <code>minrank</code> ranks - each node by the length of the shortest path from a root node to it. - "Root" nodes (those which have no incoming edges) are of rank 0, - their successors are of rank 1, etc. (As always, edges point from a - target to its prerequisites: the targets it depends upon.) -</p> - -<p> - <code>maxrank</code> ranks each node by the length of the longest - path from a root node to it. Again, "roots" have rank 0, all other - nodes have a rank which is one greater than the maximum rank of all - their predecessors. -</p> - -<p> - All nodes in a cycle are considered of equal rank. (Most graphs are - acyclic, but cycles do occur - simply because BUILD files contain erroneous cycles.) -</p> - -<p> - These output formats are useful for discovering how deep a graph is. - If used for the result of a <code>deps(x)</code>, <code>rdeps(x)</code>, - or <code>allpaths</code> query, then the rank number is equal to the - length of the shortest (with <code>minrank</code>) or longest - (with <code>maxrank</code>) path from <code>x</code> to a node in - that rank. <code>maxrank</code> can be used to determine the - longest sequence of build steps required to build a target. -</p> - -<p> - Please note, the ranked output of a <code>somepath</code> query is - basically meaningless because <code>somepath</code> doesn't - guarantee to return either a shortest or a longest path, and it may - include "transitive" edges from one path node to another that are - not direct edges in original graph. -</p> - -<p> - For example, the graph on the left yields the outputs on the right - when <code>--output minrank</code> and <code>--output maxrank</code> - are specified, respectively. -</p> - -<table style='margin: auto'><tr><td> -<svg width="169pt" height="260pt" - viewBox="0.00 0.00 169.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 fill="white" stroke="transparent" points="-4,4 -4,-256 165,-256 165,4 -4,4"/> -<!-- //a:a --> -<g id="node1" class="node"> -<title>//a:a</title> -<polygon fill="none" stroke="black" points="65.5,-108 11.5,-108 11.5,-72 65.5,-72 65.5,-108"/> -<text text-anchor="middle" x="38.5" y="-86.3" font-family="arial" font-size="14.00">//a:a</text> -</g> -<!-- //a:a.cc --> -<g id="node2" class="node"> -<title>//a:a.cc</title> -<polygon fill="none" stroke="black" points="77,-36 0,-36 0,-0 77,-0 77,-36"/> -<text text-anchor="middle" x="38.5" y="-14.3" font-family="arial" font-size="14.00">//a:a.cc</text> -</g> -<!-- //a:a->//a:a.cc --> -<g id="edge1" class="edge"> -<title>//a:a->//a:a.cc</title> -<path fill="none" stroke="black" d="M38.5,-71.6966C38.5,-63.9827 38.5,-54.7125 38.5,-46.1124"/> -<polygon fill="black" stroke="black" points="42.0001,-46.1043 38.5,-36.1043 35.0001,-46.1044 42.0001,-46.1043"/> -</g> -<!-- //b:b --> -<g id="node3" class="node"> -<title>//b:b</title> -<polygon fill="none" stroke="black" points="120.5,-180 66.5,-180 66.5,-144 120.5,-144 120.5,-180"/> -<text text-anchor="middle" x="93.5" y="-158.3" font-family="arial" font-size="14.00">//b:b</text> -</g> -<!-- //b:b->//a:a --> -<g id="edge2" class="edge"> -<title>//b:b->//a:a</title> -<path fill="none" stroke="black" d="M79.9045,-143.697C73.3773,-135.389 65.432,-125.277 58.2534,-116.141"/> -<polygon fill="black" stroke="black" points="60.8695,-113.805 51.9391,-108.104 55.3653,-118.13 60.8695,-113.805"/> -</g> -<!-- //b:b.cc --> -<g id="node4" class="node"> -<title>//b:b.cc</title> -<polygon fill="none" stroke="black" points="161,-108 84,-108 84,-72 161,-72 161,-108"/> -<text text-anchor="middle" x="122.5" y="-86.3" font-family="arial" font-size="14.00">//b:b.cc</text> -</g> -<!-- //b:b->//b:b.cc --> -<g id="edge3" class="edge"> -<title>//b:b->//b:b.cc</title> -<path fill="none" stroke="black" d="M100.669,-143.697C103.935,-135.813 107.874,-126.304 111.502,-117.546"/> -<polygon fill="black" stroke="black" points="114.82,-118.683 115.414,-108.104 108.353,-116.003 114.82,-118.683"/> -</g> -<!-- //c:c --> -<g id="node5" class="node"> -<title>//c:c</title> -<polygon fill="none" stroke="black" points="92.5,-252 38.5,-252 38.5,-216 92.5,-216 92.5,-252"/> -<text text-anchor="middle" x="65.5" y="-230.3" font-family="arial" font-size="14.00">//c:c</text> -</g> -<!-- //c:c->//a:a --> -<g id="edge5" class="edge"> -<title>//c:c->//a:a</title> -<path fill="none" stroke="black" d="M62.2432,-215.871C57.6415,-191.67 49.188,-147.211 43.7086,-118.393"/> -<polygon fill="black" stroke="black" points="47.0748,-117.359 41.7684,-108.189 40.198,-118.667 47.0748,-117.359"/> -</g> -<!-- //c:c->//b:b --> -<g id="edge4" class="edge"> -<title>//c:c->//b:b</title> -<path fill="none" stroke="black" d="M72.4214,-215.697C75.5747,-207.813 79.3783,-198.304 82.8814,-189.546"/> -<polygon fill="black" stroke="black" points="86.194,-190.689 86.6583,-180.104 79.6946,-188.089 86.194,-190.689"/> -</g> -</g> -</svg> -</td><td> -<pre> -minrank - -0 //c:c -1 //b:b -1 //a:a -2 //b:b.cc -2 //a:a.cc -</pre> -</td><td> -<pre> -maxrank - -0 //c:c -1 //b:b -2 //a:a -2 //b:b.cc -3 //a:a.cc -</pre> -</td></tr></table> - -<h3 id="output-location">Print the location of each target</h3> -<pre>--output location</pre> -<p> - Like <code>label_kind</code>, this option prints out, for each - target in the result, the target's kind and label, but it is - prefixed by a string describing the location of that target, as a - filename and line number. The format resembles the output of - <code>grep</code>. Thus, tools that can parse the latter (such as Emacs - or vi) can also use the query output to step through a series of - matches, allowing the Bazel query tool to be used as a - dependency-graph-aware "grep for BUILD files". -</p> - -<p> - The location information varies by target kind (see the <a - href='#kind'>kind</a> operator). For rules, the - location of the rule's declaration within the BUILD file is printed. - For source files, the location of line 1 of the actual file is - printed. For a generated file, the location of the rule that - generates it is printed. (The query tool does not have sufficient - information to find the actual location of the generated file, and - in any case, it might not exist if a build has not yet been - performed.) -</p> - -<h3 id="output-package">Print the set of packages</h3> -<pre>--output package</pre> -<p> - This option prints the name of all packages to which - some target in the result set belongs. The names are printed in - lexicographical order; duplicates are excluded. Formally, this - is a <em>projection</em> from the set of labels (package, target) onto - packages. -</p> - -<p> - In conjunction with the <code>deps(...)</code> query, this output - option can be used to find the set of packages that must be checked - out in order to build a given set of targets. -</p> - -<h3 id="output-graph">Display a graph of the result</h3> -<pre>--output graph</pre> -<p> - This option causes the query result to be printed as a directed - graph in the popular AT&T GraphViz format. Typically the - result is saved to a file, such as <code>.png</code> or <code>.svg</code>. - (If the <code>dot</code> program is not installed on your workstation, you - can install it using the command <code>sudo apt-get install graphviz</code>.) - See the example section below for a sample invocation. -</p> - -<p> - This output format is particularly useful for <code>allpath</code>, - <code>deps</code>, or <code>rdeps</code> queries, where the result - includes a <em>set of paths</em> that cannot be easily visualized when - rendered in a linear form, such as with <code>--output label</code>. -</p> - -<p> - By default, the graph is rendered in a <em>factored</em> form. That is, - topologically-equivalent nodes are merged together into a single - node with multiple labels. This makes the graph more compact - and readable, because typical result graphs contain highly - repetitive patterns. For example, a <code>java_library</code> rule - may depend on hundreds of Java source files all generated by the - same <code>genrule</code>; in the factored graph, all these files - are represented by a single node. This behavior may be disabled - with the <code>--nograph:factored</code> option. -</p> - -<h4><code>--graph:node_limit <var>n</var></code></h4> -<p> - The option specifies the maximum length of the label string for a - graph node in the output. Longer labels will be truncated; -1 - disables truncation. Due to the factored form in which graphs are - usually printed, the node labels may be very long. GraphViz cannot - handle labels exceeding 1024 characters, which is the default value - of this option. This option has no effect unless - <code>--output=graph</code> is being used. -</p> - -<h4><code>--[no]graph:factored</code></h4> -<p> - By default, graphs are displayed in factored form, as explained - <a href='#output-graph'>above</a>. - When <code>--nograph:factored</code> is specified, graphs are - printed without factoring. This makes visualization using GraphViz - impractical, but the simpler format may ease processing by other - tools (e.g. grep). This option has no effect - unless <code>--output=graph</code> is being used. -</p> - -<h3 id="output-xml">XML</h3> -<pre>--output xml</pre> -<p> - This option causes the resulting targets to be printed in an XML - form. The output starts with an XML header such as this -</p> -<pre> - <?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 (unless - <a href='#result-order'>unordered results</a> are requested), - and then finishes with a terminating -</p> -<pre> -</query> -</pre> -<p> - Simple entries are emitted for targets of <code>file</code> - kind: -</p> -<pre> - <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 - the attributes of the rule, including those whose value was not - explicitly specified in the rule's BUILD file. -</p> -<p> - Additionally, the result includes <code>rule-input</code> and - <code>rule-output</code> elements so that the topology of the - dependency graph can be reconstructed without having to know that, - for example, the elements of the <code>srcs</code> attribute are - forward dependencies (prerequisites) and the contents of the - <code>outs</code> attribute are backward dependencies (consumers). - - <code>rule-input</code> elements for <a - href='#implicit_deps'>implicit dependencies</a> are suppressed if - <code>--noimplicit_deps</code> is specified. -</p> -<pre> - <rule class='cc_binary rule' name='//foo:foo' ...> - <list name='srcs'> - <label value='//foo:foo_main.cc'/> - <label value='//foo:bar.cc'/> - ... - </list> - <list name='deps'> - <label value='//common:common'/> - <label value='//collections:collections'/> - ... - </list> - <list name='data'> - ... - </list> - <int name='linkstatic' value='0'/> - <int name='linkshared' value='0'/> - <list name='licenses'/> - <list name='distribs'> - <distribution value="INTERNAL" /> - </list> - <rule-input name="//common:common" /> - <rule-input name="//collections:collections" /> - <rule-input name="//foo:foo_main.cc" /> - <rule-input name="//foo:bar.cc" /> - ... - </rule> -</pre> - -<p> - Every XML element for a target contains a <code>name</code> - attribute, whose value is the target's label, and - a <code>location</code> attribute, whose value is the target's - location as printed by the <a href='output-location'><code>--output - location</code></a>. -</p> - -<h4><code>--[no]xml:line_numbers</code></h4> -<p> - By default, the locations displayed in the XML output contain line numbers. - When <code>--noxml:line_numbers</code> is specified, line numbers are not - printed. -</p> - -<h4><code>--[no]xml:default_values</code></h4> -<p> - By default, XML output does not include rule attribute whose value - is the default value for that kind of attribute (e.g. because it - were not specified in the BUILD file, or the default value was - provided explicitly). This option causes such attribute values to - be included in the XML output. -</p> - - -<h3 id="external-repos">Querying with external repositories</h3> - -<p> - If the build depends on rules from external repositories (defined in the - WORKSPACE file) then query results will include these dependencies. For - example, if <code>//foo:bar</code> depends on <code>//external:some-lib</code> - and <code>//external:some-lib</code> is bound to - <code>@other-repo//baz:lib</code>, then - <code>bazel query 'deps(//foo:bar)'</code> - will list both <code>@other-repo//baz:lib</code> and - <code>//external:some-lib</code> as dependencies. -</p> - -<p> - External repositories themselves are not dependencies of a build. That is, in - the example above, <code>//external:other-repo</code> is not a dependency. It - can be queried for as a member of the <code>//external</code> package, though, - for example: -<p> - -<pre> - $ # Querying over all members of //external returns the repository. - $ bazel query 'kind(maven_jar, //external:*)' - //external:other-repo - - $ # ...but the repository is not a dependency. - $ bazel query 'kind(maven_jar, deps(//foo:bar))' - INFO: Empty results -</pre> |