BazelCon 2025 の登録と CFP が開始されました。

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

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

問題を報告するソースを表示 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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|commands|proto|jsonproto|textproto), default=text`

デフォルトの出力形式（text）は人間が読める形式です。マシンが読み取れる形式の場合は、proto、textproto、または jsonproto を使用します。proto メッセージは analysis.ActionGraphContainer です。

commands 出力形式では、1 行に 1 つのコマンドを含むビルドコマンドのリストが出力されます。

一般に、出力の順序に依存しないでください。詳細については、コアクエリの順序付け契約をご覧ください。

`--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 出力でコマンドライン/入力が異なるアクションなど）。上記のコマンドを実行すると、次のような結果が得られます。

  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

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 が、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 --noslim_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 と混同しないでください。

アップデート

問題や機能のリクエストについては、こちらから問題を報告してください。