Bazel aquery 怎么确认实际执行的编译命令

如果你只看 BUILD 规则，很难回答“这次构建到底执行了什么编译命令”。Bazel 的 aquery 查询的是分析阶段生成的 action graph，可以把某个目标关联的 action、Mnemonic、命令行、输入和输出直接展开。最常用的做法是先用目标标签缩小范围，再用 --output=commands 读取命令，最后用 mnemonic 或 inputs 过滤。

官方文档：https://bazel.build/query/aquery

要确认实际编译命令，不要只在规则文件里猜参数。先运行 bazel aquery 得到 action，再从同一个 action 的 Command Line、Inputs、Outputs 和 Target 四个字段交叉确认。

先把查询范围落到目标和依赖

在项目根目录打开终端，确认当前目录能找到 WORKSPACE、MODULE.bazel 或对应的 Bazel 工作区文件。第一条命令不要急着加很多过滤条件，先让查询结果证明目标确实能展开为 action。

# 查询目标及其依赖对应的 action graph
bazel aquery 'deps(//app:main)'

# 只查询目标本身生成的 action，便于先确认标签是否正确
bazel aquery '//app:main'

官方示例把 deps(//src:target_a) 作为普通查询函数嵌入 aquery 表达式。运行后，你应在结果中看到类似 action、Mnemonic、Target、Inputs 和 Outputs 的字段。这里的“看到”只是命令输出的字段判断，不表示已经执行了一次新的编译。

如果结果为空，先检查三个位置：目标标签是否属于当前工作区，查询表达式的引号是否完整，以及当前 Bazel 配置是否与平时构建使用的配置一致。先修正范围，再添加过滤器，排查会更容易。

用 commands 输出直接看到编译命令

默认的文本格式适合查看 action 的整体信息；如果目标是确认编译器实际收到的参数，可以把输出切换为 commands。同时保留命令行信息，让结果从“某个 CppCompile action”变成可对照的一行命令。

# 以命令行格式输出依赖树中的构建命令
bazel aquery \
  --output=commands \
  --include_commandline=true \
  'deps(//app:main)'

# 同时保留输入和输出，方便把命令归属到具体 action
bazel aquery \
  --output=text \
  --include_commandline=true \
  --include_artifacts=true \
  'deps(//app:main)'

--output=commands 会按每行一个命令输出，适合快速复制到排查记录中；它不保证结果顺序，不能把第一行命令当成固定排序结果。想知道命令属于哪个目标时，改用文本格式并保留 Target、Mnemonic、Inputs 和 Outputs，再与 commands 输出对照。

在软件说明图中，可以把这条操作理解为“Query 输入框 → Output 选择 commands → 执行 → 打开 action 详情”。这只是帮助读者理解字段关系的原创界面示意，Bazel 本身仍然通过命令行参数工作。

如果命令行显示不全，先确认没有关闭 --include_commandline；如果输入输出缺少，再确认 --include_artifacts 没有被关闭。参数较多时，可以把原始输出保存到文件，但保存动作只改变记录方式，不改变 aquery 的查询语义。

用 mnemonic 和 inputs 过滤目标 action

依赖较多时，完整 action graph 会很长。aquery 提供三个专用过滤函数：inputs 按输入文件名匹配，outputs 按输出文件名匹配，mnemonic 按动作类型匹配。过滤函数的输入仍然应该是普通 query 表达式，例如 deps(//app:main)。

# 只看 Cpp 开头的编译类 action
bazel aquery \
  'mnemonic("Cpp.*", deps(//app:main))'

# 只保留输入文件名匹配 .cpp 的 action
bazel aquery \
  'inputs(".*\\.cpp", deps(//app:main))'

# 同时按动作类型和输入文件缩小结果
bazel aquery \
  'mnemonic("Cpp.*", inputs(".*\\.cpp", deps(//app:main)))'

这里的嵌套顺序有一个容易踩的边界：mnemonic、inputs、outputs 产生的是 action，不能再把它们放进 deps 这类需要 configured target 的普通函数中。错误的方向通常长这样：

# 错误示例：先产生 action，再把 action 当成 deps 的输入
bazel aquery 'deps(inputs(".*\\.cpp", //app:main))'

# 正确示例：先用 deps 得到目标范围，再在 action 上过滤
bazel aquery 'inputs(".*\\.cpp", deps(//app:main))'

看到“过滤函数产生 actions，不能作为其他函数输入”一类错误时，优先调整表达式的层级，不要先怀疑编译器参数。过滤成功的可见状态是：结果中的 action 数量明显减少，同时每条结果仍能找到对应的 Target 或输出文件。

最后按四个字段复核定位结果

找到候选 action 后，按下面顺序复核，而不是只复制一行命令：

1. Mnemonic：确认它确实是编译、链接或其他你要排查的动作类型。
2. Target：确认 action 属于目标本身还是依赖目标，避免把依赖库的参数误认为主目标参数。
3. Command Line：查看编译器、宏、头文件目录、优化选项等实际传入内容。
4. Inputs / Outputs：确认输入源文件、生成文件和最终产物之间的归属关系。

当你需要把结果交给脚本处理时，可改用 jsonproto、textproto 或 proto。机器格式更适合保存和比较，但字段更多，阅读时仍建议先用文本输出确定 action，再决定是否切换格式。

# 机器可读格式用于后续脚本处理
bazel aquery \
  --output=jsonproto \
  --include_commandline=true \
  --include_artifacts=true \
  'mnemonic("Cpp.*", deps(//app:main))'

两个容易误判的边界

aquery 显示的是分析后的 action，不是执行日志

aquery 基于分析阶段生成的 action graph，擅长回答“Bazel 为这个目标准备了哪些动作、命令、输入和输出”。它不负责告诉你每个动作实际花了多长时间；如果要研究执行耗时，应结合 JSON profile 等执行信息单独分析。

参数文件和树形制品可能让命令看起来不完整

官方文档特别提醒，树形制品的内容在 action 执行后才知道，因此 aquery 可能只展示目录路径，而参数文件在真正执行时包含更细的文件列表。遇到命令行与磁盘上的参数文件不完全一致时，先判断是否涉及 tree artifact，不要直接认定 aquery 找错了 action。

需要对比改动前后的命令时怎么办

可以分别保存两次 aquery 的 proto 输出，再使用 Bazel 仓库提供的 aquery_differ 比较命令行或输入变化。对比时关注 action 的输出归属，不要依赖输出的固定顺序。

总结

确认 Bazel 实际执行的编译命令，可以固定成一条排查路径：先用 bazel aquery 'deps(目标)' 展开 action graph，再用 --output=commands 查看命令，必要时用 mnemonic、inputs 和 outputs 缩小范围，最后把 Mnemonic、Target、Command Line、Inputs 和 Outputs 放在一起复核。表达式中先得到目标范围、后做 action 过滤，基本可以避开最常见的类型错误。