From fd9e5a2da94558cc9b4353a694b43379ac8906a1 Mon Sep 17 00:00:00 2001 From: janakr Date: Wed, 6 Dec 2017 09:59:52 -0800 Subject: Document Sky Query, along with its unique operators, allrdeps and rbuildfiles. PiperOrigin-RevId: 178111653 --- site/docs/query.html | 89 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 82 insertions(+), 7 deletions(-) (limited to 'site/docs') diff --git a/site/docs/query.html b/site/docs/query.html index 01560efd15..5ce91c0b81 100644 --- a/site/docs/query.html +++ b/site/docs/query.html @@ -220,6 +220,31 @@ title: Query Language dir/..., etc.

+

Sky Query

+ +

+ Query has two different implementations, with slightly different features. The alternative one is + called "Sky Query", and is activated by passing the following two flags: + --universe_scope and --order_output=no. + --universe_scope=<target_pattern1>,...,<target_patternN> tells query to + preload the transitive closure of the target pattern specified by the target patterns, which can + be both additive and subtractive. All queries are then evaluated in this "scope". In particular, + the allrdeps and + rbuildfiles operators only return results from this scope. +

+ +

+ Sky Query has some advantages and disadvantages compared to the default query. The main + disadvantage is that it cannot order its output according to graph order, and thus certain + output formats are forbidden. Its advantages are that it provides + two operators (allrdeps and + rbuildfiles) that are not available in the default query. + As well, Sky Query does its work by introspecting the + Skyframe graph, rather than creating a new + graph, which is what the default implementation does. Thus, there are some circumstances in which + it is faster and uses less memory. +

+

Expressions: syntax and semantics of the grammar

@@ -479,6 +504,7 @@ x intersect (y union z) attr
buildfiles
+rbuildfiles
deps
filter
@@ -486,6 +512,7 @@ x intersect (y union z) labels
loadfiles
rdeps
+allrdeps
siblings
some
somepath
@@ -558,6 +585,18 @@ x intersect (y union z) depth parameter is omitted, the search is unbounded.

+

Transitive closure of all reverse dependencies: allrdeps

+
expr ::= allrdeps(expr)
+       | allrdeps(expr, depth)
+Only available with Sky Query
+

+ The allrdeps operator behaves just like the rdeps + operator, except that the "universe set" is whatever the --universe_scope flag + evaluated to, instead of being separately specified. Thus, if + --universe_scope=//foo/... was passed, then allrdeps(//bar) is + equivalent to rdeps(//bar, //foo/...). +

+

Dealing with a target's package: siblings

expr ::= siblings(expr)

@@ -953,10 +992,8 @@ genrule( The buildfiles(x) operator returns the set of files that define the packages of each target in set x; in other words, for each package, its BUILD file, - plus any files it references - - via load. Note that this also returns the BUILD files of the - packages containing these loaded files. + plus any files it references via load. Note that this also returns the BUILD files + of the packages containing these loaded files.

@@ -976,9 +1013,41 @@ genrule( the buildfiles operator and use only deps, but this yields an incorrect result: while the result contains the majority of needed packages, those packages that contain only files - that are load()'ed + that are load()'ed will be missing. +

- will be missing. +

Package definition files: rbuildfiles

+
expr ::= buildfiles(expr)
+Only available with Sky Query
+

+ The rbuildfiles(x) operator returns the set of "buildfiles" (BUILD and + .bzl files) that depend on x, where x is a list of path fragments for + buildfiles. For instance, if //foo is a package, then + rbuildfiles(foo/BUILD) will return the //foo:BUILD target. If the + foo/BUILD file has load('//bar:file.bzl'... in it, then + rbuildfiles(bar/file.bzl) will return the //foo:BUILD target and the + //bar:file.bzl target, as well as the targets for any other BUILD files and .bzl + files that load //bar:file.bzl +

+ +

+ The scope of the rbuildfiles operator is the universe specified by the + --universe_scope flag. Files that do not correspond directly to BUILD files and .bzl + files do not affect the results. For instance, source files (like foo.cc) are ignored, + even if they are explicitly mentioned in the BUILD file. Symlinks, however, are respected, so that + if foo/BUILD is a symlink to bar/BUILD, then + rbuildfiles(bar/BUILD) will include //foo:BUILD in its results. +

+ +

+ The rbuildfiles operator is morally the inverse of the + buildfiles operator. However, this moral inversion + holds more strongly in one direction: the outputs of rbuildfiles are just like the + inputs of buildfiles, since both are targets corresponding to packages and .bzl + files. In the other direction, the correspondence is weaker. The outputs of the + buildfiles operator are targets corresponding to all packages and .bzl files needed + by a given input. However, the inputs of the rbuildfiles operator are not those + targets, but rather the path fragments that correspond to those targets.

Package definition files: loadfiles

@@ -990,7 +1059,7 @@ genrule( .bzl files that are referenced from its BUILD files.

-

Output formats

+

Output formats

bazel query generates a graph. @@ -1000,6 +1069,12 @@ genrule( command-line option.

+

+ When running with Sky Query, only output formats that are compatible with + unordered output are allowed. Specifically, graph, minrank, and + maxrank output formats are forbidden. +

+

Some of the output formats accept additional options. The name of each output option is prefixed with the output format to which it -- cgit v1.2.3