本頁面假設您已熟悉 Bazel,並提供專案架構的相關指南和建議,協助您充分運用 Bazel 的功能。
整體目標如下:
- 使用精細依附元件,允許平行處理和增量。
- 確保依附元件受到妥善封裝。
- 讓程式碼結構完整且可測試。
- 建立容易瞭解及維護的建構設定。
這些規範並非必要條件,因為很少有專案能完全遵守。如 lint 的說明頁面所述,「如果有人能製作出一個程式,在嚴格檢查下不會產生任何錯誤,將可獲得特別獎勵」。不過,盡可能納入這些原則,應可讓專案更容易閱讀、減少錯誤,並加快建構速度。
本頁面使用這份 RFC 中說明的需求等級。
執行建構作業和測試
專案應一律能在穩定分支上順利執行 bazel build //...
和 bazel test //...
。如果目標是必要項目,但在特定情況下不會建構 (例如需要特定建構旗標、不會在特定平台上建構,或需要授權協議),則應盡可能加上具體標記 (例如「requires-osx
」)。與「手動」標記相比,這類標記可讓目標在更精細的層級進行篩選,並讓檢查 BUILD
檔案的人員瞭解目標的限制。
第三方依附元件
您可以宣告第三方依附元件:
- 您可以在
MODULE.bazel
檔案中將其宣告為遠端存放區。 - 或者,將這些檔案放在工作區目錄下的
third_party/
目錄中。
視二進位檔而定
盡可能從來源建構所有內容。一般來說,這表示您會建立 BUILD
檔案並從其來源建構 some-library.so
,然後依附於該目標,而不是依附於 some-library.so
程式庫。
一律從來源建構可確保建構作業不會使用以不相容的標記或不同架構建構的程式庫。此外,有些功能 (例如涵蓋範圍、靜態分析或動態分析) 只能在來源上運作。
版本管理
請盡可能從 HEAD 建構所有程式碼。如必須使用版本,請避免在目標名稱中加入版本 (例如 //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
開放原始碼的 bazelrc-preset.bzl{: .external} 會產生符合 Bazel 版本的自訂 bazelrc 檔案,並提供建議標記的預設設定。
套件
含有可建構檔案的每個目錄都應是套件。如果 BUILD
檔案參照子目錄中的檔案 (例如 srcs = ["a/b/C.java"]
),表示應將 BUILD
檔案新增至該子目錄。這個結構存在越久,就越可能不慎建立循環依附元件、目標範圍會逐漸擴大,且必須更新的反向依附元件數量也會增加。