aquery コマンドを使用すると、ビルドグラフ内のアクションをクエリできます。分析後の構成済みターゲット グラフで動作し、アクション、アーティファクト、それらの関係に関する情報を公開します。
aquery は、構成されたターゲット グラフから生成されたアクション/アーティファクトのプロパティを知りたい場合に便利です。たとえば、実際のコマンドが実行され、入力/出力/略語が表示されます。
このツールは、いくつかのコマンドライン オプションを受け入れます。特に、aquery コマンドは通常の Bazel ビルド上で実行され、ビルド時に使用可能な一連のオプションを継承します。
従来の 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 関数には次の 3 つがあります。
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))
オプション
ビルド オプション
aquery は通常の Bazel ビルドで実行されるため、ビルド時に使用可能な一連のオプションを継承します。
クエリ オプション
--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
出力にアスペクトで生成されたアクションを含めるかどうか。
--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 でアクション グラフをクエリすると便利です。ユースケースの例を次に示します。
bazel build //target_aを実行します。bazel build //target_bを実行します。- ファイル
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 のインスタンスに保存するアクション グラフのコンテンツを取得し、分析フェーズを再実行せずにフィルタリングを行い、コンテンツを出力します。
特記事項
出力形式
--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_differ ツールを使用すると、2 つの異なるクエリ呼び出しの出力を比較できます。たとえば、ルールの定義にいくつか変更を加えて、実行中のコマンドラインが変更されていないことを確認する場合などです。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 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: 比較するクエリ出力ファイル
--input_type=(proto|text_proto), default=proto: 入力ファイルの形式。proto と textproto のクエリ出力がサポートされます。
--attrs=(cmdline|inputs), default=cmdline: 比較するアクションの属性。
アスペクト
Aspect は互いに適用されます。これらのアスペクトによって生成されるアクションのクエリ出力には、アクションを生成したターゲットに適用されるアスペクトのシーケンスであるアスペクトのパスが含まれます。
Aspect-on-Aspect の例:
t0 ^ | <- a1 t1 ^ | <- a2 t2
ti をルール ri のターゲットとし、aspect 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 は、a1(t0) に適用されたアスペクト a2 によって生成されました。a1(t0) は、ターゲット t0 に適用されたアスペクト a1 の結果です。
各 AspectDescriptor の形式は次のとおりです。
AspectClass([param=value,...])
AspectClass は、Aspect クラスの名前（ネイティブ アスペクトの場合）または bzl_file%aspect_name（Starlark アスペクトの場合）になります。AspectDescriptor は、依存関係グラフのトポロジ順で並べ替えられます。
JSON プロファイルとのリンク
aquery は、ビルドで実行されているアクション（アクションが実行されている理由、入力と出力）の情報を提供しますが、JSON プロファイルは実行のタイミングと時間を示しています。これら 2 つの情報セットは、共通項（アクションの主出力）によって結合できます。
アクションの出力を JSON プロファイルに含めるには、--experimental_include_primary_output --noexperimental_slim_json_profile を使用してプロファイルを生成します。スリムなプロファイルは、プライマリ出力を含めることができません。デフォルトでは、アクションのプライマリ出力はクエリに含まれます。
現在のところ、この 2 つのデータソースを組み合わせた正規のツールはありませんが、上記の情報を使用して独自のスクリプトを作成することは可能です。
既知の問題
共有アクションの処理
構成されたターゲット間でアクションが共有される場合があります。
実行フェーズでは、共有アクションは 1 つとみなされ、1 回だけ実行されます。ただし、aquery は実行前、分析後のアクション グラフで動作するため、出力アーティファクトがまったく同じ execPath を持つ別々のアクションとして扱われます。そのため、同等のアーティファクトは複製されます。
クエリの問題と予定されている機能の一覧については、GitHub をご覧ください。
よくある質問
入力ファイルの内容が変更されても、ActionKey は変わりません。
クエリのコンテキストでは、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 と混同されることはありません。
アップデート
問題や機能リクエストがある場合は、こちらから問題を報告してください。