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 関数の使用
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 ビルドの上で実行されるため、ビルド中に使用可能なオプションのセットを継承します。
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
コマンドで使用されるパラメータ ファイルの内容を含めます(サイズが大きい可能性があります)。
--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 のインスタンスに保持する 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")'
クエリ出力の比較
2 つの異なる aquery 呼び出しの出力を比較するには、aquery_differ
ツールを使用します。たとえば、ルール定義に変更を加えて、実行されるコマンドラインが変更されていないことを確認する場合などです。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 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 出力には、アスペクトパスが含まれます。これは、アクションを生成したターゲットに適用されたアスペクトのシーケンスです。
アスペクト オン アスペクトの例:
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
は 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 と混同しないでください。
更新
問題や機能リクエストがある場合は、こちらから問題を報告してください。