可配置查询 (cquery)

7.3 · 7.2 · 7.1 · 7.0 · 6.5

cquery 是 query 的变体，可正确处理 select() 和 build 选项对 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 在配置的目标图上运行，因此它无法深入了解 build 操作等工件，也无法访问 [test_suite](/versions/6.2.0/reference/be/general#test_suite) 规则，因为它们不是配置的目标。如需了解前者，请参阅 [aquery](/versions/6.2.0/docs/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

主机配置使用特殊 ID (HOST)。非生成的源文件（例如通常在 srcs 中找到的源文件）使用特殊 ID (null)（因为它们不需要配置）。

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

目标模式评估

对于 cquery，//foo 的含义与 query 不同。这是因为 cquery 会评估已配置的目标，而 build 图表可能包含多个已配置的 //foo 版本。

对于 cquery，查询表达式中的目标模式会针对具有与该模式匹配的标签的每个已配置目标进行评估。输出是确定性的，但 cquery 除了核心查询排序协定之外，不对排序做出任何保证。

与 query 相比，这会为查询表达式生成更细微的结果。例如，以下查询可能会产生多个结果：

# Analyzes //foo in the target configuration, but also analyzes
# //genrule_with_foo_as_tool which depends on a host-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 (HOST)

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

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

函数

在 query 支持的一组函数中，cquery 支持其中的所有函数，但不支持 allrdeps、buildfiles、rbuildfiles、siblings、tests 和 visible。

cquery 还引入了以下新函数：

config

expr ::= config(expr, word)

config 运算符会尝试为第一个参数表示的标签和第二个参数指定的配置找到已配置的目标。

第二个参数的有效值包括 target、host、null 或自定义配置哈希。哈希值可从 $ bazel config 或上一个 cquery 的输出中检索。

示例：

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

$ bazel cquery "deps(//foo)"
//bar (HOST)
//baz (3732cc8)

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

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

选项

build 选项

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

使用 cquery 选项

--universe_scope（英文逗号分隔列表）

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

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

Genrules 会在主机配置中配置其工具，因此以下查询将生成以下输出：

查询	目标构建	输出
bazel cquery "//x:tool"	//x:tool	//x:tool(targetconfig)
bazel cquery "//x:tool" --universe_scope="//x:my_gen"	//x:my_gen	//x:tool(hostconfig)

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

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

--implicit_deps（布尔值，默认值为 True）

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

--tool_deps（布尔值，默认值为 True）

将此标志设为 false 会滤除所有配置的目标，其中从查询的目标到这些目标的路径会跨越目标配置和非目标配置之间的转换。如果查询的目标位于目标配置中，则设置 --notool_deps 将仅返回同时位于目标配置中的目标。如果查询的目标处于非目标配置中，设置 --notool_deps 只会返回也处于非目标配置中的目标。此设置通常不会影响已解析工具链的过滤。

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

切面可以向 build 添加其他依赖项。默认情况下，cquery 不会遵循切面，因为它们会使可查询图变大，而占用更多内存。但遵循这些准则可以获得更准确的结果。

如果您不担心大型查询对内存的影响，请在 bazelrc 中默认启用此标志。

如果您在停用方面的情况下进行查询，可能会遇到以下问题：在构建目标 Y 时，目标 X 会失败，但 cquery somepath(Y, X) 和 cquery deps(Y) | grep 'X' 不会返回任何结果，因为依赖项是通过方面发生的。

输出格式

默认情况下，cquery 会输出按依赖项排序的标签和配置对列表。您还可以通过其他方式显示结果。

转场效果

--transitions=lite
--transitions=full

配置转换用于在与顶级目标不同的配置中构建顶级目标下方的目标。

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

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

协议消息输出

--output=proto

此选项会导致生成的目标以二进制协议缓冲区形式输出。如需查看协议缓冲区的定义，请参阅 src/main/protobuf/analysis.proto。

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

--[no]proto:include_configurations

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

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

注意：虽然选择操作会在返回的目标的顶级和属性中解析，但选择操作的所有可能输入仍会作为 rule_input 字段包含在内。

图表输出

--output=graph

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

文件输出

--output=files

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

注意：bazel cquery --output=files //pkg:foo 的输出包含构建过程中发生的所有配置中的 //pkg:foo 输出文件（另请参阅“目标模式评估”部分）。如果不希望这样，请将查询封装在 config(..., target) 中。

使用 Starlark 定义输出格式

--output=starlark

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

“cquery”Starlark 方言

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

build_options(target)

build_options(target) 会返回一个映射，该映射的键是 build 选项标识符（请参阅配置），其值是其 Starlark 值。值不是有效 Starlark 值的 build 选项会从此映射中省略。

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

providers(target)

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](#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 (host_config)
...

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

权宜解决方法：更改任何启动选项，以强制重新分析已配置的目标。例如，将 --test_arg=<whatever> 添加到构建命令。

问题排查

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

如果您遇到以下问题：

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

这会错误地提示软件包 //foo 不在范围内，即使 --universe_scope=//foo:app 包含该软件包也是如此。这是由于 cquery 中的设计限制所致。如需解决此问题，请在“universe”作用域中明确添加 //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 "+" -))"