建構事件通訊協定 (BEP) 可讓第三方程式深入瞭解 Bazel 叫用。舉例來說,您可以使用 BEP 收集 IDE 外掛程式或顯示建構結果的資訊主頁的資訊。
通訊協定是一組通訊協定緩衝區訊息,在其上方定義一些語意。其中包含建構與測試結果、建構進度、建構設定等相關資訊。BEP 適合以程式輔助方式取用,讓剖析 Bazel 的指令列會輸出過去的內容。
建構事件通訊協定會以事件的形式呈現有關建構的資訊。建構事件是一種通訊協定緩衝區訊息,當中包含建構事件 ID、一組子事件 ID 和酬載。
建構事件 ID:視建構事件種類而定,這個值可能是不透明字串或結構化資訊,進一步說明建構事件。建構事件中的建構事件 ID 是唯一的。
子項:建構事件可能會在子項欄位中加入建構事件 ID,藉此宣告其他建構事件。舉例來說,
PatternExpanded
建構事件會公告其展開為子項的目標。此通訊協定可確保所有事件 (第一個事件除外) 都會透過上一個事件宣布。酬載:酬載包含建構事件的結構化資訊,編碼為該事件專屬的通訊協定緩衝區訊息。請注意,酬載可能不是預期的類型,但如果建構作業提早取消,則可能是
Aborted
訊息。
建立事件圖表
所有建構事件都會透過其父項和子項關係組成有向非循環圖。除了初始建構事件以外,每個建構事件都有一或多個父項事件。請注意,並非所有子項事件的父項事件都必須在事件發生前發布。建構完成時 (成功或失敗),系統就會發布所有公告的事件。如果 Bazel 當機或網路傳輸失敗,系統就可能不會發布某些宣告的建構事件。
事件圖的結構反映了指令的生命週期。每個 BEP 圖表都有下列特性:
- 根事件一律為
BuildStarted
事件。所有其他事件則會是子系。 - BuildStarted 事件的立即子項包含該指令的中繼資料。
- 包含指令產生的資料的事件 (例如建構的檔案和測試結果) 會顯示在
BuildFinished
事件之前。 BuildFinished
事件「可以」後面接著含有建構作業摘要資訊的事件 (例如指標或剖析資料)。
使用建構事件通訊協定
以二進位格式使用
如何以二進位格式使用 BEP:
指定選項
--build_event_binary_file=/path/to/file
,讓 Bazel 將通訊協定緩衝區的訊息序列化為檔案。檔案會包含序列化的通訊協定緩衝區訊息,每則訊息都以長度分隔。每則訊息的前置字串都加上長度編碼為變數長度整數。您可以使用通訊協定緩衝區程式庫的parseDelimitedFrom(InputStream)
方法讀取此格式。接著編寫程式,從序列化的通訊協定緩衝區訊息中擷取相關資訊。
以文字或 JSON 格式使用
下列 Bazel 指令列旗標會以使用者可理解的格式輸出 BEP,例如文字和 JSON:
--build_event_text_file
--build_event_json_file
建構事件服務
建構事件服務通訊協定是發布建構事件的通用 gRPC 服務。建構事件服務通訊協定與 BEP 無關,且會將 BEP 事件視為不透明位元組。Bazel 隨附建構事件服務通訊協定的 gRPC 用戶端實作,該通訊協定會發布 Build Event Protocol 事件。您可以使用 --bes_backend=HOST:PORT
標記,指定要將事件傳送至哪個端點。如果您的後端使用 gRPC,就必須在位址前面加上適當的配置:grpc://
適用於明文 gRPC,grpcs://
適用於已啟用 TLS 的 gRPC。
建構事件服務旗標
Bazel 有多個與 Build Event Service 通訊協定相關的標記,包括:
--bes_backend
--[no]bes_best_effort
--[no]bes_lifecycle_events
--bes_results_url
--bes_timeout
--bes_instance_name
如需每個標記的說明,請參閱指令列參考資料。
驗證與安全性
Bazel 的建構事件服務實作也支援驗證和 TLS。您可使用下列旗標控制這些設定。請注意,這些標記也適用於 Bazel 的 Remote Execution。這表示建構事件服務和遠端執行端點需要共用相同的驗證和傳輸層安全標準 (TLS) 基礎架構。
--[no]google_default_credentials
--google_credentials
--google_auth_scopes
--tls_certificate
--[no]tls_enabled
如需每個標記的說明,請參閱指令列參考資料。
建構事件服務和遠端快取
BEP 通常包含許多在執行 Bazel 的機器上儲存的記錄檔 (test.log、test.xml 等) 參照。遠端 BES 伺服器通常無法存取這些檔案,因為這些檔案位於不同機器。解決這個問題的一個方法是使用 Bazel 搭配遠端快取。Bazel 會將所有輸出檔案上傳至遠端快取 (包括 BEP 中參照的檔案),接著 BES 伺服器就能從快取中擷取參照的檔案。
詳情請參閱 GitHub 問題 3689。