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)
每个结果都包含目标 build 所用的配置的唯一标识符 (9f87702)。
由于 cquery 在配置的目标图上运行，因此它无法了解 build 操作等制品，也无法访问 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 会评估已配置的目标，而 build 图可能具有 //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 支持除 allrdeps、buildfiles、rbuildfiles、siblings、tests 和 visible 之外的所有函数。
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)"
如果无法在指定配置中找到第一个实参的所有结果，则仅返回可以找到的结果。如果在指定配置中找不到任何结果，查询会失败。
选项
构建选项
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_binary(
name = "tool",
srcs = ["tool.cpp"],
)
Genrule 会在 exec 配置中配置其工具，因此以下查询会产生以下输出：
| 查询 | 目标已构建 | 输出 |
|---|---|---|
| bazel cquery "//x:tool" | //x:tool | //x:tool(targetconfig) |
| bazel cquery "//x:tool" --universe_scope="//x:my_gen" | //x:my_gen | //x:tool(execconfig) |
如果设置了此标志，则会构建其内容。如果未设置，则会构建查询表达式中提及的所有目标。所构建目标的传递闭包用作查询的宇宙。无论哪种方式，要构建的目标都必须可在顶层构建（即与顶层选项兼容）。cquery 会返回这些顶级目标的传递闭包中的结果。
即使可以在顶级查询表达式中构建所有目标，但最好不要这样做。例如，明确设置 --universe_scope 可以防止在您不关心的配置中多次构建目标。它还可以帮助指定您要查找的目标的哪个配置版本。如果您的查询表达式比 deps(//foo) 更复杂，则应设置此标志。
--implicit_deps（布尔值，默认值为 True）
将此标志设置为 false 会滤除所有未在 BUILD 文件中明确设置、而是由 Bazel 在其他位置设置的结果。这包括过滤已解析的工具链。
--tool_deps（布尔值，默认值为 True）
将此标志设置为 false 会过滤掉所有已配置的目标，从查询的目标到这些目标的路径会跨越目标配置和非目标配置之间的过渡。如果查询的目标位于目标配置中，则设置 --notool_deps 将仅返回也位于目标配置中的目标。如果查询的目标处于非目标配置中，则设置 --notool_deps 将仅返回同样处于非目标配置中的目标。此设置通常不会影响已解析的工具链的过滤。
--include_aspects（布尔值，默认值为 True）
包含由方面添加的依赖项。
如果此标志处于停用状态，则 cquery somepath(X, Y) 和 cquery deps(X) | grep 'Y' 会省略 Y（如果 X 仅通过方面依赖于 Y）。
输出格式
默认情况下，cquery 会以标签和配置对的依赖项有序列表的形式输出结果。您还可以通过其他方式公开结果。
转场效果
--transitions=lite --transitions=full
配置转换用于以不同于顶级目标的配置构建顶级目标下的目标。
例如，目标可能会在其 tools 属性中对所有依赖项强制执行向 exec 配置的转换。这些称为属性过渡。规则还可以对其自身配置施加过渡，称为规则类过渡。此输出格式会输出有关这些过渡的信息，例如它们的类型以及它们对 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 获取 execroot。如果存在 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，并且不支持 load 语句。
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 providers(target)['DefaultInfo'].files.to_list()])"
输出 //bar 及其子软件包中 rule 目标生成的所有文件的路径（以空格分隔）：
bazel cquery 'kind(rule, //bar/...)' --output=starlark \
--starlark:expr="' '.join([f.path for f in providers(target)['DefaultInfo'].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(providers(target)["DefaultInfo"].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 选择哪个分支，因此通过包含所有分支进行过近似。cquery的精确度要求构建比query更多的图。具体而言，cquery会评估已配置的目标，而query只会评估目标。这需要更多时间，并会占用更多内存。cquery对查询语言的解读会引入query避免的歧义。例如，如果"//foo"存在于两个配置中，cquery "deps(//foo)"应该使用哪个？config函数可以帮助您解决这一问题。
非确定性输出
cquery 不会自动清除之前命令中的 build 图。因此，它很容易从过去的查询中获取结果。
例如，genrule 对其 tools 属性施加了 exec 转换，也就是说，它在 exec 配置中配置了其工具。
您可以在下方看到该过渡期的持续影响。
$ cat > foo/BUILD <<这种行为是否理想取决于您要评估的内容。
如需停用此功能，请在运行
cquery之前运行blaze clean，以确保获得最新的分析图。问题排查
递归目标模式 (
/...)如果您遇到以下情况：
这会错误地表明软件包
//foo不在范围内，即使--universe_scope=//foo:app包含它也是如此。这是由于cquery中的设计限制所致。作为一种解决方法，请在全集范围内明确包含//foo/...：如果此方法不起作用（例如，因为
//foo/...中的某些目标无法使用所选的 build 标志进行 build），请使用预处理查询手动将该模式解包为组成软件包：