一般规则

报告问题 查看来源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

规则

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

别名

查看规则来源

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

alias 规则会创建规则的另一个名称，可用于引用规则。

别名仅适用于“常规”目标。特别是，package_group 和 test_suite 不能别名化。

在大型代码库中，如果重命名目标需要更改大量文件，别名可能会有所帮助。如果您想将某个 select 函数调用重复用于多个目标，也可以使用别名规则来存储该函数调用。

别名规则有自己的可见性声明。在所有其他方面，它都与所引用的规则类似（例如，忽略别名上的 testonly；而是使用所引用规则的 testonly 属性），但有一些细微的例外情况：

• 如果测试的别名在命令行中被提及，则不会运行该测试。如需定义运行所引用测试的别名，请使用 test_suite 规则，并在其 tests 属性中包含单个目标。
• 定义环境组时，不支持 environment 规则的别名。--target_environment 命令行选项中也不支持这些变量。

示例

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

参数

属性
name	名称；必需 相应目标的唯一名称。
actual	标签；必需 相应别名所指的目标。它不一定是一条规则，也可以是一个输入文件。

config_setting

查看规则来源

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

匹配预期配置状态（表示为 build 标志或平台限制），以触发可配置的属性。如需了解如何使用此规则，请参阅 select；如需大致了解此常规功能，请参阅 可配置的属性。

示例

以下内容与设置了 --compilation_mode=opt 或 -c opt（通过命令行显式设置或通过 .bazelrc 文件隐式设置）的任何 build 相匹配：

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

以下内容会匹配以 ARM 为目标平台的任何 build，并应用自定义 define FOO=bar（例如 bazel build --cpu=arm --define FOO=bar ...）：

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

以下内容匹配任何设置了用户定义的标志 --//custom_flags:foo=1（通过命令行显式设置或通过 .bazelrc 文件隐式设置）的 build：

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

以下内容会匹配以 x86_64 架构和 glibc 版本 2.25 为目标的任何 build，前提是存在标签为 //example:glibc_2_25 的 constraint_value。请注意，如果平台定义了除这两个以外的其他限制条件值，仍会匹配。

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

在所有这些情况下，配置都可能在 build 过程中发生变化，例如，如果某个目标需要针对不同于其依赖项的平台进行 build。这意味着，即使 config_setting 与顶级命令行标志不匹配，它也可能与某些 build 目标匹配。

备注

• 如需了解当多个 config_setting 与当前配置状态匹配时会发生什么情况，请参阅选择。
• 对于支持简写形式的标志（例如 --compilation_mode 与 -c），values 定义必须使用完整形式。这些规则会自动匹配使用任一形式的调用。
• 如果某个标志接受多个值（例如 --copt=-Da --copt=-Db 或列表类型的 Starlark 标志），则当实际列表中任意位置存在 "a" 时，values = { "flag": "a" } 匹配。

  values = { "myflag": "a,b" } 的工作方式相同：它会匹配 --myflag=a --myflag=b、--myflag=a --myflag=b --myflag=c、--myflag=a,b 和 --myflag=c,b,a。各个标志的确切语义各不相同。例如，--copt 不支持同一实例中的多个值：--copt=a,b 会生成 ["a,b"]，而 --copt=a --copt=b 会生成 ["a", "b"]（因此 values = { "copt": "a,b" } 与前者匹配，但不与后者匹配）。但 --ios_multi_cpus（对于 Apple 规则）会：-ios_multi_cpus=a,b 和 ios_multi_cpus=a --ios_multi_cpus=b 都会生成 ["a", "b"]。仔细检查标志定义并测试您的条件，以验证确切的预期。

• 如果您需要定义内置 build 标志无法模拟的条件，请使用 Starlark 定义的标志。您也可以使用 --define，但此方法提供的支持较弱，不建议使用。如需了解详情，请点击此处查看相关讨论。
• 避免在不同软件包中重复相同的 config_setting 定义。 而是引用在规范软件包中定义的通用 config_setting。
• values、define_values 和 constraint_values 可在同一 config_setting 中以任意组合使用，但对于任何给定的 config_setting，至少必须设置一个。

参数

属性
name	名称；必需 相应目标的唯一名称。
constraint_values	标签列表；不可配置；默认值为 [] 目标平台必须指定的最小 constraint_values 集，才能与此 config_setting 相匹配。（此处不考虑执行平台。）平台具有的任何其他限制值都会被忽略。如需了解详情，请参阅 可配置的 build 属性。 如果两个 config_setting 在同一 select 中都匹配，则在确定其中一个 config_setting 是否是另一个的专业化时，不考虑此属性。换句话说，一个 config_setting 不能比另一个平台更匹配。
define_values	字典：字符串 -> 字符串；不可配置；默认值为 {} 与 values 相同，但专门针对 --define 标志。 --define 之所以特殊，是因为其语法 (--define KEY=VAL) 从 Bazel 标志的角度来看，表示 KEY=VAL 是一个值。 这意味着： config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) 之所以不起作用，是因为同一键 (define) 在字典中出现了两次。此属性可解决该问题： config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", }) 正确匹配 bazel build //foo --define a=1 --define b=2。 --define 仍可使用常规标志语法出现在 values 中，并且可以与此属性自由混合，只要字典键保持不同即可。
flag_values	字典：标签 -> 字符串；不可配置；默认值为 {} 与 values 相同，但适用于 用户定义的 build 标志。 这是一个独特的属性，因为用户定义的标志被引用为标签，而内置标志被引用为任意字符串。
values	字典：字符串 -> 字符串；不可配置；默认值为 {} 与此规则匹配的一组配置值（以 build 标志表示） 此规则会继承在 select 语句中引用它的已配置目标的配置。如果字典中的每个条目的配置都与相应条目的预期值匹配，则认为该 Bazel 调用“匹配”。例如，values = {"compilation_mode": "opt"} 匹配目标配置规则上的调用 bazel build --compilation_mode=opt ... 和 bazel build -c opt ...。 为方便起见，配置值指定为 build 标志（不带前面的 "--"）。但请注意，这两者并不相同。这是因为可以在同一 build 中以多种配置构建目标。例如，执行配置的“cpu”与 --host_cpu 的值匹配，而不与 --cpu 的值匹配。因此，同一 config_setting 的不同实例可能会以不同的方式匹配同一调用，具体取决于使用它们的规则的配置。 如果未在命令行中明确设置标志，则使用其默认值。 如果某个键在字典中多次出现，则仅使用最后一个实例。 如果某个键引用了可在命令行上多次设置的标志（例如 bazel build --copt=foo --copt=bar --copt=baz ...），则只要任何设置匹配，就会发生匹配。

filegroup

查看规则来源

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

使用 filegroup 为一组目标指定一个方便的名称。 然后，其他规则可以引用这些变量。

建议使用 filegroup，而不是直接引用目录。 后者是不合理的，因为构建系统并不完全了解目录下的所有文件，因此当这些文件发生更改时，它可能不会重新构建。与 glob 结合使用时，filegroup 可确保构建系统明确知道所有文件。

示例

如需创建包含两个源文件的 filegroup，请执行以下操作：

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

或者，使用 glob 来搜索 testdata 目录：

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

如需使用这些定义，请在任何规则中引用带有标签的 filegroup：

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

参数

属性
name	名称；必需 相应目标的唯一名称。
srcs	标签列表；默认值为 [] 文件组中包含的目标的列表。 通常情况下，我们会使用 glob 表达式的结果作为 srcs 属性的值。
data	标签列表；默认值为 [] 相应规则在运行时所需的文件列表。 data 属性中指定的目标将添加到相应 filegroup 规则的 runfiles 中。当 filegroup 在另一条规则的 data 属性中被引用时，其 runfiles 将添加到依赖规则的 runfiles 中。如需详细了解如何依赖和使用数据文件，请参阅数据依赖项部分和 data 的常规文档。
output_group	字符串；默认值为 "" 要从中收集来源工件的输出组。如果指定了此属性，系统将导出依赖项的指定输出组中的制品，而不是默认输出组中的制品。 “输出组”是目标的一类输出制品，在相应规则的实现中指定。

genquery

查看规则来源

genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() 运行 Blaze 查询语言中指定的查询，并将结果转储到文件中。

为了保持 build 的一致性，查询只能访问 scope 属性中指定的目标的传递闭包。如果查询违反此规则，则在执行期间会失败（如果 strict 未指定或为 true）。如果 strict 为 false，则系统只会跳过范围外的目标，并显示警告。确保不会发生这种情况的最简单方法是在范围中提及与查询表达式中相同的标签。

此处允许的查询与命令行中允许的查询之间的唯一区别在于，此处不允许包含通配符目标规范（例如 //pkg:* 或 //pkg:all）的查询。 这有两个原因：首先，genquery 必须指定范围，以防止查询的传递闭包之外的目标影响其输出；其次，BUILD 文件不支持通配符依赖项（例如，不允许使用 deps=["//a/..."]）。

为了强制执行确定性输出，genquery 的输出按字典顺序排序，但 --output=graph|minrank|maxrank 或 somepath 用作顶级函数时除外。

输出文件的名称是规则的名称。

示例

此示例将指定目标传递闭包中的标签列表写入文件。

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

参数

属性
name	名称；必需 相应目标的唯一名称。
compressed_output	布尔值；默认值为 False 如果值为 True，则查询输出以 GZIP 文件格式写入。如果查询输出预计会很大，可以使用此设置来避免 Bazel 的内存使用量出现峰值。无论此设置的值是多少，Bazel 都会在内部压缩大于 2^20 字节的查询输出，因此将此设置设为 True 可能不会减少保留的堆。不过，它允许 Bazel 在写入输出文件时跳过解压缩，这可能会消耗大量内存。
expression	字符串；必需 要执行的查询。与命令行和 BUILD 文件中的其他位置不同，此处的标签是相对于工作区的根目录解析的。例如，文件 a/BUILD 中此属性的标签 :b 将引用目标 //:b。
opts	字符串列表；默认值为 [] 传递给查询引擎的选项。这些参数对应于可传递给 bazel query 的命令行选项。此处不允许使用某些查询选项：--keep_going、--query_file、--universe_scope、--order_results 和 --order_output。未在此处指定的选项将具有默认值，就像在 bazel query 的命令行中一样。
scope	标签列表；必需 查询的范围。不允许查询触及这些目标的传递闭包之外的目标。
strict	布尔值；默认值为 True 如果为 true，则查询逃脱其范围的传递闭包的目标将无法构建。如果为 false，Bazel 将打印警告并跳过导致其超出范围的任何查询路径，同时完成其余查询。

genrule

查看规则来源

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule 使用用户定义的 Bash 命令生成一个或多个文件。

Genrule 是一种通用 build 规则，如果没有适用于相应任务的特定规则，您可以使用这种规则。 例如，您可以运行 Bash 单行命令。不过，如果您需要编译 C++ 文件，请坚持使用现有的 cc_* 规则，因为所有繁重的工作都已为您完成。

请注意，genrule 需要 shell 来解释命令实参。 还可以轻松引用 PATH 上提供的任意程序，但这会使命令不密封，并且可能无法重现。 如果您只需要运行单个工具，请考虑改用 run_binary。

请勿使用 genrule 运行测试。测试和测试结果有特殊豁免，包括缓存政策和环境变量。测试通常需要在 build 完成后在目标架构上运行，而 genrule 在 build 期间在执行架构上执行（两者可能不同）。如果您需要一个通用测试规则，请使用 sh_test。

交叉编译注意事项

如需详细了解交叉编译，请参阅用户手册。

虽然 genrule 在 build 期间运行，但其输出通常在 build 之后用于部署或测试。以编译微控制器的 C 代码为例：编译器接受 C 源文件，并生成可在微控制器上运行的代码。生成的代码显然无法在用于构建它的 CPU 上运行，但 C 编译器（如果从源代码编译）本身必须能够运行。

构建系统使用执行配置来描述运行构建的机器，并使用目标配置来描述构建的输出应运行的机器。它提供了一些选项来配置这些内容，并将相应的文件隔离到单独的目录中，以避免冲突。

对于 genrule，构建系统会确保依赖项得到适当构建：srcs 会针对目标配置进行构建（如果需要），tools 会针对执行配置进行构建，并且输出会被视为针对目标配置。它还提供 genrule 命令可传递给相应工具的 “Make”变量。

genrule 未定义 deps 属性是有意为之：其他内置规则使用在规则之间传递的语言相关元信息来自动确定如何处理依赖规则，但 genrule 无法实现这种程度的自动化。Genrule 纯粹在文件和 runfiles 级别上运行。

特殊情况

执行-执行编译：在某些情况下，构建系统需要运行 genrule，以便在构建期间也能执行输出。例如，如果某个 genrule 构建了某个自定义编译器，而该编译器随后被另一个 genrule 使用，则第一个 genrule 必须为其执行配置生成输出，因为编译器将在另一个 genrule 中运行。在这种情况下，构建系统会自动执行正确的操作：它会为执行配置构建第一个 genrule 的 srcs 和 outs，而不是为目标配置构建。如需了解详情，请参阅用户手册。

JDK 和 C++ 工具：如需使用 JDK 或 C++ 编译器套件中的工具，构建系统提供了一组可供使用的变量。如需了解详情，请参阅 “Make”变量。

genrule 环境

genrule 命令由一个配置为在命令或流水线失败时失败的 Bash shell 执行，使用 set -e -o pipefail。

构建工具会在经过清理的进程环境中执行 Bash 命令，该环境仅定义核心变量，例如 PATH、PWD、TMPDIR 和其他一些变量。 为了确保 build 可重现，用户 shell 环境中定义的大多数变量不会传递给 genrule 的命令。不过，Bazel（但不是 Blaze）会传递用户的 PATH 环境变量的值。 对 PATH 值的任何更改都会导致 Bazel 在下一次 build 时重新执行该命令。

genrule 命令不应访问网络，除非是为了连接属于该命令本身的子进程，不过目前尚未强制执行此规则。

构建系统会自动删除所有现有的输出文件，但在运行 genrule 之前会创建所有必需的父目录。如果出现故障，它还会移除所有输出文件。

一般建议

• 请务必确保由 genrule 运行的工具是确定性的和密封的。它们不应将时间戳写入输出，并且应使用稳定的集合和映射排序，以及仅将相对文件路径写入输出，而不写入绝对路径。不遵循此规则会导致意外的 build 行为（Bazel 未重新构建您认为它会重新构建的 genrule），并降低缓存性能。
• 请广泛使用 $(location)，用于输出、工具和来源。由于不同配置的输出文件是分开的，因此 genrule 不能依赖于硬编码和/或绝对路径。
• 如果多个位置使用相同或非常相似的 genrule，请编写一个通用的 Starlark 宏。如果 genrule 较为复杂，请考虑在脚本中或作为 Starlark 规则实现它。这有助于提高可读性和可测试性。
• 请务必确保退出代码正确指示了 genrule 的成功或失败。
• 请勿将信息性消息写入 stdout 或 stderr。虽然这对于调试很有用，但很容易变成干扰信息；成功的 genrule 应该保持静默。另一方面，失败的 genrule 应该发出良好的错误消息。
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x)。
• 避免创建符号链接和目录。Bazel 不会复制由 genrule 创建的目录/符号链接结构，并且其目录依赖项检查不健全。
• 在其他规则中引用 genrule 时，您可以使用 genrule 的标签或各个输出文件的标签。有时，一种方法更易于理解；有时，另一种方法更易于理解：在使用规则的 srcs 中按名称引用输出将避免无意中获取 genrule 的其他输出，但如果 genrule 生成许多输出，则可能会很麻烦。

示例

此示例会生成 foo.h。没有来源，因为该命令不接受任何输入。该命令运行的“二进制文件”是与 genrule 位于同一软件包中的 perl 脚本。

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

以下示例展示了如何使用 filegroup 和另一个 genrule 的输出。请注意，使用 $(SRCS) 而不是显式 $(location) 指令也可行；此示例使用后者是为了演示。

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

参数

属性
name	名称；必需 相应目标的唯一名称。 您可以在其他 BUILD 规则的 srcs 或 deps 部分中按名称引用此规则。如果规则生成源文件，您应使用 srcs 属性。
srcs	标签列表；默认值为 [] 相应规则的输入列表，例如要处理的源文件。 此属性不适合列出由 cmd 执行的工具；请改用 tools 属性。 构建系统可确保在运行 genrule 命令之前构建这些前提条件；它们是使用与原始构建请求相同的配置构建的。这些前提条件的文件名以空格分隔的列表形式在 $(SRCS) 中提供给命令；或者，可以使用 $(location //x:y) 获取单个 srcs 目标 //x:y 的路径，也可以使用 $<（前提是它是 srcs 中的唯一条目）。
outs	文件名列表；不可配置；必需 相应规则生成的文件列表。 输出文件不得跨越软件包边界。 输出文件名被解读为相对于软件包。 如果设置了 executable 标志，则 outs 必须仅包含一个标签。 genrule 命令应在预定位置创建每个输出文件。 该位置可在 cmd 中使用 genrule 特定的“Make”变量（$@、$(OUTS)、$(@D) 或 $(RULEDIR)）或使用 $(location) 替换进行设置。
cmd	字符串；默认值为 "" 要运行的命令。 受 $(location) 和 “Make”变量替换的影响。 首先，应用 $(location) 替换，替换所有出现的 $(location label) 和 $(locations label)（以及使用相关变量 execpath、execpaths、rootpath 和 rootpaths 的类似结构）。 接下来，系统会展开 “制作”变量。请注意，预定义变量 $(JAVA)、$(JAVAC) 和 $(JAVABASE) 在 exec 配置下展开，因此作为构建步骤的一部分运行的 Java 调用可以正确加载共享库和其他依赖项。 最后，使用 Bash shell 执行生成的命令。如果其退出代码不为零，则该命令会被视为失败。 这是 cmd_bash、cmd_ps 和 cmd_bat 的回退，如果它们都不适用，则使用此值。 如果命令行长度超过平台限制（在 Linux/macOS 上为 64K，在 Windows 上为 8K），则 genrule 会将命令写入脚本并执行该脚本以解决此问题。这适用于所有 cmd 属性（cmd、cmd_bash、cmd_ps、cmd_bat）。
cmd_bash	字符串；默认值为 "" 要运行的 Bash 命令。 此属性的优先级高于 cmd。该命令会展开，并以与 cmd 属性完全相同的方式运行。
cmd_bat	字符串；默认值为 "" 要在 Windows 上运行的批处理命令。 此属性的优先级高于 cmd 和 cmd_bash。 该命令的运行方式与 cmd 属性类似，但存在以下差异： 此属性仅适用于 Windows。 该命令会使用以下默认实参运行 cmd.exe /c： /S - 剥离开头和结尾的引号，并按原样执行所有其他内容。 /E:ON - 启用扩展命令集。 /V:ON - 启用延迟变量扩展 /D - 忽略自动运行注册表条目。 在替换 $(location) 和 "Make" 变量后，路径将扩展为 Windows 样式的路径（带有反斜杠）。
cmd_ps	字符串；默认值为 "" 要在 Windows 上运行的 Powershell 命令。 此属性的优先级高于 cmd、cmd_bash 和 cmd_bat。该命令的运行方式与 cmd 属性类似，但存在以下差异： 此属性仅适用于 Windows。 该命令会使用 powershell.exe /c 运行。 为了让 Powershell 更易于使用且不易出错，我们在 genrule 中执行 Powershell 命令之前运行以下命令来设置环境。 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - 允许运行未签名的脚本。 $errorActionPreference='Stop' - 如果有多个命令以 ; 分隔，则当 PowerShell CmdLet 失败时，操作会立即退出，但这对外部命令不起作用。 $PSDefaultParameterValues['*:Encoding'] = 'utf8' - 将默认编码从 utf-16 更改为 utf-8。
executable	布尔值；不可配置；默认值为 False 声明输出可执行。 将此标志设置为 True 表示输出是可执行文件，可以使用 run 命令运行。在这种情况下，genrule 必须只生成一个输出。 如果设置了此属性，run 将尝试执行该文件，而无论其内容如何。 不支持为生成的执行文件声明数据依赖项。
local	布尔值；默认值为 False 如果设为 True，此选项会强制此 genrule 使用“本地”策略运行，这意味着不进行远程执行、不进行沙盒处理、不使用持久工作器。 这相当于提供“本地”作为标记 (tags=["local"])。
message	字符串；默认值为 "" 进度消息。 在执行此构建步骤时将打印的进度消息。默认情况下，消息为“正在生成输出”（或类似平淡无奇的内容），但您可以提供更具体的消息。请在 cmd 命令中使用此属性，而不是 echo 或其他打印语句，因为这样一来，构建工具就可以控制是否打印此类进度消息。
output_licenses	许可类型；默认值为 ["none"] 请参阅 common attributes
output_to_bindir	布尔值；不可配置；默认值为 False 如果设置为 True，此选项会导致输出文件写入 bin 目录，而不是 genfiles 目录。
tools	标签列表；默认值为 [] 相应规则的工具依赖项列表。如需了解详情，请参阅依赖项的定义。 构建系统会确保在运行 genrule 命令之前构建这些前提条件；它们是使用 exec 配置构建的，因为这些工具是作为构建的一部分执行的。可以使用 $(location //x:y) 获取各个 tools 目标 //x:y 的路径。 任何要由 cmd 执行的 *_binary 或工具都必须出现在此列表中，而不是 srcs 中，以确保它们以正确的配置构建。

starlark_doc_extract

查看规则来源

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() 会提取在给定 .bzl 或 .scl 文件中定义或重新导出的规则、函数（包括宏）、方面和提供程序的文档。此规则的输出是 ModuleInfo 二进制 proto，如 Bazel 源代码树中的 stardoc_output.proto 中所定义。

隐式输出目标

• name.binaryproto（默认输出）：ModuleInfo 二进制 proto。
• name.textproto（仅在明确请求时构建）：name.binaryproto 的文本 proto 版本。

警告：无法保证此规则的输出格式稳定。它主要供 Stardoc 内部使用。

参数

属性
name	名称；必需 相应目标的唯一名称。
deps	标签列表；默认值为 [] 封装了由 src load() 的 Starlark 文件的目标列表。这些目标在正常使用情况下应为 bzl_library 目标，但 starlark_doc_extract 规则不会强制执行此要求，而是接受在其 DefaultInfo 中提供 Starlark 文件的任何目标。 请注意，封装的 Starlark 文件必须是源树中的文件；Bazel 无法封装 load() 生成的文件。
src	标签；必需 要从中提取文档的 Starlark 文件。 请注意，这必须是源树中的文件；Bazel 无法处理 load() 生成的文件。
render_main_repo_name	布尔值；默认值为 False 如果为 true，则在包含代码库组件的已发布文档中呈现主代码库中的标签（换句话说，//foo:bar.bzl 将作为 @main_repo_name//foo:bar.bzl 发布）。 主代码库的名称从主代码库的 MODULE.bazel 文件（如果启用了 Bzlmod）中的 module(name = ...) 或主代码库的 WORKSPACE 文件中的 workspace(name = ...) 获取。 如果生成仅在同一代码库中使用的 Starlark 文件的文档，此属性应设置为 False；如果生成旨在从其他代码库中使用的 Starlark 文件的文档，此属性应设置为 True。
symbol_names	字符串列表；默认值为 [] 要提取文档的导出函数、规则、提供程序或方面（或它们嵌套在其中的结构）的限定名称的可选列表。在此，“限定名”是指实体向模块用户提供的名称，包括实体为实现命名空间而嵌套的任何结构体。 当且仅当以下情况时，starlark_doc_extract 会针对实体发出文档： 实体的完全限定名称的每个组成部分都是公开的（换句话说，完全限定名称的每个组成部分的第一个字符都是字母，而不是 "_"）；并且 或者 symbol_names 列表为空（默认情况），或者 实体的完全限定名或实体嵌套在其中的结构的完全限定名位于 symbol_names 列表中。

test_suite

查看规则来源

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite 定义了一组对人类而言“有用”的测试。这样一来，项目就可以定义一组测试，例如“签入前必须运行的测试”“项目的压力测试”或“所有小型测试”。blaze test 命令遵循这种组织结构：对于 blaze test //some/test:suite 之类的调用，Blaze 首先会枚举 //some/test:suite 目标以传递方式包含的所有测试目标（我们称之为“test_suite 扩展”），然后 Blaze 会构建并测试这些目标。

示例

用于运行当前软件包中的所有小型测试的测试套件。

test_suite(
    name = "small_tests",
    tags = ["small"],
)

运行指定的一组测试的测试套件：

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

用于运行当前软件包中所有非不稳定测试的测试套件。

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

参数

属性
name	名称；必需 相应目标的唯一名称。
tags	字符串列表；不可配置；默认值为 [] 文本标记的列表，例如“small”“database”或“-flaky”。标记可以是任何有效的字符串。 以“-”字符开头的标记被视为负标记。前面的“-”字符不被视为标记的一部分，因此“-small”的套装标记与测试的“small”尺寸匹配。所有其他标记都被视为正标记。 （可选）为了更明确地表示正面标记，标记也可以以“+”字符开头，该字符不会被视为标记文本的一部分进行评估。它只是让正负区分更容易阅读。 只有与所有正标记匹配且与任何负标记都不匹配的测试规则才会包含在测试套件中。请注意，这并不意味着跳过对已过滤掉的测试的依赖项的错误检查；跳过的测试的依赖项仍需合法（例如，不受可见性限制的阻止）。 manual 标记关键字的处理方式与上述不同，这是因为 blaze test 命令在涉及通配符目标模式的调用中执行了“测试套件扩展”。 在此处，标记为“手动”的 test_suite 目标会被过滤掉（因此不会进行扩展）。此行为与 blaze build 和 blaze test 处理通配符目标模式的方式一致。请注意，这与 blaze query 'tests(E)' 的行为方式明显不同，因为无论 manual 标记如何，tests 查询函数始终会展开套件。 请注意，测试的 size 会被视为过滤目的的标记。 如果您需要一个包含具有互斥标记的测试（例如，所有小型测试和中型测试）的 test_suite，则必须创建三条 test_suite 规则：一条用于所有小型测试，一条用于所有中型测试，一条包含前两条规则。
tests	标签列表；不可配置；默认值为 [] 任何语言的测试套件和测试目标列表。 此处接受任何 *_test，与语言无关。不过，即使 *_binary 目标恰好运行了测试，也不会被接受。 仅针对此属性中直接列出的测试按指定的 tags 进行过滤。如果此属性包含 test_suite，则这些 test_suite 内的测试不会被此 test_suite 过滤（它们被视为已过滤）。 如果未指定或为空，该规则将默认包含当前 BUILD 文件中未标记为 manual 的所有测试规则。tests这些规则仍受 tag 过滤条件的限制。