2022 年 BazelCon 将于 11 月 16 日至 17 日在纽约和线上举办。
立即报名!

部署规则

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

托管和命名规则

新规则应存放在您的组织下的 GitHub 代码库中。如果您认为您的规则属于 Bazelbuild 组织,请与 Bazel-dev 邮寄名单联系。

Bazel 规则的代码库名称采用以下格式采用以下格式:$ORGANIZATION/rules_$NAME。请参阅 GitHub 上的示例。为了保持一致性,在发布 Bazel 规则时必须遵循相同的格式。

请务必使用 GitHub 代码库说明和 README.md 标题,例如:

  • 代码库名称:bazelbuild/rules_go
  • 代码库说明:Go 使用 Bazel 规则
  • 代码库标记:golangbazel
  • README.md 标头:Bazel 的 Go 规则(请注意指向 https://Bazel.build 的链接,引导不熟悉的用户) Bazel 到正确的位置)

规则可以按语言(例如 Scala)或平台(例如 Android)进行分组。

代码库内容

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

例如,针对(假设)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)。如果您认为自己的规则应该遵循 只有在 buildbuild 组织中规则的惯例,请联系 Bazel-dev 邮寄名单

在以下部分中,假设代码库属于 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 属性引用的所有目标。如果要注册工具链,需要在代码库中执行复杂的计算,请考虑将含有 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.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 下)。我们还有几条规则,但我们正在努力移除其余规则。