部署规则

<ph type="x-smartling-placeholder"></ph> 报告问题 查看来源 敬上 每晚 · 7.3。 · 7.2 条 · 7.1。 · 7.0。 · 6.5

本页面适用于计划公开规则的规则制定者 信息。

我们建议您从模板代码库开始创建新规则集： https://github.com/bazel-contrib/rules-template 该模板遵循下面的建议，并包含 API 文档生成功能 并设置 CI/CD 流水线，以轻松分发规则集。

托管和命名规则

新规则应放入您的组织下其自己的 GitHub 代码库中。 在 GitHub 上发起线程 如果你觉得规则属于bazelbuild 组织。

Bazel 规则的代码库名称已按以下格式标准化： $ORGANIZATION/rules_$NAME。 查看 GitHub 上的示例。 为保持一致性，在发布 Bazel 规则时，您应该遵循相同的格式。

请务必使用描述性的 GitHub 代码库说明和 README.md title，例如：

  • 代码库名称：bazelbuild/rules_go
  • 代码库说明：适用于 Bazel 的 Go 规则
  • 代码库标记：golang、bazel
  • README.md 标头：Bazel 的 Go 规则 （请注意指向 https://bazel.build 的链接，如果不熟悉 使用 Bazel 移动到合适的位置）

规则可以按语言（例如 Scala）、运行时平台分组 （如 Android）或框架（如 Spring）。

代码库内容

每个规则库都应具有特定的布局，以便用户快速 了解新规则

例如，在为 (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）。请 在 GitHub 上发起线程 如果您想让规则遵循 bazelbuild 组织。

在以下部分中，假设代码库属于 bazelbuild 组织。

workspace(name = "rules_mockascript")

自述文件

顶层应有一个 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 文件中执行平台专用逻辑（例如， 使用 selects）。 借助自定义约束，您可以定义一种语言，供整个 Bazel 生态系统 会说话。

Runfiles 库

如果您的规则提供用于访问 runfile 的标准库，它应该 采用位于 //<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/ 目录可以向用户显示一些 这些规则的基本使用方式

CI/CD

许多规则集都使用 GitHub Actions。查看 rules-template 代码库中使用的配置，该配置通过“可重复使用的工作流”进行了简化托管在 bazel-contrib 中 org.ci.yaml 对每个 PR 和 main 组合运行测试，release.yaml 会在您将标记推送到代码库时运行。 如需了解详情，请参阅 rules-template 代码库中的注释。

如果您的代码库位于 bazelbuild 组织下， 您可以要求添加 ci.bazel.build。

文档

如需查看以下内容，请参阅 Stardoc 文档 说明如何注释规则以便生成文档 。

rules-template docs/ 文件夹 展示了一种简单的方法，可确保 docs/ 文件夹中的 Markdown 内容始终保持最新状态 因为 Starlark 文件会更新。

常见问题解答

为什么我们不能将规则添加到 Bazel GitHub 主代码库？

我们希望尽可能将规则与 Bazel 版本分离。更清晰 单独管理规则，从而减少 Bazel 开发者的负载。对于我们的用户 通过分离，您可以更轻松地修改、升级、降级和替换规则。 与为 Bazel 编写贡献相比，为规则贡献内容可能更轻量： 包括对相应的 GitHub 代码库。获得对 Bazel 的提交访问权限本身要复杂得多 过程。

但这种方法的缺点是对用户而言，一次性安装的流程更为复杂： 他们必须将规则复制并粘贴到 WORKSPACE 文件中，如 README.md部分。

过去，我们把所有规则都放到了 Bazel 代码库（ //tools/build_rules 或 //tools/build_defs）。我们仍然需要遵循几条规则 ，但我们正在努力移除其余规则。