部署规则

报告问题 查看源代码 每夜 build · 7.4 .

本页面适用于计划向他人提供规则的规则制定者。

我们建议您从模板代码库开始一个新规则集: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)进行分组。

代码库内容

每个规则代码库都应具有一定的布局,以便用户快速理解新规则。

例如,在为 (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)。如果您认为自己的规则应遵循 bazelbuild 组织中的规则惯例,请在 GitHub 上发起会话。

在以下部分中,假设代码库属于 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 文件中执行平台特定的逻辑(例如,使用选择)。借助自定义约束条件,您可以定义整个 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>_toolchainsWORKSPACE 宏添加到 <LANG>/repositories.bzl 文件中。

请注意,为了在分析阶段解析工具链,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-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 下)中添加了所有规则。现在,我们还有一些规则,但我们正在努力将其余规则移出。