建構樣式指南

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

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.cccc_library 可以是 chat,也可以是 java_library DirectMessage.java 的名稱可能是 direct_message)。

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

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

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

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

  • 一般來說,請使用 "snake_case"
    • 對於具有 srcjava_library,這表示使用的名稱不是 與不含副檔名的檔案名稱相同
    • 如果是 Java *_binary*_test 規則,請使用 「Upper CamelCase」。 這樣一來,目標名稱就能與其中一個 src 比對。適用對象 java_test,如此一來,test_class 屬性即可能 從目標名稱推斷得出
  • 如果特定目標有多個變化版本,請在 釐清 (例如:foo_dev:foo_prod:bar_x86:bar_x64)
  • 使用 _test_unittestTestTests 後後置字串 _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 檔案。