透過指令碼呼叫 Bazel

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

您可以從指令碼呼叫 Bazel,執行建構、測試或查詢相依關係圖。Bazel 的設計目的是提供有效的指令碼功能,但本節列出一些需要留意的細節,以便讓指令碼更健全。

選擇輸出基礎

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

選擇正確的輸出基礎目錄,取決於多項因素。如果您需要將建構輸出內容放在特定位置,系統會根據這個位置決定您需要使用的輸出基礎。如果您向 Bazel 發出「只讀」呼叫 (例如 bazel query),鎖定因素就會更重要。特別是,如果您需要同時執行多個指令碼例項,請注意,每個 Blaze 伺服器程序最多只能處理一次一次的叫用。視情況而定,每個指令碼例項都可能需要等待輪到自己執行,或者您可能需要使用 --output_base 執行多個 Blaze 伺服器並加以使用。

如果您使用預設輸出基底值,就會與使用者互動式 Bazel 指令使用的鎖定機制競爭。如果使用者發出長時間執行的指令 (例如建構),您的指令碼必須等待這些指令完成後才能繼續執行。

伺服器模式的附註

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

我會收到哪個結束代碼?

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

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

  • 0 - 成功
  • 2 - 指令列問題、錯誤或非法旗標或指令組合,或錯誤的環境變數。您必須修改指令列。
  • 8 - 建構作業中斷,但我們已以有序方式關閉作業。
  • 9:伺服器鎖定已保留,且已傳遞 --noblock_for_lock
  • 32 - 外部環境失敗,但不是在本機上。

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

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

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

  • 36 - 本機環境問題,疑似永久性問題。

  • 37 - 未處理的例外狀況 / 內部 Bazel 錯誤。

  • 38 - 將結果發布至建構事件服務時發生暫時性錯誤。

  • 39 - Bazel 所需的 Blob 會從遠端快取中移除。

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

  • 45 - 持續性錯誤,無法將結果發布至建構事件服務。

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

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

指令 bazel buildbazel test 的傳回碼:

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

針對 bazel run

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

針對 bazel query

  • 3 - 部分成功,但在輸入的 BUILD 檔案集中發生 1 個以上的錯誤,因此作業結果不一定可靠。這可能是因為指令列上的 --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 值。

透過分析排解效能問題

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