部署规则

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

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

托管和命名规则

新规则应放入您的组织下其自己的 GitHub 代码库中。 请与 bazel-dev 邮寄名单联系 如果你觉得规则属于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）。

代码库内容

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

例如，在为 (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）。请联系 bazel-dev 邮寄名单 如果您想让规则遵循 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/ 目录可以向用户显示一些 这些规则的基本使用方式

测试

按照 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）。我们仍然需要遵循几条规则 ，但我们正在努力移除其余规则。