最佳做法

回報問題 查看來源

本頁面假設您已熟悉 Bazel,並提供指南與建議,協助您建構專案,以便充分運用 Bazel 的功能。

整體目標如下:

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

這些規範並非必要條件:少數專案可以遵循所有規定。如同 Lint 的主頁面所說:「一項特殊獎勵將提供給第一位使用嚴格檢查,不產生任何錯誤的真正程式的使用者。」不過,要盡量整合這些原則,可使專案更容易閱讀、較不容易出錯,以及建構速度更快。

本頁面採用此 RFC 中所述要求層級。

執行建構和測試

專案應一律能在其穩定的分支版本中成功執行 bazel build //...bazel test //...。對於某些必要但在特定情況下不建構的目標 (例如需要特定建構旗標、不在特定平台上建構、需要授權協議),請盡可能明確標記目標 (例如「requires-osx」)。此標記可讓目標以比「手動」標記更精細的層級篩選,並讓使用者透過檢查 BUILD 檔案瞭解目標的限制。

第三方依附元件

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

  • 請在 WORKSPACE 檔案中將這些 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

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

套件

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