正在部署規則

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

本頁面適用於打算將規則提供給他人的規則編寫者。

建議您從範本存放區開始建立新的規則集: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 規則
  • 存放區標記:golangbazel
  • README.md 標頭:Bazel 的 Go 規則 (請注意,https://bazel.build 的連結可引導不熟悉 Bazel 的使用者前往正確的位置)

您可以依據語言 (例如 Scala)、執行階段平台 (例如 Android) 或架構 (例如 Spring) 將規則分組。

存放區內容

每個規則存放區都應採用特定版面配置,方便使用者快速瞭解新規則。

舉例來說,當您為 (假設) mockascript 語言編寫新規則時,規則存放區的結構會如下所示:

/
  LICENSE
  README
  MODULE.bazel
  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

MODULE.bazel

在專案的 MODULE.bazel 中,您應定義使用者用來參照規則的名稱。如果您的規則屬於 bazelbuild 機構,則必須使用 rules_<lang> (例如 rules_mockascript)。否則,建議您為存放區命名,例如 build_stack_rules_proto。如果您認為規則應遵循 bazelbuild 機構中的規則慣例,請在 GitHub 上啟動執行緒。<org>_rules_<lang>

在以下各節中,假設存放區屬於 bazelbuild 機構。

module(name = "rules_mockascript")

README

在最上層,應有 README,其中包含規則集的簡短說明,以及 API 使用者應預期的內容。

規則

存放區通常會提供多個規則。建立以語言命名的目錄,並提供一個可匯出所有規則的進入點 - 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 屬性。

存放區規則

依附元件

您的規則可能會有外部依附元件,您需要在 MODULE.bazel 檔案中指定這些依附元件。

註冊工具鏈

規則也可能會註冊工具鍊,您也可以在 MODULE.bazel 檔案中指定工具鍊。

請注意,為了在分析階段解析工具鍊,Bazel 需要分析所有已註冊的 toolchain 目標。Bazel 不需要分析 toolchain.toolchain 屬性參照的所有目標。如果您為了註冊工具鏈而需要在存放區中執行複雜的運算,建議您將含有 toolchain 目標的存放區與含有 <LANG>_toolchain 目標的存放區分開。前者一律會擷取,而後者只會在使用者實際需要建構 <LANG> 程式碼時才會擷取。

發布摘要

在發布公告中提供程式碼片段,讓使用者複製貼上至 MODULE.bazel 檔案。這個程式碼片段通常會如下所示:

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

測試命名空間

您應先進行測試,確認規則運作正常。這個檔案可以位於規則所適用語言的標準位置,也可以位於頂層的 tests/ 目錄中。

範例 (選填)

提供 examples/ 目錄可讓使用者瞭解幾種基本使用規則的方式,對使用者來說很有幫助。

CI/CD

許多規則集都會使用 GitHub Actions。請參閱 rules-template 存放區中使用的設定,這些設定已簡化為在 bazel-contrib 網站上代管的「可重複使用的工作流程」。ci.yaml 會對每個 PR 和 main 提交執行測試,而 release.yaml 會在您將標記推送至存放區時執行。詳情請參閱 Rules-template 存放區中的註解。

如果您的存放區屬於 bazelbuild 組織,您可以要求將其加入 ci.bazel.build

說明文件

如要瞭解如何註解規則以便自動產生文件,請參閱 Stardoc 說明文件

規則範本文件/ 資料夾會顯示簡單的方法,確保 docs/ 資料夾中的 Markdown 內容隨 Starlark 檔案更新而保持最新狀態。

常見問題

為什麼我們無法將規則新增至主要的 Bazel GitHub 存放區?

我們希望盡可能將規則與 Bazel 版本分開。這樣一來,誰擁有個別規則就更為明確,可減少 Bazel 開發人員的負擔。對於使用者而言,分離後可更輕鬆地修改、升級、降級及取代規則。根據規則的不同,提供規則的負擔可能比提供 Bazel 還要輕,包括對應 GitHub 存放區的完整提交存取權。取得提交 Bazel 的存取權,則是更複雜的程序。

缺點是使用者必須在 MODULE.bazel 檔案中新增對規則集的依附元件,因此一次性安裝程序會變得更複雜。

我們過去將 Bazel 存放區中的所有規則 (在 //tools/build_rules//tools/build_defs 下) 保存起來。我們仍有一些規則,但我們正在設法將其餘規則移出。