本頁面適用於打算向他人提供規則的規則撰寫者。
建議您從範本存放區啟動新的規則集: https://github.com/bazel-contrib/rules-template。該範本遵循下列建議,包含產生 API 說明文件並設定 CI/CD 管道,讓規則集得更容易發布。
託管和命名規則
新規則應進入貴機構專屬的 GitHub 存放區。如果您認為規則屬於 bazelbuild 組織,請在 GitHub 上建立執行緒。
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) 或架構 (例如 Spring) 將規則分組。
存放區內容
每個規則存放區都應具有特定版面配置,以便使用者快速瞭解新規則。
舉例來說,為 (容許) 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
)。否則,請為存放區 <org>_rules_<lang>
命名 (例如 build_stack_rules_proto
)。如果您認為規則應遵循 bazelbuild 中的規則慣例,請在 GitHub 上啟動執行緒。
在以下各節中,假設存放區屬於 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()
如果您的規則依附於另一個存放區的規則,請在規則說明文件中指明 (例如請參閱 Skydoc 規則,這些規則取決於 Sass 規則),並提供可下載所有依附元件的 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
檔案中執行平台專屬邏輯 (例如使用選取項目)。透過自訂限制,您可以定義整個 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
屬性參照的所有目標。如要註冊工具鍊,您必須在存放區中執行複雜運算,請考慮使用具有 <LANG>_toolchain
目標的存放區分割具有 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/
目錄,可為使用者提供規則的幾種基本使用方式,非常實用。
CI/CD
許多規則集使用 GitHub Actions。查看 rules-template 存放區中使用的設定,這些存放區使用 bazel-contrib 機構代管的「可重複使用的工作流程」簡化了其中的設定。ci.yaml
會在每個 PR 和 main
函式上執行測試,而每當您將標記推送至存放區時,release.yaml
都會執行。詳情請參閱 Rules-範本存放區中的註解。
如果您的存放區位於 bazelbuild 機構中,您可以要求將存放區新增至 ci.bazel.build。
說明文件
如要瞭解如何加註規則,以便系統自動產生說明文件,請參閱 Stardoc 說明文件。
rules-template docs/ folder 顯示一種簡單的方法,可確保 docs/
資料夾中的 Markdown 內容隨時保持在最新狀態,因為 Starlark 檔案需要更新。
常見問題
為何我們無法將規則新增至主要 Bazel GitHub 存放區?
我們希望盡可能將規則與 Bazel 版本分離。每個規則的擁有者都比較清楚,減少 Bazel 開發人員的負載。對使用者來說,分離規則可讓您輕鬆修改、升級、降級及取代規則。視規則而定,影響規則的權重可能比 Bazel 少,包括對對應 GitHub 存放區的完整提交存取權。取得 Bazel 本身的存取權是比較複雜的程序。
這個做法對使用者而言是較複雜的一次性安裝程序,必須複製規則貼到 WORKSPACE
檔案中,如上方的 README.md
部分所示。
我們之前將 Bazel 存放區中的所有規則 (在 //tools/build_rules
或 //tools/build_defs
下) 納入。目前仍有幾項規則,但我們正努力移出其餘的規則。