最佳做法

回報問題 查看原始碼

本頁面假設您已熟悉 Bazel,並且提供了指南與建議架構,讓您充分運用 Bazel 的功能。

整體目標為:

  • 使用精細的依附元件來允許平行處理和漸進式工作。
  • 為了保持依附元件的封裝。
  • 確保程式碼結構良好且可供測試。
  • 建立容易理解及維護的建構設定。

這些指南並非必要條件:只有少數專案能夠遵守所有專案。就像 Lint 的頁面說:「將獲得第一項獎勵給第一位負責產生實際錯誤的真人,而且不會因為嚴密的檢查而產生錯誤。」但是,要盡可能納入這些原則,則應該讓專案更易讀、減少錯誤,並且加快建構速度。

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

執行建構與測試

專案應一律在其穩定分支版本上執行 bazel build //...bazel test //...。必須能在特定情況下 (而非要求特定建構標記,不在特定平台上建構、需取得授權協議) 建構,但應盡可能加上標記 (例如「requires-osx」)。這類標記可讓目標精細地篩選。

第三方依附元件

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

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

視二進位檔而定

請盡可能從來源建立所有內容。一般而言,這意味著,您不需要依附程式庫 some-library.so,而是建立 BUILD 檔案,並從其來源建構 some-library.so,然後依附於該目標。

一律從原始碼進行建構可確保建構作業不會使用以不相容旗標或不同架構建構的程式庫。此外,部分功能也適用範圍,例如涵蓋率、靜態分析或動態分析,且僅支援來源。

版本管理

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

使用 .bazelrc 檔案

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

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

try-import %workspace%/user.bazelrc

(或任何其他檔案名稱) workspace/.bazelrc 並將 user.bazelrc 新增到 .gitignore

包裹

每個包含可建構檔案的目錄都是套件。如果 BUILD 檔案參照子目錄中的檔案 (例如 srcs = ["a/b/C.java"]),則表示 BUILD 檔案應新增至該子目錄。此結構的存在時間越長,就越有可能意外建立循環依附元件、目標的範圍會不斷增加,而必須增加越來越多的反向依附元件。