正在部署規則

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

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

代管和命名規則

新規則應傳送至貴機構專屬的 GitHub 存放區。如果您認為規則屬於 bazelbuild 機構,請聯絡 bazel-dev 郵寄清單

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) 分組。

存放區內容

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

例如,為 (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 檔案中執行平台專屬邏輯 (例如使用選取項目)。您可以使用自訂限制,定義整個 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>_toolchainsWORKSPACE 巨集。

請注意,為解析分析階段中的工具鍊,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 下) 保存起來。我們仍有一些規則,但我們正在設法將其餘規則移出。