Bazel 查询参考

报告问题 查看源代码

本页介绍了您在使用 bazel query 分析 build 依赖项时所使用的 Bazel 查询语言的参考手册。还介绍了 bazel query 支持的输出格式。

如需了解实际用例,请参阅 Bazel 查询使用方法

其他查询参考

除了在加载后阶段目标图上运行的 query 之外,Bazel 还包含操作图查询可配置的查询

操作图表查询

操作图查询 (aquery) 会在分析后配置的目标图上运行,并显示有关操作工件及其关系的信息。如果您对从已配置的目标图表生成的操作/工件的属性感兴趣,aquery 非常有用。例如,实际运行的命令及其输入、输出和助记符。

如需了解详情,请参阅查询参考文档

可配置查询

传统 Bazel 查询是在加载后阶段目标图上运行,因此不涉及配置及其相关概念。值得注意的是,这不会正确解析 select 语句,而是会返回选择的所有可能的分辨率。但是,可配置的查询环境 cquery 可正确处理配置,但不会提供此原始查询的所有功能。

如需了解详情,请参阅 cquery 参考文档

示例

用户如何使用 bazel query?以下是典型示例:

为什么 //foo 树依赖于 //bar/baz?显示路径:

somepath(foo/..., //bar/baz:all)

哪些 C++ 库的所有 foo 测试都依赖于 foo_bin 目标所不具备的功能?

kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))

词法单元:词法语法

查询语言的表达式由以下令牌组成:

  • 关键字,例如 let。关键字是语言的保留字,下面将逐一介绍。完整的关键字组合如下:

  • 字词,如“foo/...”“.*test rule”或“//bar/baz:all”。如果字符序列为“带引号”(以英文单引号 ' 开头和结尾,或以英文双引号 " 开头和结尾),它是一个字词。即使某个字符序列未加引号,它仍可能会被解析为字词。不带引号的字词是从字母字符 A-Za-z、数字 0-9、数字 0-9 和特殊字符 */@.-_:$~[](星号、正斜线、@、句点、连字符、下划线、冒号、美元符号、波浪号、左方括号、右方括号)中提取的一系列字符。但是,不带英文引号的字词不能以连字符 - 或星号 * 开头,即使相对目标名称可能以这些字符开头。

    不带英文引号的字词也不得包含字符加号 + 或等号 =,即使这些字符可以用在目标名称中也是如此。在编写用于生成查询表达式的代码时,应该用引号将目标名称引起来。

    编写根据用户提供的值构建 Bazel 查询表达式的脚本时,必须加引号。

     //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.
    

    请注意,除了 shell 可能要求的任何引用之外,也应使用此引号,例如:

    bazel query ' "//foo:bar=wiz" '   # single-quotes for shell, double-quotes for Bazel.
    

    关键字和运算符(用引号括起来)被视为普通字词。例如,some 是一个关键字,但“some”是一个词。foo 和“foo”都是单词。

    但是,在目标名称中使用单引号或双引号时要小心。引用一个或多个目标名称时,请仅使用一种类型的引号(全部单引号或全双引号)。

    以下是 Java 查询字符串的示例:

      'a"'a'         # WRONG: Error message: unclosed quotation.
      "a'"a"         # WRONG: Error message: unclosed quotation.
      '"a" + 'a''    # WRONG: Error message: unexpected token 'a' after query expression '"a" + '
      "'a' + "a""    # WRONG: Error message: unexpected token 'a' after query expression ''a' + '
      "a'a"          # OK.
      'a"a'          # OK.
      '"a" + "a"'    # OK
      "'a' + 'a'"    # OK
    

    我们之所以选择此语法,是为了让大多数情况下都不需要引号。(不常见的)".*test rule" 示例需要引号:它以英文句点开头并包含一个空格。引用 "cc_library" 没有必要,但不会造成任何危害。

  • 标点符号,例如圆括号 ()、句号 . 和逗号 ,。必须用引号括住包含标点符号的字词(上面列出的例外情况除外)。

系统会忽略引用的字词以外的空格字符。

Bazel 查询语言概念

Bazel 查询语言是一种表达式语言。每个表达式的求值结果为一组按部分排序的目标,或等效的目标图 (DAG)。这是唯一的数据类型。

集和图引用相同的数据类型,但强调不同方面,例如:

  • 设置:对部分目标的顺序无关紧要。
  • 图表:目标的部分顺序很重要。

依赖关系图中的循环

build 依赖关系图应该是无循环的。

查询语言使用的算法适用于无环图,但可以防范循环。我们未指定如何处理周期的详细信息,因此不应依赖这些详细信息。

隐式依赖项

除了在 BUILD 文件中显式定义的构建依赖项之外,Bazel 还会向规则添加其他隐式依赖项。例如,每条 Java 规则都隐式依赖于 JavaBuilder。隐式依赖项是使用以 $ 开头的属性建立的,无法在 BUILD 文件中替换它们。

默认情况下,bazel query 在计算查询结果时会将隐式依赖项考虑在内。可以使用 --[no]implicit_deps 选项更改此行为。请注意,由于查询不考虑配置,因此永远不会考虑潜在的工具链。

稳健性

Bazel 查询语言表达式针对构建依赖关系图运行,构建依赖关系图是由所有 BUILD 文件中的所有规则声明隐式定义的图。请务必注意,此图在某种程度上比较抽象,并不能构成有关如何执行构建的所有步骤的完整说明。若要执行 build,也必须提供配置;如需了解详情,请参阅用户指南的配置部分。

对于所有配置,采用 Bazel 查询语言评估表达式的结果为 true,这意味着它可能属于保守的过度估算,并不精确。如果您使用查询工具计算构建期间需要的所有源文件集,则该工具报告的内容可能会超出实际需要的数量,例如,即使您不打算在 build 中使用该功能,查询工具也会包含支持消息翻译所需的所有文件。

关于保留图表顺序的说明

运算会保留从其子表达式继承的所有排序约束。您可以将其视为“部分有序守恒定律”。举例说明:如果您发出查询以确定特定目标的依赖项的传递闭包,则生成的集合将根据依赖关系图进行排序。如果您过滤设置为仅包含 file 种类的目标,则生成的子集中的每对目标之间会保持相同的传递部分排序关系,即使这些目标对在原始图中实际上并未直接关联。(build 依赖关系图中没有文件-文件边缘)。

不过,虽然所有运算符都会保留顺序,但某些运算(如集合运算)本身并不会引入任何排序约束条件。请考虑以下表达式:

deps(x) union y

最终结果集的顺序一定会保留其子表达式的所有排序约束条件,也就是说,x 的所有传递依赖项都按彼此相关地正确排序。不过,查询不保证 y 中目标的顺序,也不保证 deps(x) 中目标相对于 y 中目标的顺序(y 中的目标恰好位于 deps(x) 中除外)。

引入排序约束的运算符包括:allpathsdepsrdepssomepath 以及目标模式通配符 package:*dir/... 等。

星空查询

星空查询是一种在指定的宇宙范围内运行的查询模式。

仅在 SkyQuery 中可用的特殊函数

Sky 查询模式具有其他查询函数 allrdepsrbuildfiles。这些函数涵盖整个宇宙(这就是它们不适用于普通查询的原因)。

指定 Universe 范围

通过传递以下两个标志(--universe_scope--infer_universe_scope)和 --order_output=no 来激活 Sky Query 模式。--universe_scope=<target_pattern1>,...,<target_patternN> 指示查询预加载由目标模式指定的目标模式的传递闭包,该模式可以是加法,也可以是减法。然后,系统会在此“范围”内评估所有查询。特别是,allrdepsrbuildfiles 运算符仅返回此范围的结果。--infer_universe_scope 告知 Bazel 根据查询表达式推断 --universe_scope 的值。此推断值是查询表达式中唯一目标模式的列表,但这可能不是您想要的值。例如:

bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)"

此查询表达式中唯一目标模式的列表为 ["//my:target"],因此 Bazel 将其视为与调用相同:

bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)"

但是,使用 --universe_scope 进行该查询的结果只有 //my:target;通过构造,宇宙中没有 //my:target 的反向依赖项!另一方面,请考虑:

bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))"

这是一个有意义的查询调用,它会尝试计算某些目录下的目标 tests 扩展中的测试目标,这些目录传递性依赖于其定义使用特定 .bzl 文件的目标。此处,--infer_universe_scope 是一种便利,尤其是在选择 --universe_scope 需要您自行解析查询表达式的情况下。

因此,对于使用 Universe 作用域运算符(如 allrdepsrbuildfiles)的查询表达式,请仅在其行为符合您的预期时才使用 --infer_universe_scope

与默认查询相比,Sky Query 有一些优缺点。主要缺点是,它无法按图顺序对输出进行排序,因此禁止使用某些输出格式。其优点是它提供了两个在默认查询中不可用的运算符(allrdepsrbuildfiles)。同样,Sky Query 的工作方式是自省 Skyframe 图,而不是像默认实现那样创建新图。因此,在某些情况下,它速度更快且使用的内存更少。

表达式:语法的语法和语义

以下是 Bazel 查询语言的语法,以 EBNF 表示法表示:

expr ::= word
       | let name = expr in expr
       | (expr)
       | expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr
       | set(word *)
       | word '(' int | word | expr ... ')'

以下部分按顺序介绍了该语法的各种形式。

目标模式

expr ::= word

从语法上讲,目标模式只是一个词。系统会将其解释为一组(无序)目标。最简单的目标模式是标签,用于标识单个目标(文件或规则)。例如,目标模式 //foo:bar 的求值结果为包含一个元素(目标,即 bar 规则)的集合。

目标模式会泛化标签以在软件包和目标中包含通配符。例如,foo/...:all(或仅 foo/...)是一个目标模式,其计算结果以递归方式在 foo 目录下包含每个软件包中的所有规则bar/baz:all 是一个目标模式,其计算结果是一个集包含 bar/baz 软件包中的所有规则,但不包含其子软件包。

同样,foo/...:* 是一个目标模式,其计算结果为一个集,其中包含每个软件包中的所有目标(规则和文件)(递归地位于 foo 目录下);bar/baz:* 求出的集包含 bar/baz 软件包中的所有目标,但不包含其子软件包。

由于 :* 通配符与文件及规则匹配,因此对于查询,它通常比 :all 更有用。相反,:all 通配符(隐含在 foo/... 等目标模式中)通常对 build 更有用。

bazel query 目标模式与 bazel build build 目标的工作方式相同。如需了解详情,请参阅目标模式,或输入 bazel help target-syntax

如果目标模式与目标模式不匹配,则目标模式可能求值为单例集(针对标签的情况下)、包含许多元素的集合(例如,对具有数千个元素的 foo/... 而言)或空集(如果目标模式与任何目标均不匹配)。

根据依赖关系,目标模式表达式的结果中的所有节点均相对于彼此正确排序。因此,foo:* 的结果不仅是软件包 foo 中的目标集,也是这些目标的。(无法保证结果节点相对于其他节点的相对顺序。)如需了解详情,请参阅图顺序部分。

变量

expr ::= let name = expr1 in expr2
       | $name

Bazel 查询语言允许对变量进行定义和引用。let 表达式的计算结果与 expr2 的结果相同,其中变量 name 的所有自由出现次数都替换为 expr1 的值。

例如,let v = foo/... in allpaths($v, //common) intersect $v 等同于 allpaths(foo/...,//common) intersect foo/...

如果 name 变量引用出现在封装 let name = ... 表达式中,则属于错误。换句话说,顶级查询表达式不能包含自由变量。

在上述语法形式中,name 与“word”类似,但增加了额外的限制,即它是 C 编程语言中的合法标识符。对变量的引用必须以“$”字符开头。

每个 let 表达式仅定义一个变量,但您可以嵌套它们。

目标模式和变量引用都仅由单个词元(即单词)组成,从而导致语法歧义。但是,这不存在语义歧义,因为作为合法变量名称的单词子集与合法目标模式单词的子集不相交。

从技术上讲,let 表达式不会提高查询语言的表达性:任何可用该语言表达的查询也可以在没有它们的情况下表达。但是,它们可以提高许多查询的简洁性,并且还可能会提高查询评估效率。

带英文括号的表达式

expr ::= (expr)

圆括号用于关联子表达式,以强制实施计算顺序。带括号的表达式求值为其实参的值。

代数集运算:交集、并集、集差

expr ::= expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr

这三个运算符对其参数计算常规集合运算。每个运算符都有两种形式:一种名词形式(例如 intersect)和一种符号形式(例如 ^)。这两种形式等效;符号形式输入速度更快。(为清楚起见,本页其余部分使用的是名词形式。)

例如,

foo/... except foo/bar/...

求值为匹配 foo/... 但不匹配 foo/bar/... 的一组目标。

您可按以下方式编写相同的查询:

foo/... - foo/bar/...

intersect (^) 和 union (+) 运算具有交换性(对称);except (-) 则不对称。解析器会将所有三个运算符视为左结合运算符,并给予同等优先级,因此您可能需要括号。例如,前两个表达式是等效的,但第三个不是:

x intersect y union z
(x intersect y) union z
x intersect (y union z)

从外部来源读取目标:set

expr ::= set(word *)

set(a b c ...) 运算符计算零个或多个目标模式的并集,这些模式之间用空格分隔(无英文逗号)。

通过结合使用 Bourne shell 的 $(...) 功能,set() 提供了一种方法,可将一个查询结果保存在常规文本文件中,使用其他程序(例如标准 UNIX shell 工具)操控该文本文件,然后将结果重新引入查询工具中,作为进一步处理的值。例如:

bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
bazel query "kind(cc_binary, set($(<foo)))"

在下一个示例中,kind(cc_library, deps(//some_dir/foo:main, 5)) 是使用 awk 程序对 maxrank 值进行过滤来计算的。

bazel query 'deps(//some_dir/foo:main)' --output maxrank | awk '($1 < 5) { print $2;} ' > foo
bazel query "kind(cc_library, set($(<foo)))"

在这些示例中,$(<foo)$(cat foo) 的简写形式,但您也可以使用除 cat 以外的 shell 命令,例如前面的 awk 命令。

函数

expr ::= word '(' int | word | expr ... ')'

查询语言定义了多个函数。函数的名称决定了它所需的参数数量和类型。提供的函数如下:

依赖项的传递关闭:deps

expr ::= deps(expr)
       | deps(expr, depth)

deps(x) 运算符计算其参数集 x 的依赖项的传递闭包形成的图。例如,deps(//foo) 的值是根位于单个节点 foo 的依赖关系图,包括其所有依赖关系。deps(foo/...) 的值是依赖关系图,其根目录是 foo 目录下每个软件包中的所有规则。在这种情况下,“依赖项”仅表示规则目标和文件目标,因此此处未包含创建这些目标所需的 BUILD 和 Starlark 文件。为此,您应使用 buildfiles 运算符。

生成的图根据依赖关系进行排序。如需了解详情,请参阅有关图顺序的部分。

deps 运算符接受可选的第二个参数,该参数是一个整数字面量,用于指定搜索深度的上限。因此,deps(foo:*, 0) 会返回 foo 软件包中的所有目标,而 deps(foo:*, 1) 进一步包含 foo 软件包中任何目标的直接前提条件,而 deps(foo:*, 2) 进一步包含可从 deps(foo:*, 1) 中的节点直接访问的节点,依此类推。(这些数字对应于 minrank 输出格式中显示的排名。)如果省略 depth 参数,搜索将没有界限:它会计算前提条件的自反传递闭包。

反向依赖项的传递闭合:rdeps

expr ::= rdeps(expr, expr)
       | rdeps(expr, expr, depth)

rdeps(u, x) 运算符求值为宇宙集 u 的传递闭包中的参数集 x 的反向依赖关系。

生成的图根据依赖关系进行排序。如需了解详情,请参阅有关图顺序的部分。

rdeps 运算符接受可选的第三个参数,该参数是一个整数字面量,用于指定搜索深度的上限。生成的图仅包含与参数集中的任何节点相距指定深度的节点。因此,rdeps(//foo, //common, 1) 的计算结果是 //foo 的传递闭包中直接依赖于 //common 的所有节点。(这些数字与 minrank 输出格式中显示的排名相对应。)如果省略 depth 参数,搜索将是无限的。

所有反向依赖项的传递闭包:allrdeps

expr ::= allrdeps(expr)
       | allrdeps(expr, depth)

allrdeps 运算符的行为类似于 rdeps 运算符,只不过“宇宙集合”是 --universe_scope 标志的求值结果,而不是单独指定。因此,如果传递了 --universe_scope=//foo/...,则 allrdeps(//bar) 等同于 rdeps(//foo/..., //bar)

在同一软件包中直接反向依赖项:same_pkg_direct_rdeps

expr ::= same_pkg_direct_rdeps(expr)

same_pkg_direct_rdeps(x) 运算符会计算与参数集中的目标位于同一软件包中的全部目标,这些目标直接依赖于这些参数。

处理目标的软件包:同级

expr ::= siblings(expr)

siblings(x) 运算符计算与参数集中的目标位于同一软件包中的全部目标集。

任意选择:部分

expr ::= some(expr)
       | some(expr, count )

some(x, k) 运算符从其参数集 x 任意选择最多 k 目标,并计算结果为仅包含这些目标的集。k 参数是可选的;如果缺少该参数,结果将是一个单例集,其中只包含一个任意选择的目标。如果参数集 x 的大小小于 k,则返回整个参数集 x

例如,表达式 some(//foo:main union //bar:baz) 的求值结果为包含 //foo:main//bar:baz(尽管未定义二者)的单例集。表达式 some(//foo:main union //bar:baz, 2)some(//foo:main union //bar:baz, 3) 同时返回 //foo:main//bar:baz

如果参数是单例,则 some 会计算标识函数:some(//foo:main) 等同于 //foo:main

如果指定的参数集为空,则会出错,如表达式 some(//foo:main intersect //bar:baz) 所示。

路径运算符:somepath、allpaths

expr ::= somepath(expr, expr)
       | allpaths(expr, expr)

somepath(S, E)allpaths(S, E) 运算符用于计算两组目标之间的路径。这两个查询都接受两个参数:一组起点 S 和一组终点 Esomepath 返回从 S 中的目标到 E 中目标的某个任意路径上的节点图;allpaths 返回从 S 中的任意目标到 E 中的任意目标的所有路径上的节点图。

所得图根据依赖关系进行排序。如需了解详情,请参阅有关图表顺序的部分。

某个路径
somepath(S1 + S2, E),一种可能的结果。
某个路径
somepath(S1 + S2, E),另一种可能的结果。
所有路径
allpaths(S1 + S2, E)

目标种类过滤: kind

expr ::= kind(word, expr)

kind(pattern, input) 运算符对一组目标应用过滤条件,并舍弃那些不属于预期种类的目标。pattern 参数指定要匹配的目标类型。

例如,下表显示了由 BUILD 文件(适用于软件包 p)定义的四个目标的种类:

编码 目标 种类
        genrule(
            name = "a",
            srcs = ["a.in"],
            outs = ["a.out"],
            cmd = "...",
        )
      
//p:a 一般规则
//p:a.in 源文件
//p:a.out 生成的文件
//p:BUILD 源文件

因此,kind("cc_.* rule", foo/...) 求值为 foo 下的所有 cc_librarycc_binary 等规则目标的集合,而 kind("source file", deps(//foo)) 求值为 //foo 目标依赖项的传递闭包中的所有源文件的集合。

通常需要将 pattern 参数括起来,因为如果没有该参数,解析器就不会将许多正则表达式(例如 source file.*_test)视为字词。

package group 匹配时,以 :all 结尾的目标可能不会产生任何结果。请改用 :all-targets

目标名称过滤:过滤器

expr ::= filter(word, expr)

filter(pattern, input) 运算符对一组目标应用过滤条件,并舍弃标签(绝对形式)与模式不匹配的目标;其计算结果为输入的子集。

第一个参数 pattern 是在目标名称上包含正则表达式的字词。filter 表达式的计算结果是包含所有目标 x 的集,以便 xinput 集的成员,并且 x 的标签(绝对形式,例如 //foo:bar)包含正则表达式 pattern 的(未锚定)匹配项。由于所有目标名称都以 // 开头,因此它可以用作 ^ 正则表达式锚点的替代项。

此运算符通常提供更快、更可靠的替代 intersect 运算符。例如,如需查看 //foo:foo 目标的所有 bar 依赖项,可以评估

deps(//foo) intersect //bar/...

但是,此语句将需要解析 bar 树中的所有 BUILD 文件,这样做速度很慢,并且容易在不相关的 BUILD 文件中出错。替代方案是:

filter(//bar, deps(//foo))

该查询将首先计算一组 //foo 依赖项,然后仅过滤与提供的模式匹配的目标(换句话说,名称中包含 //bar 作为子字符串的目标)。

filter(pattern, expr) 运算符的另一个常见用途是按名称或扩展名过滤特定文件。例如,

filter("\.cc$", deps(//foo))

将提供一个列表,其中包含用于构建 //foo 的所有 .cc 文件。

规则属性过滤:attr

expr ::= attr(word, word, expr)

attr(name, pattern, input) 运算符对一组目标应用过滤条件,并舍弃不是规则的目标、未定义属性 name 的规则目标,或属性值与提供的正则表达式 pattern 不匹配的规则目标;其计算结果是输入内容的子集。

第一个参数 name 是应与提供的正则表达式模式匹配的规则属性的名称。第二个参数 pattern 是针对属性值的正则表达式。attr 表达式的计算结果是包含所有目标 x 的集合,因此 xinput 集的成员,是具有已定义属性 name 的规则,并且属性值包含正则表达式 pattern 的(未锚定)匹配项。如果 name 是可选属性,且规则未明确指定,系统将使用默认属性值进行比较。例如,

attr(linkshared, 0, deps(//foo))

将选择允许具有链接共享属性(例如,cc_binary 规则)的所有 //foo 依赖项,并将其明确设置为 0 或根本不设置,但默认值为 0(例如,对于 cc_binary 规则)。

列表类型属性(例如 srcsdata 等)会转换为 [value<sub>1</sub>, ..., value<sub>n</sub>] 形式的字符串,开头为 [ 括号,以 ] 括号结尾,并使用“,”(英文逗号、空格)来分隔多个值。使用标签的绝对形式将标签转换为字符串。例如,属性 deps=[":foo", "//otherpkg:bar", "wiz"] 将转换为字符串 [//thispkg:foo, //otherpkg:bar, //thispkg:wiz]。 方括号始终存在,因此空列表将使用字符串值 [] 进行匹配。例如,

attr("srcs", "\[\]", deps(//foo))

将在 srcs 属性为空的 //foo 依赖项中选择所有规则,而

attr("data", ".{3,}", deps(//foo))

将选择 //foo 依赖项之间的所有规则,这些依赖项在 data 属性中至少指定一个值(由于 //:,每个标签的长度至少为 3 个字符)。

如需选择 //foo 依赖项与列表类型属性中特定 value 的所有规则,请使用

attr("tags", "[\[ ]value[,\]]", deps(//foo))

之所以行之有效,是因为 value 之前的字符是 [ 或空格,而 value 之后的字符是逗号或 ]

规则可见性过滤:可见

expr ::= visible(expr, expr)

visible(predicate, input) 运算符对一组目标应用过滤条件,并舍弃不具备所需公开范围的目标。

第一个参数 predicate 是输出结果中的所有目标必须可见的一组目标。visible 表达式的计算结果为包含所有目标 x 的集,使 x 成为 input 集的成员,并且对于 predicate 中的所有目标,xy 可见。y例如:

visible(//foo, //bar:*)

会选择软件包 //bar//foo 可以依赖的所有目标,而不会违反可见性限制。

对“标签”类型的规则属性求值

expr ::= labels(word, expr)

labels(attr_name, inputs) 运算符会返回 inputs 集内某条规则中类型为“标签”或“标签列表”的 attr_name 属性中指定的一组目标。

例如,labels(srcs, //foo) 会返回 //foo 规则的 srcs 属性中显示的一组目标。如果 inputs 集中有多个规则具有 srcs 属性,则返回其 srcs 的并集。

扩展和过滤 test_suites: testing

expr ::= tests(expr)

tests(x) 运算符会返回 x 集中所有测试规则的集合,将任何 test_suite 规则扩展到它们引用的各个测试集中,并按 tagsize 应用过滤。

默认情况下,查询评估会忽略所有 test_suite 规则中的所有非测试目标。可以使用 --strict_test_suite 选项将其更改为错误。

例如,查询 kind(test, foo:*) 会列出 foo 软件包中的所有 *_testtest_suite 规则。根据定义,所有结果都是 foo 软件包的成员。相比之下,查询 tests(foo:*) 将返回由 bazel test foo:* 执行的所有单个测试:这可能包括属于其他软件包的测试,这些测试通过 test_suite 规则直接或间接引用。

软件包定义文件:buildfiles

expr ::= buildfiles(expr)

buildfiles(x) 运算符返回一组文件,这些文件定义了集 x 中每个目标的软件包;换句话说,对于每个软件包,其 BUILD 文件以及它通过 load 引用的任何 .bzl 文件。请注意,此操作还会返回包含这些 load 文件的软件包的 BUILD 文件。

此运算符通常用于确定构建指定目标所需的文件或软件包,通常与下面的 --output package 选项结合使用。例如,

bazel query 'buildfiles(deps(//foo))' --output package

返回 //foo 以传递方式依赖的所有软件包的集合。

软件包定义文件:rbuildfile

expr ::= rbuildfiles(word, ...)

rbuildfiles 运算符接受以英文逗号分隔的路径片段列表,并返回以传递方式依赖于这些路径片段的一组 BUILD 文件。例如,如果 //foo 是一个软件包,那么 rbuildfiles(foo/BUILD) 将返回 //foo:BUILD 目标。如果 foo/BUILD 文件中包含 load('//bar:file.bzl'...,则 rbuildfiles(bar/file.bzl) 将返回 //foo:BUILD 目标,以及加载 //bar:file.bzl 的任何其他 BUILD 文件的目标。

rbuildfiles 运算符的范围是 --universe_scope 标志指定的宇宙。不直接对应于 BUILD 文件和 .bzl 文件的文件不会影响结果。例如,系统会忽略源文件(如 foo.cc),即使 BUILD 文件中明确提及这些文件也是如此。不过,系统会考虑符号链接,因此,如果 foo/BUILD 是指向 bar/BUILD 的符号链接,那么 rbuildfiles(bar/BUILD) 将在其结果中包含 //foo:BUILD

rbuildfiles 运算符在道德上几乎与 buildfiles 运算符相反。不过,这种道德反转更适合某个方向:rbuildfiles 的输出类似于 buildfiles 的输入;前者的输出将仅包含软件包中的 BUILD 文件目标,而后者可能包含此类目标。而在另一个方向,这种对应关系则较弱。buildfiles 运算符的输出是与所有软件包和 .bzl 文件。不过,rbuildfiles 运算符的输入不是这些目标,而是与这些目标对应的路径片段。

软件包定义文件:loadfiles

expr ::= loadfiles(expr)

loadfiles(x) 运算符返回加载 x 集中每个目标的软件包所需的 Starlark 文件集。换言之,对于每个软件包,它都会返回从其 BUILD 文件中引用的 .bzl 文件。

输出格式

bazel query 生成图表。您可以通过 --output 命令行选项指定 bazel query 呈现此图表的内容、格式和顺序。

运行 Sky Query 时,系统仅允许使用与无序输出兼容的输出格式。具体而言,禁止使用 graphminrankmaxrank 输出格式。

某些输出格式接受其他选项。每个输出选项的名称都以它所应用的输出格式作为前缀,因此 --graph:factored 仅在使用 --output=graph 时适用;如果使用 graph 以外的输出格式,则无效。同样,--xml:line_numbers 仅在使用 --output=xml 时才适用。

关于结果排序

虽然查询表达式始终遵循“图顺序守恒定律”,但可以按依赖关系顺序或无序的方式呈现结果。这不会影响结果集中的目标或查询的计算方式。而只会影响输出到 stdout 的方式。此外,依赖关系顺序相等的节点不一定按字母顺序排序。--order_output 标志可用于控制此行为。(--[no]order_results 标志包含 --order_output 标志的一部分功能,现已弃用。)

此标志的默认值为 auto,会按字典顺序输出结果。不过,使用 somepath(a,b) 时,结果将改为按 deps 顺序输出。

当此标志为 no 并且 --outputbuildlabellabel_kindlocationpackageprotoxml 之一时,输出将按任意顺序输出。这通常是最快的选项。不过,当 --outputgraphminrankmaxrank 其中之一时,Bazel 会始终输出按依赖项顺序或排名排序的结果。

当此标志为 deps 时,Bazel 会按某种拓扑顺序输出结果,即依赖项在前,依赖项在后。不过,可以按任何顺序输出按依赖关系顺序无序的节点(因为不存在从任何一个到另一个之间的路径)。

当此标志为 full 时,Bazel 会按完全确定(总计)顺序输出节点。首先,所有节点均按字母顺序排序。然后,列表中的每个节点都用作后级深度优先搜索的起始点,其中未访问节点的传出边缘按后续节点的字母顺序遍历。最后,输出节点的顺序与访问顺序相反。

按此顺序输出节点的速度可能会较慢,因此只应在确定性非常重要时使用它。

输出目标的源形式,因为它们将在 build 中显示

--output build

使用此选项时,每个目标的表示形式就像用 BUILD 语言手写一样。所有变量和函数调用(例如 glob、宏)都会展开,这有助于查看 Starlark 宏的效果。此外,每条有效规则都会报告一个 generator_name 和/或 generator_function) 值,并给出宏的名称,该宏被评估以生成有效规则。

虽然输出使用的语法与 BUILD 文件相同,但不能保证生成有效的 BUILD 文件。

--output label

使用此选项时,系统会按拓扑顺序输出结果图中每个目标的名称(或标签)集,每行一个标签(除非指定了 --noorder_results,请参阅关于结果排序的备注)。(拓扑排序是指图节点先于其所有后代出现的情况。)当然,图有许多可能的拓扑排序(反向后序只是其中一种);具体选择哪种排序并未指定。

输出 somepath 查询的输出时,节点的输出顺序是路径的顺序。

注意:在某些极端情况下,可能会有两个不同的目标具有相同的标签;例如,sh_binary 规则及其唯一的(隐式)srcs 文件可能都称为 foo.sh。如果查询结果同时包含这两个目标,则输出(label 格式)将显示为包含重复项。使用 label_kind(见下文)格式时,区别会很明显:两个目标具有相同的名称,但一个种类为 sh_binary rule,另一个目标种类为 source file

--output label_kind

label 一样,此输出格式会按拓扑顺序输出每个目标的标签,但它还会在标签前面加上目标的种类

--output proto

将查询输出作为 QueryResult 协议缓冲区输出。

--output streamed_proto

输出 Target 协议缓冲区的以长度分隔的流。这对于 (i) 解决协议缓冲区的大小限制非常有用:当目标太多而无法容纳在一个 QueryResult 中时,(ii) 无法开始处理,而 Bazel 仍在输出。

--output textproto

--output proto 类似,该方法会以文本格式输出 QueryResult 协议缓冲区。

--output streamed_jsonproto

--output streamed_proto 类似,会以 ndjson 格式输出 Target 协议缓冲区的流。

--output minrank --output maxrank

label 一样,minrankmaxrank 输出格式会在结果图中输出每个目标的标签,但它们不是按拓扑顺序显示,而是按排名顺序显示,其前加上其秩号。这些值不受结果排序 --[no]order_results 标志的影响(请参阅关于结果排序的注意事项)。

此格式有两种变体:minrank 按照从根节点到节点的最短路径长度对每个节点进行排名。“根”节点(没有传入边缘的节点)的等级为 0,其后代的等级为 1,以此类推(与往常一样,边缘从目标指向其前提,即它所依赖的目标。)

maxrank 按从根节点到该节点的最长路径长度对每个节点进行排序。同样,“根”的排名为 0,所有其他节点的排名均比其所有前身的最高排名大 1。

一个循环中的所有节点都被视为相等排名。(大多数图都是无环的,但因为 BUILD 文件包含错误的循环,确实会出现循环。)

这些输出格式有助于发现图的深度。如果用于 deps(x)rdeps(x)allpaths 查询的结果,则排名数字等于从 x 到该排名中某个节点的最短路径(采用 minrank)或最长路径(采用 maxrank)。maxrank 可用于确定构建目标所需的最长构建步骤序列。

例如,当分别指定了 --output minrank--output maxrank 时,左侧的图表会生成右侧输出。

排名胜出
      minrank

      0 //c:c
      1 //b:b
      1 //a:a
      2 //b:b.cc
      2 //a:a.cc
      
      maxrank

      0 //c:c
      1 //b:b
      2 //a:a
      2 //b:b.cc
      3 //a:a.cc
      
--output location

label_kind 类似,此选项会针对结果中的每个目标输出目标的种类和标签,但它的前缀是用一个字符串作为前缀,用于描述该目标的位置(采用文件名和行号)。其格式类似于 grep 的输出。因此,可以解析后者的工具(例如 Emacs 或 vi)也可以使用查询输出逐步检查一系列匹配,从而使 Bazel 查询工具可以用作依赖项图感知型“grep,用于 BUILD 文件”。

位置信息因目标种类而异(请参阅 Kind 运算符)。对于规则,系统会输出规则的声明在 BUILD 文件中的位置。对于源文件,系统会输出实际文件的第 1 行位置。对于生成的文件,输出生成该文件的规则的位置。(查询工具没有足够的信息来查找所生成文件的实际位置,在任何情况下,如果尚未执行构建,都可能不存在该文件的位置。)

--output package

此选项会输出结果集中的某个目标所属的所有软件包的名称。这些名称会按字典顺序输出,并排除重复项。正式地说,这是从标签集(软件包、目标)到软件包的投影。

外部代码库中的软件包的格式为 @repo//foo/bar,而主代码库中的软件包的格式为 foo/bar

deps(...) 查询结合使用时,此输出选项可用于查找必须签出的一组软件包,以便构建一组指定的目标。

显示结果图表

--output graph

此选项会使查询结果以常用的 AT&T GraphViz 格式输出为有向图。通常,结果会保存到一个文件中,例如 .png.svg。(如果您的工作站上未安装 dot 程序,则可以使用命令 sudo apt-get install graphviz 进行安装。)如需查看示例调用,请参阅下面的示例部分。

此输出格式对 allpathsdepsrdeps 查询特别有用,因为在此类查询中,结果包含一组路径,以线性形式(例如使用 --output label)呈现时无法轻松直观呈现这些路径。

默认情况下,图表以分解形式呈现。也就是说,拓扑等效的节点会合并为具有多个标签的单个节点。这会使图表更紧凑、更易于阅读,因为典型的结果图包含高度重复的模式。例如,java_library 规则可能依赖于数百个由同一 genrule 生成的 Java 源文件;在因式图中,所有这些文件均由单个节点表示。可以使用 --nograph:factored 选项停用此行为。

--graph:node_limit n

此选项指定输出中图节点的标签字符串的最大长度。较长的标签将被截断;-1 表示禁止截断。鉴于通常输出图表的因式分解形式,节点标签可能会很长。GraphViz 无法处理超过 1024 个字符(此选项为此选项的默认值)的标签。除非使用了 --output=graph,否则此选项无效。

--[no]graph:factored

默认情况下,图表以分解形式显示,如上文所述。指定 --nograph:factored 时,系统在输出图表时不考虑因数因素。这使得使用 GraphViz 进行可视化变得不切实际,但更简单的格式可以简化其他工具(例如 grep)的处理。除非使用了 --output=graph,否则此选项无效。

XML

--output xml

此选项会使生成的目标以 XML 格式输出。输出以如下 XML 标头开头

  <?xml version="1.0" encoding="UTF-8"?>
  <query version="2">

接着按拓扑顺序处理结果图中每个目标的 XML 元素(除非请求的是无序结果),最后以终止

</query>

对于 file 种类的目标,系统会发出简单的条目:

  <source-file name='//foo:foo_main.cc' .../>
  <generated-file name='//foo:libfoo.so' .../>

但对于规则,XML 是结构化的,并且包含规则的所有属性的定义,包括规则的 BUILD 文件中未明确指定值的属性。

此外,结果包含 rule-inputrule-output 元素,这样无需知道这一点即可重建依赖关系图的拓扑,而无需知道例如,srcs 属性的元素是前向依赖项(先决条件),而 outs 属性的内容是向后依赖项(使用方)。

如果指定了 --noimplicit_deps,系统会抑制隐式依赖项rule-input 元素。

  <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>

目标的每个 XML 元素都包含一个 name 属性(其值为目标的标签)和一个 location 属性(其值为 --output location 输出的目标位置)。

--[no]xml:line_numbers

默认情况下,XML 输出中显示的位置包含行号。指定 --noxml:line_numbers 时,系统不会输出行号。

--[no]xml:default_values

默认情况下,XML 输出不包含其值是此类属性的默认值的规则属性(例如,如果未在 BUILD 文件中指定该属性,或已明确提供默认值)。此选项会使此类属性值包含在 XML 输出中。

正则表达式

查询语言中的正则表达式使用 Java 正则表达式库,因此您可以使用 java.util.regex.Pattern 的完整语法。

使用外部代码库进行查询

如果构建依赖于外部代码库中的规则,则查询结果将包含这些依赖项。例如,如果 //foo:bar 依赖于 @other-repo//baz:libbazel query 'deps(//foo:bar)' 会将 @other-repo//baz:lib 列为依赖项。