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 つの 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))
オプション
ビルド オプション
aquery
は通常の Bazel ビルドの上で実行されるため、ビルド中に使用可能なオプションのセットを継承します。
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
アスペクトによって生成されたアクションを出力に含めるかどうか。
--include_param_files, default=false
コマンドで使用される param ファイルの内容(大規模な場合もあります)を含めます。
--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 サーバーの各インスタンスで、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
を作成するため)とターゲットを渡しています。ただし、Chronicle で
以前にビルドされたターゲットは 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_differ
ツールを使用すると、2 つの異なる 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
上記のコマンドは、aquery クエリ出力の before
と after
の差を返します。
あるアクションと含まれていないアクション、それぞれのアクションに違いがある
各 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
: アクションの属性
定義します。
アスペクト オン アスペクト
アスペクトを重ねて適用できます。生成されたアクションの aquery 出力は、 これらのアスペクトには、アスペクト パスが含まれます。これは、 アクションを生成したターゲットに適用されるアスペクト。
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
が、a1(t0)
に適用されたアスペクト a2
によって生成されたことを意味します。ここで、a1(t0)
は、ターゲット t0
に適用されたアスペクト a1
の結果です。
各 AspectDescriptor
の形式は次のとおりです。
AspectClass([param=value,...])
AspectClass
は、Aspect クラスの名前(ネイティブ Aspect の場合)または bzl_file%aspect_name
(Starlark Aspect の場合)にできます。AspectDescriptor
は、依存関係グラフのトポロジ順に並べ替えられます。
JSON プロファイルとのリンク
クエリは、ビルドで実行されるアクション(実行される理由、入力 / 出力)に関する情報を提供しますが、JSON プロファイルは、実行のタイミングと実行時間に関する情報を提供します。アクションのプライマリ出力という共通要素によって、この 2 セットの情報を組み合わせることができます。
アクションの出力を JSON プロファイルに含めるには、--experimental_include_primary_output --noexperimental_slim_json_profile
を使用してプロファイルを生成します。スリム プロファイルは、プライマリ出力の追加に対応していません。アクションのメイン出力は、デフォルトでクエリに含まれます。
現在、これら 2 つのデータソースを組み合わせる標準的なツールは提供していませんが、 上記の情報で独自のスクリプトを作成できることです。
既知の問題
共有アクションの処理
アクションは、構成されたターゲット間で共有される場合があります。
実行フェーズでは、これらの共有アクションは単純に 1 つと見なされ、1 回だけ実行されます。ただし、クエリは実行前、分析後のアクション グラフで動作するため、これらのアクションは
たとえば、出力アーティファクトの execPath
がまったく同じである個別のアクションなどです。その結果
重複しているように見えます。
Aquery の問題とリリース予定の機能のリストは次の場所にあります: GitHub。
よくある質問
入力ファイルの内容が変更されても、ActionKey は同じです。
クエリのコンテキストで、ActionKey
は、以下から取得された String
を指します。
ActionAnalysisMetadata#getKey:
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 と混同しないでください。
更新
問題や機能のリクエストについては、こちらから問題を報告してください。