最佳做法

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

本頁面假設您已熟悉 Bazel,並提供有關建構專案的規範和建議,讓您充分利用 Bazel 的功能。

整體目標如下:

  • 使用精細依附元件,允許平行處理和增量處理。
  • 可確保依附元件妥善封裝。
  • 讓程式碼結構化且易於測試。
  • 建立易於理解及維護的建構設定。

這些規範並非必要條件:少數專案可以遵循所有規定。如 lint 的 man 頁面所述,「如果有人能製作出在嚴格檢查下不會產生錯誤的實際程式,我們會頒發特別獎勵。」不過,盡可能納入這些原則,可讓專案更易讀、更不易發生錯誤,並加快建構速度。

本頁面使用 這份 RFC 所述的規定層級。

執行建構作業和測試

專案應一律能夠在穩定分支中順利執行 bazel build //...bazel test //...。在特定情況下,如果目標是必要的,但未建構 (例如需要特定建構旗標、未在特定平台上建構、需要授權協議),則應盡可能標示為特定目標 (例如「requires-osx」)。這種標記可讓目標以比「手動」標記更精細的層級進行篩選,讓檢查 BUILD 檔案的使用者瞭解目標的限制。

第三方依附元件

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

  • 請在 MODULE.bazel 檔案中將這些 API 宣告為遠端存放區。
  • 或者,您也可以將這些檔案放在工作區目錄下的 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

套件

每個包含可建構檔案的目錄都應為套件。如果 BUILD 檔案參照子目錄中的檔案 (例如 srcs = ["a/b/C.java"]),表示應將 BUILD 檔案新增至該子目錄。這個結構存在的時間越長,就越有可能無意中建立循環依附元件,目標的範圍會逐漸擴大,而且需要更新的反向依附元件數量也會增加。