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

ビルドイベントプロトコルの例

Build Event Protocol の完全な仕様については、プロトコルバッファの定義をご覧ください。ただし、仕様を確認する前にある程度の知識を身に付けておくと役に立つ場合もあります。

2 つの空のシェルスクリプト foo.sh と foo_test.sh と、次の BUILD ファイルで構成される、シンプルな Bazel ワークスペースについて考えてみましょう。

sh_library(
    name = "foo_lib",
    srcs = ["foo.sh"],
)

sh_test(
    name = "foo_test",
    srcs = ["foo_test.sh"],
    deps = [":foo_lib"],
)

このプロジェクトで bazel test ... を実行すると、生成されるビルドイベントのビルドグラフは、以下のグラフのようになります。矢印は前述の親子関係を示しています簡略化のために、一部のビルドイベントとほとんどのフィールドは省略されています。

ベップグラフ

図 1. BEP グラフ。

最初に BuildStarted イベントがパブリッシュされます。このイベントは、bazel test コマンドを介してビルドが呼び出されたことを通知し、子イベントを通知します。

OptionsParsed
WorkspaceStatus
CommandLine
UnstructuredCommandLine
BuildMetadata
BuildFinished
PatternExpanded
Progress

最初の 3 つのイベントは、Bazel の呼び出し方法に関する情報を提供します。

PatternExpanded ビルドイベントは、... パターンが拡張されたターゲット //foo:foo_lib と //foo:foo_test に関する分析情報を提供します。そのためには、2 つの TargetConfigured イベントを子として宣言します。TargetConfigured イベントの前に Configuration がポストされている場合でも、TargetConfigured イベントは Configuration イベントを子イベントとして宣言します。

親子関係だけでなく、各イベントはビルドイベント ID を使用して互いに参照することもできます。たとえば、上のグラフでは、TargetComplete イベントは fileSets フィールドの NamedSetOfFiles イベントを参照しています。

通常、ファイルを参照するビルドイベントでは、イベントにファイル名とパスが埋め込まれることはありません。代わりに、NamedSetOfFiles イベントのビルドイベント識別子が含まれ、その後に実際のファイル名とパスが含まれます。NamedSetOfFiles イベントを使用すると、一連のファイルを 1 回報告し、多くのターゲットから参照できます。この構造が必要なのは、Build Event Protocol の出力サイズが、ファイル数に比例して 2 乗に増加することがあるためです。NamedSetOfFiles イベントにすべてのファイルが埋め込まれているわけではなく、ビルドイベント識別子を介して他の NamedSetOfFiles イベントを参照することもできます。

以下は、上記のグラフの //foo:foo_lib ターゲットの TargetComplete イベントで、プロトコルバッファの JSON 表現で出力されたインスタンスです。ビルドイベント ID にはターゲットが不透明な文字列として含まれ、ビルドイベント ID を使用して Configuration イベントを参照します。このイベントは子イベントを通知しません。ペイロードには、ターゲットが正常にビルドされたかどうか、出力ファイルのセット、ビルドされたターゲットの種類に関する情報が含まれています。

{
  "id": {
    "targetCompleted": {
      "label": "//foo:foo_lib",
      "configuration": {
        "id": "544e39a7f0abdb3efdd29d675a48bc6a"
      }
    }
  },
  "completed": {
    "success": true,
    "outputGroup": [{
      "name": "default",
      "fileSets": [{
        "id": "0"
      }]
    }],
    "targetKind": "sh_library rule"
  }
}

BEP での Aspect 結果

通常のビルドは、(target, configuration) ペアに関連付けられたアクションを評価します。アスペクトを有効にしてビルドする場合、Bazel は、特定の有効なアスペクトの影響を受けるターゲットごとに、(target, configuration, aspect) トリプルに関連付けられたターゲットを追加で評価します。

アスペクト固有のイベントタイプがない場合でも、BEP でアスペクトの評価結果を確認できます。該当するアスペクトを持つ (target, configuration) ペアごとに、Bazel は、そのアスペクトをターゲットに適用した結果を格納する TargetConfigured イベントと TargetComplete イベントを追加で発行します。たとえば、//:foo_lib が --aspects=aspects/myaspect.bzl%custom_aspect でビルドされている場合、次のイベントも BEP に表示されます。

{
  "id": {
    "targetCompleted": {
      "label": "//foo:foo_lib",
      "configuration": {
        "id": "544e39a7f0abdb3efdd29d675a48bc6a"
      },
      "aspect": "aspects/myaspect.bzl%custom_aspect"
    }
  },
  "completed": {
    "success": true,
    "outputGroup": [{
      "name": "default",
      "fileSets": [{
        "id": "1"
      }]
    }]
  }
}

`NamedSetOfFiles` の消費

特定のターゲット（またはアスペクト）によって生成されたアーティファクトを特定することは、いくつかの準備により効率的に実行できる BEP の一般的なユースケースです。このセクションでは、NamedSetOfFiles イベントによって提供される再帰の共有構造について説明します。これは、Starlark の Depset の構造と一致します。

コンシューマーは、NamedSetOfFiles イベントの処理時に二次アルゴリズムを避けるように注意する必要があります。大規模なビルドには数万ものイベントが含まれる可能性があり、二次複雑性による走査では数億のオペレーションが必要になるためです。

namesetoffiles-bep-graph

図 2. NamedSetOfFiles BEP グラフ。

NamedSetOfFiles イベントは、常に BEP ストリーム内でそれを参照する TargetComplete イベントまたは NamedSetOfFiles イベントの前に表示されます。これは、イベント（親子）の関係とは逆で、少なくとも 1 つのイベントがそれを通知するイベントが、最初のイベントを除くすべてのイベントが発生します。NamedSetOfFiles イベントは、セマンティクスのない Progress イベントによって通知されます。

順序と共有の制約があるため、一般的なコンシューマーは BEP ストリームがなくなるまですべての NamedSetOfFiles イベントをバッファリングする必要があります。次の JSON イベントストリームと Python コードは、「デフォルト」の出力グループのターゲット/アスペクトからビルドアーティファクトへのマップの入力方法と、ビルドされたターゲット/アスペクトのサブセットの出力を処理する方法を示しています。

named_sets = {}  # type: dict[str, NamedSetOfFiles]
outputs = {}     # type: dict[str, dict[str, set[str]]]

for event in stream:
  kind = event.id.WhichOneof("id")
  if kind == "named_set":
    named_sets[event.id.named_set.id] = event.named_set_of_files
  elif kind == "target_completed":
    tc = event.id.target_completed
    target_id = (tc.label, tc.configuration.id, tc.aspect)
    outputs[target_id] = {}
    for group in event.completed.output_group:
      outputs[target_id][group.name] = {fs.id for fs in group.file_sets}

for result_id in relevant_subset(outputs.keys()):
  visit = outputs[result_id].get("default", [])
  seen_sets = set(visit)
  while visit:
    set_name = visit.pop()
    s = named_sets[set_name]
    for f in s.files:
      process_file(result_id, f)
    for fs in s.file_sets:
      if fs.id not in seen_sets:
        visit.add(fs.id)
        seen_sets.add(fs.id)

ビルド イベント プロトコルの例

BEP での Aspect 結果

NamedSetOfFiles の消費

ビルドイベントプロトコルの例

`NamedSetOfFiles` の消費