最佳做法

本頁假設您已熟悉 Bazel,並提供建構專案的相關指引和建議,協助您充分運用 Bazel 的功能。

整體目標如下:

  • 使用精細的依附元件允許平行處理和成效增幅。
  • 讓依附元件完整封裝。
  • 讓程式碼結構良好且可供測試。
  • 建立易於理解及維護的建構設定。

這些規範並非必要條件:少數專案應符合所有規定。正如 Lint 的手冊所示:「特殊獎勵將提供給第一位產生真實的程式,而無需嚴格檢查。」不過,盡可能納入這些原則,應該讓專案更易讀、較不容易出錯,以及加快建構速度。

本頁面使用這個 RFC 中所述的要求等級。

執行建構和測試

專案應一律能夠在其穩定分支版本上執行 bazel build //...bazel test //...。您必須盡可能明確標記必要目標,但在某些情況下無法建構的目標 (例如需要特定的建構旗標、無法在特定平台上建構、需要授權協議)。這個標記可讓系統以比「手動」標記更精細的程度來篩選目標,並讓他人查看 BUILD 檔案瞭解目標的限制。requires-osx

第三方依附元件

您可以宣告第三方依附元件:

  • WORKSPACE 檔案中將這些 SDK 宣告為遠端存放區。
  • 或在工作區目錄下,將這些檔案放在名為 third_party/ 的目錄中。

視二進位檔而定

所有內容都應該盡可能以來源為基礎。一般來說,這表示您可以建立 BUILD 檔案並從其來源建構 some-library.so,然後依附於該目標,而非依附程式庫 some-library.so

一律透過原始碼建構,可確保建構作業不會使用以不相容的標記或不同架構建構的程式庫。此外,涵蓋率、靜態分析或動態分析等部分功能僅適用於來源。

版本管理

建議您盡可能從頭建構所有程式碼。必須使用版本時,請避免在目標名稱中加入版本 (例如 //guava,而非 //guava-20.0)。這個命名可讓程式庫更容易更新 (只需更新一個目標)。在菱形依附元件問題方面,這也更具彈性:如果一個程式庫依附於 guava-19.0,而其中一個程式庫依附於 guava-20.0,則可能會產生嘗試依附兩個不同版本的程式庫。如果您建立了誤導性的別名,將兩個目標指向一個 guava 程式庫,則 BUILD 檔案會誤導使用者。

使用 .bazelrc 檔案

如需專案專屬的選項,請使用 workspace/.bazelrc 設定檔 (請參閱 bazelrc 格式)。

如果您想針對「不想」檢查來源控制的專案支援每位使用者的選項,請加入以下這一行:

try-import %workspace%/user.bazelrc

(或任何其他檔案名稱),並將 user.bazelrc 新增至 .gitignoreworkspace/.bazelrc

套裝組合

包含可建構檔案的每個目錄都必須是套件。如果 BUILD 檔案參照子目錄 (例如 srcs = ["a/b/C.java"]) 中的檔案,就表示應將該 BUILD 檔案新增至該子目錄。這個結構越長,就越有可能不小心建立循環依附元件,目標的範圍也會越完善,而反向依附元件的數量也會不斷增加。