透過指令碼呼叫 Bazel

回報問題 查看來源 Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

您可以從指令碼呼叫 Bazel,執行建構、測試或查詢依附元件圖。Bazel 的設計宗旨是實現有效的指令碼編寫,但本節列出了一些注意事項,可協助您編寫更強大的指令碼。

選擇輸出基礎

--output_base 選項可控管 Bazel 程序應將建構輸出內容寫入何處,以及 Bazel 內部使用的各種工作檔案,其中一個是鎖定,可防止多個 Bazel 程序同時變更輸出內容基礎。

為指令碼選擇正確的輸出基本目錄時,需要考量多項因素。如需將建構輸出內容放在特定位置,這會決定您需要使用的輸出內容基礎。如果您要對 Bazel 進行「唯讀」呼叫 (例如 bazel query),鎖定因素就更重要。特別是如果需要同時執行多個指令碼執行個體,則必須為每個執行個體提供不同的 (或隨機) 輸出基準。

如果您使用預設輸出基本值,就會與使用者互動式 Bazel 指令使用的鎖定項目競爭。如果使用者發出建構等長時間執行的指令,指令完成後,指令碼才能繼續執行。

伺服器模式注意事項

根據預設,Bazel 會使用長時間執行的伺服器程序做為最佳化方式。在指令碼中執行 Bazel 時,請務必在伺服器完成工作後呼叫 shutdown,或指定 --max_idle_secs=5,讓閒置伺服器立即關閉。

我會取得哪個結束代碼?

Bazel 會嘗試區分因考量中的原始碼而導致的失敗,以及導致 Bazel 無法正常執行的外部錯誤。Bazel 執行作業可能會產生下列結束程式碼:

所有指令通用的結束代碼:

  • 0 - 成功
  • 2 - 指令列問題、旗標或指令組合有誤或違法,或是環境變數有誤。您必須修改指令列。
  • 8 - 建構作業已中斷,但我們已透過有序關機終止作業。
  • 9 - 伺服器鎖定已保留,且已傳遞 --noblock_for_lock
  • 32 - External Environment Failure not on this machine.

  • 33 - Bazel 記憶體不足而當機。您需要修改指令列。

  • 34 - 保留供 Google 內部使用。

  • 35 - 保留供 Google 內部使用。

  • 36 - Local Environmental Issue, suspected permanent.

  • 37 - Unhandled Exception / Internal Bazel Error.

  • 38 - 保留供 Google 內部使用。

  • 39 - Bazel 要求的 Blob 會從遠端快取中逐出。

  • 41-44 - 保留供 Google 內部使用。

  • 45 - Error publishing results to the Build Event Service.

  • 47 - 保留供 Google 內部使用。

指令 bazel buildbazel test 的回傳代碼:

  • 1:建構失敗。
  • 3 - 建構作業正常,但部分測試失敗或逾時。
  • 4 - 建構成功,但即使要求測試,系統仍找不到任何測試。

適用於 bazel run

  • 1:建構失敗。
  • 如果建構成功,但執行的子程序傳回非零的結束代碼,則該代碼也會是指令的結束代碼。

適用於 bazel query

  • 3 - 部分成功,但查詢在輸入 BUILD 檔案集時發生一或多個錯誤,因此作業結果並非 100% 可靠。這可能是因為指令列中的 --keep_going 選項所致。
  • 7 - 指令失敗。

日後的 Bazel 版本可能會新增其他結束代碼,以具有特定意義的不同非零值,取代一般失敗結束代碼 1。不過,所有非零的結束值一律會構成錯誤。

讀取 .bazelrc 檔案

根據預設,Bazel 會從基本工作區目錄或使用者的主目錄讀取 .bazelrc 檔案。是否要這麼做取決於指令碼;如果指令碼必須完全密封 (例如執行發布建構作業時),您應使用 --bazelrc=/dev/null 選項停用讀取 .bazelrc 檔案。如要使用使用者的偏好設定執行建構作業,建議採用預設行為。

指令記錄

您也可以在指令記錄檔中查看 Bazel 輸出內容,方法是執行下列指令:

bazel info command_log

指令記錄檔包含最新 Bazel 指令的交錯 stdout 和 stderr 串流。請注意,執行 bazel info 會覆寫這個檔案的內容,因為這會成為最新的 Bazel 指令。不過,除非變更 --output_base--output_user_root 選項的設定,否則指令記錄檔的位置不會變更。

剖析輸出內容

Bazel 輸出內容相當容易剖析,適用於許多用途。有兩個選項可能對指令碼有幫助:--noshow_progress 會抑制進度訊息,而 --show_result n 則會控制是否列印「build up-to-date」訊息;這些訊息可能會經過剖析,以找出成功建構的目標,以及所建立輸出檔案的位置。如果您依賴這些訊息,請務必指定非常大的 n 值。

透過剖析排解效能問題

請參閱「效能分析」一節。