本页面适用于计划将其规则提供给其他人的规则编写者。
我们建议您从模板代码库开始创建新规则集: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 规则
- 代码库标记:
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
)。如果您认为自己的规则应遵循 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
文件中执行平台专用逻辑(例如,使用 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 操作。查看 rules-template 代码库中使用的配置,该代码库使用 bazel-contrib 组织中托管的“可重复使用的工作流”进行了简化。ci.yaml
会针对每个 PR 和 main
comit 运行测试,并且 release.yaml
会在您将标记推送到代码库时运行。如需了解详情,请参阅规则模板代码库中的注释。
如果您的代码库位于 bazelbuild 组织下,则可以请求添加到 ci.bazel.build。
文档
如需了解如何为规则添加注释以便系统自动生成文档,请参阅 Stardoc 文档。
rules-template docs/ folder 显示了一种简单的方法,可确保 docs/
文件夹中的 Markdown 内容始终在 Starlark 文件更新时是最新的。
常见问题解答
为什么无法将规则添加到 Bazel GitHub 主代码库?
我们希望尽可能将规则与 Bazel 版本分离开来。谁拥有各自的规则变得更加清晰,从而降低了 Bazel 开发者的负担。对于用户来说,分离有助于更轻松地修改、升级、降级和替换规则。为规则贡献代码可能比为 Bazel 贡献轻量(具体取决于规则),包括对相应 GitHub 代码库的完整提交权限。获取对 Bazel 本身的提交访问权限是一个更复杂的过程。
其缺点是,对我们的用户来说,一次性安装过程更为复杂:他们必须将规则复制并粘贴到 WORKSPACE
文件中,如上面的 README.md
部分所示。
我们以前把所有规则都放在 Bazel 代码库中(在 //tools/build_rules
或 //tools/build_defs
下)。我们仍然有几条规则,但我们正努力移出其余规则。