正在部署規則

回報問題 查看原始碼 夜間 7.2 7.1 7.0 6.5 6.4

本頁內容適用於打算開放規則的規則撰寫者 供他人參考。

代管和命名規則

新規則應傳送至貴機構專屬的 GitHub 存放區。 聯絡 bazel-dev 郵寄清單 如果您認為您的規則已應用於 bazelbuild 並根據貴機構的使命 價值觀和目標進行調整

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)。否則，您應該為 存放區 <org>_rules_<lang> (例如 build_stack_rules_proto)。請聯絡 bazel-dev 郵寄清單 如果您認為規則應該遵循 Bazelbuild 的機構建立。

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

workspace(name = "rules_mockascript")

README

頂層應有一個 README 包含 (至少) 符合以下條件的內容： 使用者必須複製並貼到 WORKSPACE 檔案中，才能使用您的規則。 一般而言，這會是指向 GitHub 版本的 http_archive，且 巨集呼叫，可下載/設定規則所需的任何工具。例如： 目標為前往 規則，此 如下所示：

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

限制

如果您的規則定義了 toolchain 規則時 您可能需要定義自訂 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 巨集，以註冊這些工具鍊。如此一來，使用者就能 先前的巨集和控制依附元件，同時仍可 註冊工具鍊。

因此，新增名為 rules_<LANG>_toolchains 的 WORKSPACE 巨集至 <LANG>/repositories.bzl 檔案。

請注意，為解決分析階段中的工具鍊，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.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 本身的存取權，相當耗時 上傳資料集之後，您可以運用 AutoML 自動完成部分資料準備工作

這對使用者來說是個比較複雜的一次性安裝程序： 使用者就必須將規則複製貼到 WORKSPACE 檔案中，如下所示 README.md部分。

我們過去將 Bazel 存放區中的所有規則 //tools/build_rules 或 //tools/build_defs)。我們還有一些規則 但我們正在努力將其餘規則移出。