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
イベントのビルドイベント ID が含まれます。この ID には、実際のファイル名とパスが含まれます。NamedSetOfFiles
イベントを使用すると、一連のファイルを 1 回報告し、多くのターゲットから参照できます。この構造は、Build Event Protocol の出力サイズがファイル数に比例して二次的に増加する可能性があるため必要です。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 のアスペクトの結果
通常のビルドでは、(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
イベントを処理する際には二次元アルゴリズムを避ける必要があります。二次元アルゴリズムでは、二次元の複雑さのトレース中に数億のオペレーションが必要になります。
図 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)