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"
- 如果特定目標有多個變化版本,請在
釐清 (例如
: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
檔案。