本頁假設您已熟悉 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
新增至 .gitignore
。workspace/.bazelrc
套裝組合
包含可建構檔案的每個目錄都必須是套件。如果 BUILD
檔案參照子目錄 (例如 srcs = ["a/b/C.java"]
) 中的檔案,就表示應將該 BUILD
檔案新增至該子目錄。這個結構越長,就越有可能不小心建立循環依附元件,目標的範圍也會越完善,而反向依附元件的數量也會不斷增加。