本页面适用于计划公开规则的规则制定者 信息。
我们建议您从模板代码库开始创建新规则集: 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
)。我们仍然需要遵循几条规则
,但我们正在努力移除其余规则。