本頁面適用於打算將規則提供給他人的規則編寫者。
代管和命名規則
新規則應放入貴機構下的 GitHub 存放區。如果您認為自己的規則屬於 bazelbuild 組織,請與 bazel-dev 電子郵件討論群組聯絡。
Bazel 規則的存放區名稱會以下列格式標準化:$ORGANIZATION/rules_$NAME
。
請參閱 GitHub 上的範例。為求一致性,您必須在發布 Bazel 規則時遵循相同的格式。
請務必使用具描述性的 GitHub 存放區說明和 README.md
標題,例如:
- 存放區名稱:
bazelbuild/rules_go
- 存放區說明:Bazel 的 Go 規則
- 存放區標記:
golang
、bazel
README.md
標題:Bazel 的 Go 規則 (請注意,連結至 https://bazel.build,可將不熟悉 Bazel 的使用者引導至正確位置)
規則可依語言 (例如 Scala) 或平台 (例如 Android) 分組。
存放區內容
每個規則存放區都應有特定的版面配置,方便使用者快速瞭解新規則。
例如,為 (make-believe) mockascript
語言編寫新規則時,規則存放區將採用以下結構:
/
LICENSE
README
WORKSPACE
mockascript/
constraints/
BUILD
runfiles/
BUILD
runfiles.mocs
BUILD
defs.bzl
tests/
BUILD
some_test.sh
another_test.py
examples/
BUILD
bin.mocs
lib.mocs
test.mocs
工作區
在專案的 WORKSPACE
中,您應定義使用者用來參照規則的名稱。如果您的規則屬於 bazelbuild 機構,則必須使用 rules_<lang>
(例如 rules_mockascript
)。否則,請為存放區命名 (例如 build_stack_rules_proto
)。如果您認為您的規則應遵循 bazelbuild 機構的規則慣例,請聯絡 bazel-dev 郵寄清單。<org>_rules_<lang>
在以下各節中,假設存放區屬於 bazelbuild 機構。
workspace(name = "rules_mockascript")
README
頂層應有一個 README
,其中至少應包含使用者須將哪些內容複製貼到 WORKSPACE
檔案中,才能使用您的規則。一般來說,這會是指向 GitHub 版本的 http_archive
,以及用於下載/設定規則所需工具的巨集呼叫。例如,針對 Go 規則,這會是以下內容:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_go",
urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()
如果您的規則會依附其他存放區的規則,請在規則說明文件中指定這項資訊 (例如,請參閱依附 Sass 規則的 Skydoc 規則),並提供可下載所有依附元件的 WORKSPACE
巨集 (請參閱上述 rules_go
)。
規則
存放區通常會提供多個規則。建立以語言命名的目錄,並提供一個可匯出所有規則的進入點 - defs.bzl
檔案 (也包含 BUILD
檔案,以便目錄成為套件)。rules_mockascript
代表有名為 mockascript
的目錄,以及 BUILD
檔案和 defs.bzl
檔案:
/
mockascript/
BUILD
defs.bzl
限制
如果規則定義了工具鏈規則,您可能需要定義自訂 constraint_setting
和/或 constraint_value
。將這些項目放入 //<LANG>/constraints
套件。目錄結構如下所示:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
請參閱 github.com/bazelbuild/platforms 瞭解最佳做法,並查看現有的限制條件,如果您的限制條件不受語言限制,不妨考慮將其貢獻給該網站。請注意,導入自訂限制後,所有規則使用者都會在自己的 BUILD
檔案中使用這些限制執行平台專屬邏輯 (例如使用 selects)。您可以使用自訂限制,定義整個 Bazel 生態系統將使用的語言。
Runfiles 程式庫
如果規則提供用於存取執行檔的標準程式庫,則應以位於 //<LANG>/runfiles
(//<LANG>/runfiles:runfiles
的縮寫) 的程式庫目標形式提供。需要存取資料依附元件的使用者目標通常會將這個目標加入 deps
屬性。
存放區規則
依附元件
您的規則可能會有外部依附元件。為了讓依附規則更簡單,請提供 WORKSPACE
巨集,以便宣告對這些外部依附元件的依附元件。請勿在此宣告測試的依附元件,只需宣告規則運作所需的依附元件。將開發依附元件放入 WORKSPACE
檔案。
建立名為 <LANG>/repositories.bzl
的檔案,並提供名為 rules_<LANG>_dependencies
的單一進入點巨集。我們的目錄如下所示:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
註冊工具鏈
您的規則也可能會註冊工具鍊。請提供單獨的 WORKSPACE
巨集來註冊這些工具鍊。這樣一來,使用者就能決定省略先前的巨集並手動控制依附元件,同時仍可註冊工具鍊。
因此,請在 <LANG>/repositories.bzl
檔案中新增名為 rules_<LANG>_toolchains
的 WORKSPACE
巨集。
請注意,為了在分析階段解析工具鍊,Bazel 需要分析所有已註冊的 toolchain
目標。Bazel 不需要分析 toolchain.toolchain
屬性參照的所有目標。如果您為了註冊工具鏈而需要在存放區中執行複雜的運算,建議您將含有 toolchain
目標的存放區與含有 <LANG>_toolchain
目標的存放區分開。前者一律會擷取,而後者只會在使用者實際需要建構 <LANG>
程式碼時才會擷取。
版本程式碼片段
在發布公告中提供程式碼片段,讓使用者複製貼上至 WORKSPACE
檔案。這個程式碼片段通常會如下所示:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_<LANG>",
urls = ["<url_to_the_release.zip"],
sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()
測試命名空間
您應該要進行測試,驗證規則是否正常運作。這可以位於規則所屬語言的標準位置,或是頂層的 tests/
目錄。
範例 (選填)
提供 examples/
目錄可讓使用者瞭解幾種基本使用規則的方式,對使用者來說很有幫助。
測試
按照 Travis 入門文件所述,設定 Travis。然後在存放區中新增含有以下內容的 .travis.yml
檔案:
dist: xenial # Ubuntu 16.04
# On trusty (or later) images, the Bazel apt repository can be used.
addons:
apt:
sources:
- sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
key_url: 'https://bazel.build/bazel-release.pub.gpg'
packages:
- bazel
script:
- bazel build //...
- bazel test //...
如果您的存放區屬於 bazelbuild 組織,您可以要求將其加入 ci.bazel.build。
說明文件
請參閱 Stardoc 說明文件,瞭解如何為規則加上註解,以便自動產生說明文件。
常見問題
為什麼我們無法將規則新增至主要的 Bazel GitHub 存放區?
我們希望盡可能將規則與 Bazel 版本分開。這樣一來,誰擁有個別規則就更為明確,可減少 Bazel 開發人員的負擔。對於使用者而言,分離後可更輕鬆地修改、升級、降級及取代規則。視規則而定,提交至規則的權重可能比用於 Bazel 稍低,包括完整提交對應 GitHub 存放區的權限。取得提交 Bazel 的存取權,則是更複雜的程序。
缺點是使用者必須複製貼上規則至 WORKSPACE
檔案,如上述 README.md
部分所示,這會讓一次性安裝程序變得更複雜。
我們過去將 Bazel 存放區中的所有規則 (在 //tools/build_rules
或 //tools/build_defs
下) 保存起來。我們仍有一些規則,但我們正在設法將其餘規則移出。