操作图表查询（查询）

每夜版 · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

您可以使用 aquery 命令查询 build 图中的操作。它基于分析后的配置目标图运行，并公开有关操作、制品及其关系的信息。

如果您对从配置的目标图生成的 Action/制品感兴趣，aquery 会很有用。例如，实际运行的命令及其输入/输出/助记符。

该工具接受多个命令行选项。 值得注意的是，aquery 命令在常规 Bazel build 的基础上运行，并继承 build 期间可用的选项集。

它支持与传统 query 相同的函数集，但 siblings、buildfiles 和 tests 除外。

aquery 输出示例（不含具体详细信息）：

$ bazel aquery 'deps(//some:label)'
action 'Writing file some_file_name'
  Mnemonic: ...
  Target: ...
  Configuration: ...
  ActionKey: ...
  Inputs: [...]
  Outputs: [...]

基本语法

aquery 的简单语法示例如下：

bazel aquery "aquery_function(function(//target))"

查询表达式（用英文引号括起来）包含以下内容：

  • aquery_function(...)：特定于 aquery 的函数。 更多详情请见下文。
  • function(...)：标准函数，以传统 query 的形式。
  • //target 是感兴趣的目标的标签。
# aquery examples:
# Get the action graph generated while building //src/target_a
$ bazel aquery '//src/target_a'

# Get the action graph generated while building all dependencies of //src/target_a
$ bazel aquery 'deps(//src/target_a)'

# Get the action graph generated while building all dependencies of //src/target_a
# whose inputs filenames match the regex ".*cpp".
$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

使用 aquery 函数

有三个 aquery 函数：

  • inputs：按输入过滤操作。
  • outputs：按输出过滤操作
  • mnemonic：按助记符过滤操作

expr ::= inputs(word, expr)

inputs 运算符返回通过构建 expr 生成的操作，这些操作的输入文件名与 word 提供的正则表达式匹配。

$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

outputs 和 mnemonic 函数的语法类似。

您还可以组合使用函数来实现 AND 运算。例如：

  $ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'

上述命令会查找构建 //src/target_a 所涉及的所有操作，这些操作的助记符与 "Cpp.*" 匹配，输入与模式 ".*cpp" 和 "foo.*" 匹配。

以下是产生的语法错误示例：

        $ bazel aquery 'deps(inputs(".*cpp", //src/target_a))'
        ERROR: aquery filter functions (inputs, outputs, mnemonic) produce actions,
        and therefore can't be the input of other function types: deps
        deps(inputs(".*cpp", //src/target_a))

选项

build 选项

aquery 在常规 Bazel build 的基础上运行，因此会继承 build 期间可用的选项集。

Aquery 选项

--output=(text|summary|proto|jsonproto|textproto), default=text

默认输出格式 (text) 是人类可读的，请使用 proto、textproto 或 jsonproto 获取机器可读的格式。 proto 消息为 analysis.ActionGraphContainer。

--include_commandline, default=true

在输出中包含操作命令行（可能很大）。

--include_artifacts, default=true

在输出中包含操作输入和输出的名称（可能很大）。

--include_aspects, default=true

是否在输出中包含 Aspect 生成的操作。

--include_param_files, default=false

包含命令中使用的参数文件的内容（可能很大）。

--include_file_write_contents, default=false

针对 actions.write() 操作包含文件内容，针对 SourceSymlinkManifest 操作包含清单文件的内容。文件内容会以 --output=xxxproto 的形式在 file_contents 字段中返回。 使用 --output=text 时，输出包含 FileWriteContents: [<base64-encoded file contents>] 行

--skyframe_state, default=false

无需执行额外的分析，即可从 Skyframe 转储操作图。

其他工具和功能

针对 Skyframe 的状态进行查询

Skyframe 是 Bazel 的评估和增量模型。在每个 Bazel 服务器实例上，Skyframe 都会存储从之前运行的分析阶段构建的依赖关系图。

在某些情况下，查询 Skyframe 上的操作图非常有用。以下是一个使用场景示例：

  1. 运行 bazel build //target_a
  2. 运行 bazel build //target_b
  3. 已生成文件 foo.out。

作为 Bazel 用户，我想确定 foo.out 是通过构建 //target_a 还是 //target_b 生成的。

可以运行 bazel aquery 'outputs("foo.out", //target_a)' 和 bazel aquery 'outputs("foo.out", //target_b)' 来找出负责创建 foo.out 的操作，进而找出目标。不过，之前构建的不同目标的数量可能超过 2 个，这使得运行多个 aquery 命令非常麻烦。

作为替代方案，您可以使用 --skyframe_state 标志：

  # List all actions on Skyframe's action graph
  $ bazel aquery --output=proto --skyframe_state

  # or

  # List all actions on Skyframe's action graph, whose output matches "foo.out"
  $ bazel aquery --output=proto --skyframe_state 'outputs("foo.out")'

在 --skyframe_state 模式下，aquery 会获取 Skyframe 保留在 Bazel 实例上的 Action Graph 的内容，（可选）对其进行过滤，然后输出内容，而无需重新运行分析阶段。

特殊注意事项

输出格式

--skyframe_state 目前仅适用于 --output=proto 和 --output=textproto

查询表达式中未包含目标标签

目前，--skyframe_state 会查询 Skyframe 上存在的整个操作图，而不管目标是什么。在查询中指定目标标签并同时指定 --skyframe_state 会被视为语法错误：

  # WRONG: Target Included
  $ bazel aquery --output=proto --skyframe_state **//target_a**
  ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.

  # WRONG: Target Included
  $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java", **//target_a**)'
  ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.

  # CORRECT: Without Target
  $ bazel aquery --output=proto --skyframe_state
  $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java")'

比较 aquery 输出

您可以使用 aquery_differ 工具比较两次不同的 aquery 调用输出。例如，当您对规则定义进行了一些更改，并想验证正在运行的命令行是否未发生变化时，aquery_differ 是实现此目的的工具。

该工具位于 bazelbuild/bazel 代码库中。如需使用该代码库，请将其克隆到本地机器。用法示例：

  $ bazel run //tools/aquery_differ -- \
  --before=/path/to/before.proto \
  --after=/path/to/after.proto \
  --input_type=proto \
  --attrs=cmdline \
  --attrs=inputs

上述命令会返回 before 和 after aquery 输出之间的差异：哪些操作存在于一个输出中，但不存在于另一个输出中；哪些操作在每个 aquery 输出中具有不同的命令行/输入；等等。运行上述命令的结果如下：

  Aquery output 'after' change contains an action that generates the following outputs that aquery output 'before' change doesn't:
  ...
  /list of output files/
  ...

  [cmdline]
  Difference in the action that generates the following output(s):
    /path/to/abc.out
  --- /path/to/before.proto
  +++ /path/to/after.proto
  @@ -1,3 +1,3 @@
    ...
    /cmdline diff, in unified diff format/
    ...

命令选项

--before, --after：要比较的 aquery 输出文件

--input_type=(proto|text_proto), default=proto：输入文件的格式。支持 proto 和 textproto aquery 输出。

--attrs=(cmdline|inputs), default=cmdline：要比较的操作的属性。

方面到方面

方面可以叠加应用。由这些 Aspect 生成的操作的 aquery 输出随后将包含 Aspect 路径，即应用于生成相应操作的目标的 Aspect 序列。

Aspect-on-Aspect 的示例：

  t0
  ^
  | <- a1
  t1
  ^
  | <- a2
  t2

假设 ti 是规则 ri 的目标，该规则会将其方面 ai 应用于其依赖项。

假设 a2 在应用于目标 t0 时会生成操作 X。针对操作 X 的 bazel aquery --include_aspects 'deps(//t2)' 的文本输出将如下所示：

  action ...
  Mnemonic: ...
  Target: //my_pkg:t0
  Configuration: ...
  AspectDescriptors: [//my_pkg:rule.bzl%**a2**(foo=...)
    -> //my_pkg:rule.bzl%**a1**(bar=...)]
  ...

这意味着，操作 X 是通过将 Aspect a2 应用到 a1(t0) 上生成的，其中 a1(t0) 是将 Aspect a1 应用到目标 t0 上得到的结果。

每个 AspectDescriptor 的格式如下：

  AspectClass([param=value,...])

AspectClass 可以是 Aspect 类的名称（对于原生 Aspect），也可以是 bzl_file%aspect_name（对于 Starlark Aspect）。AspectDescriptor 按依赖关系图的拓扑顺序排序。

与 JSON 配置文件相关联

虽然 aquery 可提供有关 build 中正在运行的操作的信息（运行原因、输入/输出），但 JSON 配置文件会告知我们这些操作的执行时间和时长。可以通过一个共同点（即操作的主要输出）来合并这两组信息。

如需在 JSON 配置文件中包含操作的输出，请使用 --experimental_include_primary_output --noexperimental_slim_json_profile 生成配置文件。精简版配置文件与包含主要输出不兼容。aquery 默认包含操作的主要输出。

我们目前没有提供用于合并这两个数据源的规范工具，但您应该能够使用上述信息构建自己的脚本。

已知问题

处理共享操作

有时，操作会在配置的目标之间共享。

在执行阶段，这些共享操作仅被视为一个，并且仅执行一次。不过，aquery 在执行前、分析后的操作图上运行，因此会将这些视为单独的操作，其输出制品具有完全相同的 execPath。因此，等效制品会重复显示。

您可以在 GitHub 上找到 aquery 问题/计划功能列表。

常见问题解答

即使输入文件的内容发生了变化，ActionKey 仍保持不变。

在 aquery 的上下文中，ActionKey 是指从 ActionAnalysisMetadata#getKey 获取的 String：

  Returns a string encoding all of the significant behaviour of this Action that might affect the
  output. The general contract of `getKey` is this: if the work to be performed by the
  execution of this action changes, the key must change.

  ...

  Examples of changes that should affect the key are:

  - Changes to the BUILD file that materially affect the rule which gave rise to this Action.
  - Changes to the command-line options, environment, or other global configuration resources
      which affect the behaviour of this kind of Action (other than changes to the names of the
      input/output files, which are handled externally).
  - An upgrade to the build tools which changes the program logic of this kind of Action
      (typically this is achieved by incorporating a UUID into the key, which is changed each
      time the program logic of this action changes).
  Note the following exception: for actions that discover inputs, the key must change if any
  input names change or else action validation may falsely validate.

这不包括对输入文件内容的更改，请勿与 RemoteCacheClient#ActionKey 混淆。

更新

如有任何问题/功能请求，请点击此处提交问题。