BazelCon 2024 登録の受け付けを開始しました。

このページは Cloud Translation API によって翻訳されました。

アクショングラフクエリ（aquery）

<ph type="x-smartling-placeholder"></ph> 問題を報告するソースを表示夜間 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

t_i をルール r_i のターゲットとし、アスペクト a_i を適用する。依存関係に追加します。

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 --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。

アクション グラフ クエリ（aquery）

基本的な構文

aquery 関数の使用

オプション

ビルド オプション

Aquery のオプション

--output=(text|summary|proto|jsonproto|textproto), default=text

--include_commandline, default=true

--include_artifacts, default=true

--include_aspects, default=true

--include_param_files, default=false

--include_file_write_contents, default=false

--skyframe_state, default=false