建構事件通訊協定範例

回報問題查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

您可以在通訊協定緩衝區定義中找到 Build Event Protocol 的完整規格。不過，在查看規格之前，先建立一些直覺概念可能會有所幫助。

請考慮一個簡單的 Bazel 工作區，其中包含兩個空白的殼層指令碼 foo.sh 和 foo_test.sh，以及下列 BUILD 檔案：

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

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

在這個專案上執行 bazel test ... 時，產生的建構事件建構圖會類似下方的圖表。箭頭代表上述父項和子項關係。請注意，為求簡潔，系統會省略部分建構事件和大部分欄位。

bep-graph

圖 1. 業務效率評估圖表。

一開始，系統會發布 BuildStarted 事件。這項事件會告知我們，建構作業是透過 bazel test 指令叫用，並宣告子事件：

OptionsParsed
WorkspaceStatus
CommandLine
UnstructuredCommandLine
BuildMetadata
BuildFinished
PatternExpanded
Progress

前三個事件會提供 Bazel 的叫用方式相關資訊。

PatternExpanded 建構事件可深入分析 ... 模式擴展至 //foo:foo_lib 和 //foo:foo_test 的特定目標。方法是將兩個 TargetConfigured 事件宣告為子項。請注意，即使 Configuration 已在 TargetConfigured 事件之前發布，TargetConfigured 事件仍會將 Configuration 事件宣告為子項事件。

除了父項和子項關係之外，事件也可以使用建構事件 ID 參照彼此。舉例來說，在上述圖表中，TargetComplete 事件會參照其 fileSets 欄位的 NamedSetOfFiles 事件。

參照檔案的建構事件通常不會在事件中嵌入檔案名稱和路徑。而是包含 NamedSetOfFiles 事件的建構事件 ID，該 ID 會包含實際的檔案名稱和路徑。NamedSetOfFiles 事件允許一組檔案回報一次，並由多個目標參照。這個結構是必要的，因為在某些情況下，Build Event Protocol 輸出大小會隨著檔案數量以平方方式成長。NamedSetOfFiles 事件也可能不會內嵌所有的檔案，而會改為透過建構事件 ID 參照其他 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) 組合相關聯的動作。在啟用 aspects 的情況下進行建構時，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 事件時，必須小心避免二次方演算法，因為大型版本可能包含數萬個這類事件，需要在二次方複雜度的遍歷中執行數億次作業。

namedsetoffiles-bep-graph

圖 2. NamedSetOfFiles 邊際利潤率圖。

NamedSetOfFiles 事件一律會在 BEP 串流中前置參照該事件的 TargetComplete 或 NamedSetOfFiles 事件。這與「父項/子項」事件關係相反，其中第一個事件以外的所有事件都會在至少一個通知該事件後出現。NamedSetOfFiles 事件是由 Progress 事件宣告，且沒有語意。

考慮到這些排序和共用限制，一般取用端必須緩衝所有 NamedSetOfFiles 事件，直到 BEP 串流用盡為止。下列 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 中的顯示比例結果

使用 NamedSetOfFiles

使用 `NamedSetOfFiles`