blob: 0228d2b3e2ef12cba4d23eaf0a5ffd4a55faeb9d [file] [log] [blame]
---
layout: documentation
title: Aquery (Action Graph Query)
---
<h1>Aquery (Action Graph Query)</h1>
<ul class="toc">
<li><a href="#overview">Overview</a></li>
<li><a href="#basic-syntax">Basic Syntax</a></li>
<li><a href="#functions">Aquery Functions</a></li>
<li><a href="#options">Options</a></li>
<li><a href="#misc">Miscellaneous</a></li>
<li><a href="#known-issues">Known Issues</a></li>
<li><a href="#updates">Updates</a></li>
</ul>
<h2 id='overview'>Overview</h2>
<b>Caution</b>: The aquery command is still experimental and its API will change.
<p>
The <code>aquery</code> command allows you to query for actions in your build graph.
It operates on the post-analysis Configured Target Graph and exposes
information about <b>Actions, Artifacts and their relationships.</b>
</p>
<p>
<code>aquery</code> is useful when we are interested in the properties of the Actions/Artifacts
generated from the Configured Target Graph. For example, the actual commands run
and their inputs/outputs/mnemonics.
</p>
<p>
The tool accepts several command-line <a href="#aquery-options">options</a>.
Notably, the aquery command runs on top of a regular Bazel build and inherits
the set of options available during a build.
</p>
<p>
It supports the same set of functions that is also available to traditional
<code>query</code> but <code>siblings</code>, <code>buildfiles</code> and
<code>tests</code>.
</p>
<p>An example <code>aquery</code> output (without specific details):</p>
<pre>
$ bazel aquery 'deps(//some:label)'
action 'Writing file some_file_name'
Mnemonic: ...
Owner: ...
Configuration: ...
ActionKey: ...
Inputs: [...]
Outputs: [...]
</pre>
<h2 id='basic-syntax'>Basic Syntax</h2>
<p>A simple example of the syntax for <code>aquery</code> is as follows:</p>
<p><code>bazel aquery "aquery_function(function(//target))"</code></p>
<p>The query expression (in quotes) consists of the following:
<ul>
<li>
<code>aquery_function(...)</code>: functions specific to <code>aquery</code>.
More details <a href="#functions">below</a>.
</li>
<li>
<code>function(...)</code>: the standard <a href="query.html#functions">functions</a>
as traditional <code>query</code>.
</li>
<li>
<code>//target</code> is the label to the interested target.
</li>
</ul>
<pre>
# 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))'
</pre>
<h2 id='functions'>Aquery Functions</h2>
<p>There are currently 3 <code>aquery</code> functions:</p>
<ul>
<li><code>inputs</code>: filter actions by inputs.</li>
<li><code>outputs</code>: filter actions by outputs</li>
<li><code>mnemonic</code>: filter actions by mnemonic</li>
</ul>
<p><code>expr ::= inputs(word, expr)</code></p>
<p>
The <code>inputs</code> operator returns the actions generated from building <code>expr</code>,
whose input filenames match the regex provided by <code>word</code>.
</p>
<p><code>$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'</code></p>
<p><code>outputs</code> and <code>mnemonic</code> functions share a similar syntax.</p>
<p>You can also combine functions to achieve the AND operation. For example:</p>
<pre>
$ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'
</pre>
<p>
The above command would find all actions involved in building <code>//src/target_a</code>,
whose mnemonics match <code>"Cpp.*"</code> and inputs match the patterns
<code>".*cpp"</code> and <code>"foo.*"</code>.
</p>
<h3>Important: aquery functions can't be nested inside non-aquery functions</h3>
<ul>
<li>Conceptually this makes sense since the output of aquery functions is Actions,
not Configured Targets.</li>
<li>
An example of the syntax error produced:
<pre>
$ 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))
</pre>
</li>
</ul>
<h2 id='options'>Options</h2>
<h3>Build Options</h3>
<p>
<code>aquery</code> runs on top of a regular Bazel build and thus inherits the set of
<a href="command-line-reference.html#build-options">options</a>
available during a build.
</p>
<h3 id="aquery-options">Aquery options</h3>
<h4><code class='flag'>--output=(text|proto|textproto), default=text</code></h4>
<p>
The default output format (<code>text</code>) is human-readable,
use <code>proto</code> or <code>textproto</code> for machine-readable format.
</p>
<h4><code class='flag'>--include_commandline, default=true</code></h4>
<p>
Includes the content of the action command lines in the output (potentially large).
</p>
<h4><code class='flag'>--include_aspects, default=false</code></h4>
<p>
Whether to include Aspect-generated actions in the output.
</p>
<h4><code class='flag'>--include_param_files, default=false</code></h4>
<p>
Include the content of the param files used in the command (potentially large).
Warning: Enabling this flag will automatically enable the <code>--include_commandline</code> flag.
</p>
<h2 id='misc'>Miscellaneous</h2>
<h3>Aspect-on-Aspect</h3>
<p>
It is possible for <a href="https://docs.bazel.build/versions/master/skylark/aspects.html">Aspects</a>
to be applied on top of each other. The aquery output of the action generated by these Aspects would
then include the <i>Aspect path</i>, which is the sequence of Aspects applied to the target which generated the action.
</p>
<p>An example of Aspect-on-Aspect:</p>
<pre>
t0
^
| <- a1
t1
^
| <- a2
t2
</pre>
<p>
Let t<sub>i</sub> be a target of rule r<sub>i</sub>, which applies an Aspect a<sub>i</sub>
to its dependencies.
</p>
<p>Assume that a2 generates an action X when applied to target t0. The text output of
<code>bazel aquery --include_aspects 'deps(//t2)'</code> for action X would be:</p>
<pre>
action ...
Mnemonic: ...
Target: //my_pkg:t0
Configuration: ...
AspectDescriptors: [//my_pkg:rule.bzl%<b>a2</b>(foo=...)
-> //my_pkg:rule.bzl%<b>a1</b>(bar=...)]
...
</pre>
<p>
This means that action <code>X</code> was generated by Aspect <code>a2</code> applied onto
<code>a1(t0)</code>, where <code>a1(t0)</code> is the result of Aspect <code>a1</code> applied
onto target <code>t0</code>.
</p>
<p>Each <code>AspectDescriptor</code> has the following format:</p>
<pre>
AspectClass([param=value,...])
</pre>
<p>
<code>AspectClass</code> could be the name of the Aspect class (for native Aspects) or
<code>bzl_file%aspect_name</code> (for Starlark Aspects). <code>AspectDescriptor</code> are
sorted in topological order of the
<a href="https://docs.bazel.build/versions/master/skylark/aspects.html#aspect-basics">dependency graph</a>.
</p>
<h2 id='known-issues'>Known Issues</h2>
<p>
The list of aquery issues/planned features can be found on
<a href="https://github.com/bazelbuild/bazel/labels/team-Performance">GitHub</a>.
</p>
<h2 id='updates'>Updates</h2>
<p>
Aquery is a work in progress, and its API might change in the future.
Please contact twerth@google.com and leba@google.com for any issue/feature request.
</p>