可配置的查询 (cquery)

报告问题open_in_new 查看源代码open_in_new

cquery 是 query 的变体，可正确处理 select() 和构建选项对 build 图的影响。

为此，它会处理 Bazel 分析阶段结果，该阶段集成了这些效果。相比之下，query 会先计算 Bazel 加载阶段的结果，然后再评估选项。

例如：

$ cat > tree/BUILD <<EOF
sh_library(
    name = "ash",
    deps = select({
        ":excelsior": [":manna-ash"],
        ":americana": [":white-ash"],
        "//conditions:default": [":common-ash"],
    }),
)
sh_library(name = "manna-ash")
sh_library(name = "white-ash")
sh_library(name = "common-ash")
config_setting(
    name = "excelsior",
    values = {"define": "species=excelsior"},
)
config_setting(
    name = "americana",
    values = {"define": "species=americana"},
)
EOF

# Traditional query: query doesn't know which select() branch you will choose,
# so it conservatively lists all of possible choices, including all used config_settings.
$ bazel query "deps(//tree:ash)" --noimplicit_deps
//tree:americana
//tree:ash
//tree:common-ash
//tree:excelsior
//tree:manna-ash
//tree:white-ash

# cquery: cquery lets you set build options at the command line and chooses
# the exact dependencies that implies (and also the config_setting targets).
$ bazel cquery "deps(//tree:ash)" --define species=excelsior --noimplicit_deps
//tree:ash (9f87702)
//tree:manna-ash (9f87702)
//tree:americana (9f87702)
//tree:excelsior (9f87702)

每个结果都包含构建目标所用的配置的唯一标识符 (9f87702)。

由于 cquery 在配置的目标图上运行，因此它不能了解构建操作等工件，也无法访问 test_suite 规则，因为它们不是已配置的目标。对于前者，请参阅 aquery。

基本语法

一个简单的 cquery 调用如下所示：

bazel cquery "function(//target)"

查询表达式 "function(//target)" 包含以下内容：

• function(...) 是针对目标运行的函数。cquery 支持 query 的大多数函数，还支持几个新函数。
• //target 是馈送到函数的表达式。在此示例中，表达式是一个简单的目标。但是，查询语言还允许嵌套函数。 如需查看相关示例，请参阅查询指南。

cquery 需要目标通过加载和分析阶段来运行。除非另有指定，否则 cquery 会解析查询表达式中列出的目标。如需了解如何查询顶层 build 目标的依赖项，请参阅 --universe_scope。

配置

以下代码行：

//tree:ash (9f87702)

表示 //tree:ash 是在 ID 为 9f87702 的配置中构建的。对于大多数目标，这都是定义配置的 build 选项值的不透明哈希值。

要查看配置的完整内容，请运行以下命令：

$ bazel config 9f87702

9f87702 是完整 ID 的前缀。这是因为完整的 ID 是 SHA-256 哈希，这个哈希过长，难以遵循。cquery 可识别完整 ID 的任何有效前缀，类似于 Git 短哈希值。如需查看完整 ID，请运行 $ bazel config。

目标模式评估

//foo 对 cquery 的含义与对 query 不同。这是因为 cquery 会评估已配置的目标，并且构建图可能有多个配置的 //foo 版本。

对于 cquery，查询表达式中的目标模式会针对具有该模式匹配的每个标签求值。输出是确定性的，但除了核心查询排序协定之外，cquery 不保证其他排序。

与使用 query 相比，这样会使查询表达式产生更精细的结果。例如，以下命令可以产生多条结果：

# Analyzes //foo in the target configuration, but also analyzes
# //genrule_with_foo_as_tool which depends on an exec-configured
# //foo. So there are two configured target instances of //foo in
# the build graph.
$ bazel cquery //foo --universe_scope=//foo,//genrule_with_foo_as_tool
//foo (9f87702)
//foo (exec)

如果您要精确声明要查询的实例，请使用 config 函数。

如需详细了解目标模式，请参阅 query 的目标模式文档。

函数

在 query 支持的一组函数中，cquery 支持除 visible、siblings、buildfiles 和 tests 之外的所有函数。

cquery 还引入了以下新函数：

config

expr ::= config(expr, word)

config 运算符会尝试查找第一个参数指定的标签已配置的目标，以及第二个参数指定的配置目标。

第二个参数的有效值是 null 或自定义配置哈希。哈希可以从 $ bazel config 或之前的 cquery 输出检索。

示例：

$ bazel cquery "config(//bar, 3732cc8)" --universe_scope=//foo

$ bazel cquery "deps(//foo)"
//bar (exec)
//baz (exec)

$ bazel cquery "config(//baz, 3732cc8)"

如果无法在指定配置中找到第一个参数的所有结果，则只会返回能够找到的参数。如果在指定配置中未找到任何结果，则查询会失败。

选项

build 选项

cquery 在常规 Bazel 构建上运行，因此继承在构建期间可用的一组选项。

使用 cquery 选项

--universe_scope（逗号分隔列表）

配置的目标依赖项通常会经过转换，这会导致其配置与被依赖对象的配置不同。通过此标志，您可以查询目标，就像将其构建为另一个目标的依赖项或传递依赖项。例如：

# x/BUILD
genrule(
     name = "my_gen",
     srcs = ["x.in"],
     outs = ["x.cc"],
     cmd = "$(locations :tool) $< >$@",
     tools = [":tool"],
)
cc_binary(
    name = "tool",
    srcs = ["tool.cpp"],
)

Genrule 在执行配置中配置其工具，以便以下查询会生成以下输出：

查询	已构建目标	输出
bazel cquery“//x:tool”	//x:tool	//x:tool(targetconfig)
bazel cquery "//x:tool" --universe_scope{8/}x:my_gen"	//x:my_gen	//x:tool(execconfig)

设置此标志后，系统会构建其内容。如果未设置此属性，系统会构建查询表达式中提到的所有目标。已构建目标的传递性闭包用作查询的宇宙。无论采用上述哪种方式，构建的目标都必须可在顶层进行构建（即与顶级选项兼容）。cquery 会返回这些顶级目标的传递性关闭结果。

即使可以在顶层查询表达式中构建所有目标，这样做可能有用。例如，明确设置 --universe_scope 可能会在您不关注的配置中多次构建目标。还有助于指定您要查找的目标的配置版本（因为目前无法以任何其他方式完全指定此目标）。如果您的查询表达式比 deps(//foo) 更复杂，则应设置此标志。

--implicit_deps（布尔值，default=True）

将此标志设置为 false 可过滤掉未在 BUILD 文件中明确设置的所有结果，而是由 Bazel 其他位置设置的结果。这包括过滤解析的工具链。

--tool_deps（布尔值，default=True）

将此标志设置为 false 可过滤掉所有已查询目标，对于这些目标，来自查询的目标的路径将在目标配置和非目标配置之间转换。如果查询的目标位于目标配置中，设置 --notool_deps 将仅返回也存在于目标配置中的目标。如果查询的目标属于非目标配置，则设置 --notool_deps 也只会返回非目标配置中的目标。此设置通常不会影响过滤已解析的工具链。

--include_aspects（布尔值，default=True）

添加由 aspects 添加的依赖项。

如果停用此标记，当 X 只通过某个宽高比依赖于 Y 时，cquery somepath(X, Y) 和 cquery deps(X) | grep 'Y' 会省略 Y。

输出格式

默认情况下，cquery 输出会生成按依赖项排序的标签和配置对列表。我们还提供了其他公开结果的选项。

转场效果

--transitions=lite
--transitions=full

配置转换用于在顶级目标（位于不同于顶级目标的配置中）下构建目标。

例如，目标可能会在其 tools 属性中对所有依赖项执行执行配置过渡。这称为“属性转换”。规则还可以对自己的配置强制进行转换，这称为规则类转换。此输出格式会输出有关这些转换的信息，例如类型及其对 build 选项的影响。

此输出格式由 --transitions 标志触发，该标志默认设置为 NONE。它可以设置为 FULL 或 LITE 模式。FULL 模式会输出规则类转换和属性转换的相关信息，包括转换前后选项的详细差异。LITE 模式会输出相同的信息，但不会显示选项差异。

协议消息输出

--output=proto

此选项会导致生成的目标以二进制协议缓冲区形式输出。如需了解协议缓冲区的定义，请访问 src/main/protobuf/analysis_v2.proto。

CqueryResult 是包含 cquery 结果的顶级消息。它具有 ConfiguredTarget 消息列表和 Configuration 消息列表。每个 ConfiguredTarget 都有一个 configuration_id，其值等于相应 Configuration 消息中 id 字段的值。

--[no]proto:include_configurations

默认情况下，cquery 结果作为每个已配置的目标的一部分返回配置信息。如果您想省略这些信息并获取采用与查询的 proto 输出格式完全相同的 proto 输出，请将此标志设置为 false。

如需了解更多与 proto 输出相关的选项，请参阅查询的 proto 输出文档。

图表输出

--output=graph

此选项会生成与 Graphviz 兼容的 .dot 文件输出。如需了解详情，请参阅 query 的图表输出文档。cquery 还支持 --graph:node_limit 和 --graph:factored。

文件输出

--output=files

此选项会输出由查询匹配的每个目标生成的输出文件的列表，类似于在 bazel build 调用结束时输出的列表。输出仅包含请求的输出组中通告的文件（由 --output_groups 标志确定）。其中包含源文件。

此输出格式发出的所有路径都是相对于 execroot 的，可通过 bazel info execution_root 获取。如果存在 bazel-out 便利符号链接，主代码库中文件的路径也会相对于工作区目录进行解析。

使用 Starlark 定义输出格式

--output=starlark

此输出格式针对查询结果中配置的每个目标调用 Starlark 函数，并输出调用返回的值。--starlark:file 标志指定 Starlark 文件的位置，该文件定义了一个名为 format 且具有单个参数 target 的函数。系统会针对查询结果中的每个 Target 调用此函数。或者，为方便起见，您可以使用 --starlark:expr 标志仅指定声明为 def format(target): return expr 的函数的正文。

“cquery”Starlark 方言

cquery Starlark 环境与 BUILD 或 .bzl 文件不同。它包含所有核心 Starlark 内置常量和函数，以及下文所述的一些特定于 cquery 的常量和函数，但不包含（例如）glob、native 或 rule，并且不支持加载语句。

build_options（目标）

build_options(target) 会返回映射，其键为 build 选项标识符（请参阅配置），其值为 Starlark 值。此映射省略了值不是合法 Starlark 值的构建选项。

如果目标是输入文件，build_options(target) 会返回 None，因为输入文件目标具有 null 配置。

提供方（目标）

providers(target) 会返回映射，其键为提供程序的名称（例如 "DefaultInfo"），其值为 Starlark 值。此映射中省略了值不是合法 Starlark 值的提供程序。

示例

输出由 //foo 生成的所有文件的基准名称列表（以空格分隔）：

  bazel cquery //foo --output=starlark \
    --starlark:expr="' '.join([f.basename for f in target.files.to_list()])"

输出由 //bar 及其子软件包中的 rule 目标生成的所有文件的路径列表（以空格分隔）：

  bazel cquery 'kind(rule, //bar/...)' --output=starlark \
    --starlark:expr="' '.join([f.path for f in target.files.to_list()])"

输出 //foo 注册的所有操作的助记符列表。

  bazel cquery //foo --output=starlark \
    --starlark:expr="[a.mnemonic for a in target.actions]"

输出由 cc_library //baz 注册的编译输出列表。

  bazel cquery //baz --output=starlark \
    --starlark:expr="[f.path for f in target.output_groups.compilation_outputs.to_list()]"

在构建 //foo 时，输出命令行选项 --javacopt 的值。

  bazel cquery //foo --output=starlark \
    --starlark:expr="build_options(target)['//command_line_option:javacopt']"

仅输出每个目标的标签。此示例使用文件中定义的 Starlark 函数。

  $ cat example.cquery

  def has_one_output(target):
    return len(target.files.to_list()) == 1

  def format(target):
    if has_one_output(target):
      return target.label
    else:
      return ""

  $ bazel cquery //baz --output=starlark --starlark:file=example.cquery

输出每个目标（严格来说是 Python 3）的标签。此示例使用文件中定义的 Starlark 函数。

  $ cat example.cquery

  def format(target):
    p = providers(target)
    py_info = p.get("PyInfo")
    if py_info and py_info.has_py3_only_sources:
      return target.label
    else:
      return ""

  $ bazel cquery //baz --output=starlark --starlark:file=example.cquery

从用户定义的提供程序中提取值。

  $ cat some_package/my_rule.bzl

  MyRuleInfo = provider(fields={"color": "the name of a color"})

  def _my_rule_impl(ctx):
      ...
      return [MyRuleInfo(color="red")]

  my_rule = rule(
      implementation = _my_rule_impl,
      attrs = {...},
  )

  $ cat example.cquery

  def format(target):
    p = providers(target)
    my_rule_info = p.get("//some_package:my_rule.bzl%MyRuleInfo'")
    if my_rule_info:
      return my_rule_info.color
    return ""

  $ bazel cquery //baz --output=starlark --starlark:file=example.cquery

cquery 与 query

cquery 和 query 互为补充，在不同的小众领域有出色表现。请考虑以下几点，以确定哪种做法适合您：

• cquery 跟随特定的 select() 分支构建您构建的确切图表。query 不知道 build 选择哪个分支，因此可通过添加所有分支来确定近似值。
• 与 query 相比，cquery 的精度需要构建更多图表。具体而言，cquery 仅评估已配置的目标，而 query 仅评估目标。这需要更多时间和更多内存。
• cquery 对查询语言的解释引入了 query 避免的歧义。例如，如果"//foo"存在两种配置，cquery "deps(//foo)"应该使用哪种配置？ config 函数可以解决此问题。
• 作为一种新工具，cquery 无法支持某些用例。如需了解详情，请参阅已知问题。

已知问题

cquery“构建”的所有目标都必须具有相同的配置。

在评估查询之前，cquery 会在构建操作即将执行之前触发构建。默认情况下，系统会从查询表达式中出现的所有标签中选择其“构建”的目标（这可以使用 --universe_scope 替换）。这些配置必须具有相同的配置。

虽然这些规则通常与顶级“目标”配置共享，但规则可以通过传入的边缘转换更改自己的配置。这就是 cquery 的欠缺之处。

权宜解决方法：请尽可能将 --universe_scope 设置为更严格的范围。例如：

# This command attempts to build the transitive closures of both //foo and
# //bar. //bar uses an incoming edge transition to change its --cpu flag.
$ bazel cquery 'somepath(//foo, //bar)'
ERROR: Error doing post analysis query: Top-level targets //foo and //bar
have different configurations (top-level targets with different
configurations is not supported)

# This command only builds the transitive closure of //foo, under which
# //bar should exist in the correct configuration.
$ bazel cquery 'somepath(//foo, //bar)' --universe_scope=//foo

不支持 --output=xml。

非确定性输出。

cquery 不会自动从先前的命令擦除 build 图，因此容易从过往查询中提取结果。例如，genquery 对其 tools 属性执行执行转换，也就是说，它会在执行配置中配置其工具。

您可以在下面了解这种过渡的效果。

$ cat > foo/BUILD <<<EOF
genrule(
    name = "my_gen",
    srcs = ["x.in"],
    outs = ["x.cc"],
    cmd = "$(locations :tool) $< >$@",
    tools = [":tool"],
)
cc_library(
    name = "tool",
)
EOF

    $ bazel cquery "//foo:tool"
tool(target_config)

    $ bazel cquery "deps(//foo:my_gen)"
my_gen (target_config)
tool (exec_config)
...

    $ bazel cquery "//foo:tool"
tool(exec_config)

临时解决方法：更改任意启动选项，强制重新分析已配置的目标。 例如，将 --test_arg=<whatever> 添加到您的 build 命令中。

问题排查

递归目标模式 (/...)

如果您遇到以下情况：

$ bazel cquery --universe_scope=//foo:app "somepath(//foo:app, //foo/...)"
ERROR: Error doing post analysis query: Evaluation failed: Unable to load package '[foo]'
because package is not in scope. Check that all target patterns in query expression are within the
--universe_scope of this query.

即使 --universe_scope=//foo:app 包含该软件包，这也错误地表明 //foo 软件包不在范围内。这是由于 cquery 中的设计限制。如需解决此问题，请在宇宙作用域中明确添加 //foo/...：

$ bazel cquery --universe_scope=//foo:app,//foo/... "somepath(//foo:app, //foo/...)"

如果这样做不起作用（例如，由于 //foo/... 中的某些目标无法使用所选的构建标志进行构建），请使用预处理查询手动将模式解封到其组成软件包中：

# Replace "//foo/..." with a subshell query call (not cquery!) outputting each package, piped into
# a sed call converting "<pkg>" to "//<pkg>:*", piped into a "+"-delimited line merge.
# Output looks like "//foo:*+//foo/bar:*+//foo/baz".
#
$  bazel cquery --universe_scope=//foo:app "somepath(//foo:app, $(bazel query //foo/...
--output=package | sed -e 's/^/\/\//' -e 's/$/:*/' | paste -sd "+" -))"