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
Aspect で生成されたアクションを出力に含めるかどうか。
--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 のインスタンス上に保持し、(必要に応じて)そのインスタンスでフィルタリングを実行して、
は、分析フェーズを再実行せずに内容を出力します。
特記事項
出力形式
--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
: アクションの属性
指定します。
アスペクト オン アスペクト
アスペクトは 2 つのオプションがあります生成されたアクションの 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
がアスペクト a2
によって生成され、適用されたことを意味します
a1(t0)
(a1(t0)
は適用されたアスペクト a1
の結果)
ターゲット t0
に入ります。
各 AspectDescriptor
の形式は次のとおりです。
AspectClass([param=value,...])
AspectClass
は、Aspect クラスの名前(ネイティブ アスペクトの場合)または
bzl_file%aspect_name
(Starlark アスペクトの場合)。AspectDescriptor
は
時系列のトポロジで並べ替えて
依存関係グラフ。
JSON プロファイルとのリンク
クエリは、ビルドで実行されているアクションに関する情報(実行する理由、 その入力/出力)、JSON プロファイル 実行のタイミングと期間がわかります。 アクションのプライマリ出力という共通要素によって、この 2 セットの情報を組み合わせることができます。
アクションを含めるその変数を JSON プロファイルで宣言し、
--experimental_include_primary_output --noslim_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。
最新情報
問題や機能リクエストがある場合は、こちらから問題を報告してください。