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))))'
上記のコマンドは、ニーモニックが "Cpp.*"
に一致し、入力がパターン ".*cpp"
と "foo.*"
と一致する //src/target_a
の作成に関連するすべてのアクションを検索します。
生成される構文エラーの例:
$ 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
アクションのマニフェスト ファイルの内容を含めます。ファイルの内容は、file_contents
フィールドに --output=
xxxproto
で返されます。--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 出力の比較
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
上記のコマンドは、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 出力には、アスペクト パスが含まれます。これは、アクションを生成したターゲットに適用されるアスペクトのシーケンスです。
アスペクト オン アスペクトの例:
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 Aspect の場合)です。AspectDescriptor
は、依存関係グラフのトポロジ順に並べられます。
JSON プロファイルとのリンク
クエリは、ビルドで実行されているアクションに関する情報(実行理由、その入出力情報)を提供しますが、JSON プロファイルは実行のタイミングと所要時間を示します。これら 2 つの情報セットは、共通の分母であるアクションのプライマリ出力により組み合わせることができます。
JSON プロファイルにアクションの出力を含めるには、--experimental_include_primary_output --noexperimental_slim_json_profile
を使用してプロファイルを生成します。スリム プロファイルには、プライマリ出力を含めることができません。アクションのプライマリ出力は、デフォルトでクエリによって含まれます。
現時点では、これら 2 つのデータソースを組み合わせる正規のツールは提供していませんが、上記の情報を使用して独自のスクリプトを作成することは可能です。
既知の問題
共有アクションの処理
アクションは、構成されたターゲット間で共有される場合があります。
実行フェーズでは、これらの共有アクションは単に 1 つと見なされ、1 回だけ実行されます。ただし、クエリは実行前、分析後のアクション グラフを操作するため、出力アーティファクトの 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 と混同しないでください。
更新
問題や機能リクエストについては、こちらから問題を報告してください。