建構樣式指南

回報問題 查看原始碼 夜間 7.2 7.1 7.0 6.5 6.4

BUILD 檔案格式與 Go 相同，因此需要標準化 可處理大部分的格式問題 建構工具是可以剖析及 會以標準樣式發出原始碼。因此，每個 BUILD 檔案 以相同的方式自動設定格式，在問題期間 審查流程還能讓各項工具更容易理解、編輯 可產生 BUILD 檔案。

BUILD 檔案格式必須與 buildifier 的輸出內容相符。

格式設定範例

# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)

檔案結構

建議：請使用下列順序 (每項元素皆為選用)：

  • 套件說明 (備註)

  • 所有 load() 陳述式

  • package() 函式。

  • 對規則和巨集的呼叫

建立工具會區分獨立註解和註解 某個元素會自動附加在元素上如果註解未附加至特定元素，請使用 後面多加一行空白程式碼如要自動執行自動化作業 變更 (例如：在刪除規則時保留或移除註解)。

# Standalone comment (such as to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")

參照目前套件中的目標

應以相對於套件目錄的路徑參照檔案 (不使用 .. 等向上參照)。 前置字串為「:」表示這些並非來源。來源檔案 開頭不得為 :。規則的開頭應為 :。適用對象 例如，假設 x.cc 是來源檔案：

cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)

目標命名

目標名稱應為描述性名稱。如果目標包含一個來源檔案 目標通常應具有源自該來源的名稱 (例如 chat.cc 的 cc_library 可以是 chat，也可以是 java_library DirectMessage.java 的名稱可能是 direct_message)。

套件的匿名目標 (名稱與 包含目錄) 提供的功能， 目錄名稱。如果沒有這類目標，請勿建立匿名化 目標。

在提及匿名目標時優先使用簡稱 (//x) 而不是 //x:x)。如果您位於相同套件中，請使用本機 參照 (:x，而非 //x)。

避免使用「預留」但是指定目標名稱具有特殊意義。這包括 all、__pkg__ 和 __subpackages__，這些名稱有特殊 語意，且可能會在使用時造成混淆和非預期的行為。

相較於主要的團隊慣例，這些慣例有些不具約束力 Google 廣泛採用的建議：

  • 一般來說，請使用 "snake_case"
    • 對於具有 src 的 java_library，這表示使用的名稱不是 與不含副檔名的檔案名稱相同
    • 如果是 Java *_binary 和 *_test 規則，請使用 「Upper CamelCase」。 這樣一來，目標名稱就能與其中一個 src 比對。適用對象 java_test，如此一來，test_class 屬性即可能 從目標名稱推斷得出
  • 如果特定目標有多個變化版本，請在 釐清 (例如:foo_dev、:foo_prod或:bar_x86、:bar_x64)
  • 使用 _test、_unittest、Test 或 Tests 後後置字串 _test 目標
  • 避免使用無意義的後置字串，例如 _lib 或 _library (除非必須 避免 _library 目標及其對應的 _binary 之間發生衝突)
  • 與 proto 相關的目標：
    • proto_library 個目標的名稱必須以 _proto 結尾
    • 語言專屬的 *_proto_library 規則應符合基礎 proto，但將 _proto 替換為特定語言後置字串，例如：
      • cc_proto_library：_cc_proto
      • java_proto_library：_java_proto
      • java_lite_proto_library：_java_proto_lite

顯示設定

瀏覽權限應盡可能嚴格，同時仍允許存取權 擷取及反向依附元件使用「__pkg__」和「__subpackages__」做為 或適當。

避免將套件 default_visibility 設為 //visibility:public。 //visibility:public您只能為 呼叫專案的公用 API這些程式庫可能是專門為了依靠 提供給外部專案或二進位檔 建構程序

依附元件

應將依附元件限制為直接依附元件 (依附元件) 規則中所列來源所需的資源)。請勿列出遞移依附元件。

應先列出套件-本機依附元件，並以方式參照 可與 Google Kubernetes Engine 參照目前套件中的目標 一節 (而非其絕對套件名稱)。

想要直接列出依附元件，為單一清單。說「常見」 將多個目標依附於一個變數中會降低可維護性 工具就無法變更目標的依附元件 未使用的依附元件

眼鏡

標示「無目標」只在 []。請勿使用任何配對的 glob： 比起空白清單，較容易出錯，也不容易理解。

遞迴

請勿使用遞迴 glob 來比對來源檔案 (例如 glob(["**/*.java"]))。

遞迴 glob 會使 BUILD 檔案略過，因此難以理解 包含 BUILD 檔案的子目錄。

一般來說，遞迴 glob 的效率通常低於每個單個 BUILD 檔案。 並定義依附元件圖表，這樣可以 以及執行遠端快取和平行處理

建議您在每個目錄中編寫 BUILD 檔案，並定義 之間的依附關係圖

非遞迴

一般可接受非遞迴的 glob。

其他慣例

  • 請使用大寫和底線宣告常數 (例如 GLOBAL_CONSTANT)。 請使用小寫和底線宣告變數，例如 my_variable。

  • 標籤長度不應超過 79 個半形字元，也不應分割。 標籤應盡可能使用字串常值。理由：這樣做會 方便您尋找及取代提升可讀性。

  • 名稱屬性的值應為常值常數字串 (除了 )。理由：外部工具使用名稱屬性來指稱 規則。因此必須在不解讀程式碼的情況下找到規則。

  • 設定布林類型屬性時，請使用布林值，而非整數值。 但基於舊版原因，規則仍會視需要將整數轉換為布林值 但不建議這麼做理由：flaky = 1可能會誤以為 「請重新執行一次，將其延後」。flaky = True 不明確地說 「這項測試不穩定」

與 Python 樣式的差異指南

雖然與以下項目相容 Python 樣式指南 但是兩者之間有一些差異：

  • 沒有嚴格的行長度限制。長註解和長字串通常會被分割 數量增加至 79 個資料欄，但並非強制，不應在程式碼中強制執行 審查或預先提交腳本理由：標籤長度可以太長 我們會自動向帳單帳戶扣款 並每月或在您達到用量上限時發送帳單透過工具產生或編輯 BUILD 檔案很常見。 它不適用於行距限制

  • 不支援隱式字串串連。使用 + 運算子。 理由：BUILD 檔案包含許多字串清單。很容易忘記 就會產生完整的結果。這種情況造成很多錯誤 例如使用者過去是否曾在相同的裝置上 或在類似的地點登入另請參閱此討論。

  • 在規則中，請在 = 符號前後加上關鍵字引數。理由： 已命名引數比 Python 更頻繁，而且一律會放在 一行。聊天室可提高可讀性。這種慣例 且不適合修改所有現有的 BUILD 檔案。

  • 根據預設，字串應使用雙引號。理由：非如此 與 Python 樣式指南中所指定的語言相符，但還是建議保持一致我們 因此決定只使用雙引號字串許多語言都會使用雙引號 。

  • 兩個頂層定義之間請使用一個空白行。理由： BUILD 檔案的結構與一般 Python 檔案不同。它只包含 頂層陳述式使用單空白行會縮短 BUILD 檔案。