一般规则

报告问题 查看源代码 每晚 · 7.2 条 · 7.1 · 7.0敬上 · 6.5 · 6.4

规则

• <ph type="x-smartling-placeholder"></ph> 别名
• <ph type="x-smartling-placeholder"></ph> config_setting
• <ph type="x-smartling-placeholder"></ph> 文件组
• <ph type="x-smartling-placeholder"></ph> Genquery
• <ph type="x-smartling-placeholder"></ph> Genrule
• <ph type="x-smartling-placeholder"></ph> starlark_doc_extract
• <ph type="x-smartling-placeholder"></ph> test_suite

别名

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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

alias 规则会创建另一个可以在规则中引用的名称。

混叠仅适用于“常规”目标。具体而言，package_group 和 test_suite 不能别名。

在大型代码库中，如果重命名目标，则别名会很有用 更改大量文件。您还可以使用别名规则 select 函数调用（如果您想对该逻辑重复使用该逻辑） 多个目标。

别名规则有自己的可见性声明。在所有其他方面 与其引用的规则相同（例如 testonly on the alias会被忽略；testonly-ness ），但也有一些例外情况：

• 如果命令行中提到了测试的别名，则测试不会运行。定义别名 运行所引用的测试，请使用 test_suite 在其 tests 中具有单个目标的规则 属性。
• 定义环境组时，environment 规则的别名 支持。它们在 --target_environment 命令行中不受支持 选项。

示例

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

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

参数

属性
name	姓名；必需 此目标的唯一名称。
actual	标签；必需 此别名所指的目标。它不要求是规则，也可以作为输入 文件。

config_setting

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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 文件中隐式指定）：

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

以下内容与以 ARM 并应用自定义定义的任何 build 匹配 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 文件）：

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

以下内容匹配任何以具有 x86_64 架构和 glibc 的平台为目标的 build 版本 2.25，假设存在带有标签的 constraint_value //example:glibc_2_25。请注意，如果平台定义了额外的 限制值。

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

在所有这些情况下，配置可能会在 build 中发生变化，例如， 需要针对与其依赖项不同的平台构建目标。这意味着，即使 config_setting 与顶级命令行标志不匹配，它可能仍然匹配 一些构建目标。

备注

• 请参阅 select，了解 config_setting 与当前配置状态匹配。
• 对于支持简写形式的标志（例如 --compilation_mode 与 -c），values 定义必须使用完整形式。这些 使用任一形式匹配调用。
• 如果标志接受多个值（如 --copt=-Da --copt=-Db 或列表类型值） <ph type="x-smartling-placeholder"></ph> Starlark flag），如果 "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"]。检查标志定义并测试 请仔细判断是否确实符合预期。

• 如果您需要定义未通过内置构建标志建模的条件，请使用 <ph type="x-smartling-placeholder"></ph> Starlark 定义的标志。您也可以使用 --define，但这种方式效果更好 支持，不推荐使用。请参阅 此处。
• 避免在不同软件包中重复相同的 config_setting 定义。 请改为引用规范软件包中定义的常用 config_setting。
• values, define_values和 constraint_values 可在同一 config_setting 中任意组合使用，但必须至少提供一个 为任何给定的 config_setting 设置。

参数

属性
name	姓名；必需 此目标的唯一名称。
constraint_values	标签列表；不可配置；默认值为 [] 目标平台必须指定的最小 constraint_values 集 才能匹配此config_setting。（执行平台不是 ）。平台已忽略的所有其他限制条件值都会被忽略。请参阅 <ph type="x-smartling-placeholder"></ph> 可配置的 build 属性了解详情。 两个 config_setting 都在同一处匹配的情况下 select，则不考虑此属性来确定 指示其中一个 config_setting 是否是另一个的专用属性。在其他 字词，一个 config_setting 的匹配程度不能比另一个更强。
define_values	字典：String ->String;不可配置；默认值为 {} 与values相同，但 专门用于 --define 标志。 --define 之所以特殊，是因为它的语法 (--define KEY=VAL) 表示 KEY=VAL 是一个 Bazel 标志的值。 这意味着： 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	字典：label ->String;不可配置；默认值为 {} 与values相同，但 用于“” 用户定义的 build 标志。 这是一个独特的属性，因为用户定义的标志被引用为标签，而 以任意字符串形式引用。
values	字典：String ->String;不可配置；默认值为 {} 与此规则匹配的一组配置值（表示为 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 ...），则匹配： 其中任一设置是匹配的。

文件组

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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 来 grovel 测试数据目录：

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。当 在以下页面的 data 属性中引用了 filegroup： 其runfiles将被添加到runfiles中 规则集请参阅数据依赖关系 部分和关于 data，详细了解如何依赖和使用数据文件。
output_group	String;默认值为 "" 要从来源收集制品的输出组。如果该属性为 指定依赖项后，系统将导出该依赖项的指定输出组中的制品 而不是默认输出组 “输出组”是目标输出工件的类别， 规则的实施。

Genquery

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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	Boolean;默认值为 False 如果为 True，则查询输出将以 GZIP 文件格式编写。此设置可用于 在预计查询输出会很大时，避免 Bazel 的内存使用量激增。Bazel 已在内部压缩超过 2^20 个字节的查询输出，无论 此设置的值，因此将其设置为 True 可能不会减少保留 堆。不过，它允许 Bazel 在写入输出文件时跳过解压缩， 这可能需要大量内存
expression	String;必需 要执行的查询。与命令行和 BUILD 文件中的其他位置不同， 此处的标签相对于工作区根目录进行解析。例如， a/BUILD 文件中此属性中的标签 :b 引用的是 定位//:b。
opts	字符串列表；默认值为 [] 传递给查询引擎的选项。它们对应于命令行 传递给 bazel query 的选项。不允许使用某些查询选项 此处：--keep_going、--query_file、--universe_scope --order_results 和 --order_output。此处未指定选项 将具有默认值，就像在 bazel query 的命令行中一样。
scope	标签列表；必需 查询的范围。不允许查询触摸传递词之外的目标 关闭这些目标。
strict	Boolean;默认值为 True 如果为 true，目标查询逃脱了其作用域传递闭包操作的目标将无法 build。如果为 false，Bazel 将输出警告，并跳过导致它在外部的任何查询路径 同时完成查询的其余部分。

Genrule

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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 是通用的构建规则，如果没有适用于任务的特定规则，则可以使用它们。 例如，您可以运行 Bash 一行代码。但是，如果您需要编译 C++ 文件， 现有的 cc_* 规则，因为所有繁杂的工作都已经完成 。

请注意，genrule 需要 shell 来解释命令参数。 引用 PATH 上提供的任意程序也很容易，但这使得 命令是非封闭的，并且可能无法重现。 如果您只需运行一种工具，可以考虑使用 run_binary 。

请勿使用 Genrule 来运行测试。测试和测试有特殊的方案 包括缓存政策和环境变量。通常需要运行测试 构建完成后在目标架构上执行，而 Genrule 在 build 和 exec 架构上（两者可能不同）。如果您需要通用型 测试规则，请使用 sh_test。

交叉编译注意事项

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

虽然 Genrule 在构建期间运行，但其输出通常在构建之后用于部署或 测试。请考虑为微控制器编译 C 代码的示例：编译器接受 C 源文件，并生成在微控制器上运行的代码。生成的代码很明显 不能在用于构建它的 CPU 上运行，但可以在 C 编译器（如果从源代码编译）上运行 。

构建系统使用 exec 配置来描述运行 build 的机器 和目标配置，用于描述生成 build 输出的机器 投放时间它提供了用于配置上述各项的选项，并将 将对应的文件放入单独的目录中，以避免冲突。

对于 Genrule，构建系统可确保正确构建依赖项： srcs 是为 target 配置构建的（如有必要）， tools 是针对 exec 配置构建的，且输出被视为 适用于 target 配置。它还提供 “制作”变量。

Genrule 有意不定义 deps 属性：其他内置规则使用 在规则之间传递与语言的元信息，以自动确定如何 处理依赖的规则，但 Genrule 无法实现这种级别的自动化。Genrule 的工作原理 而不是在命令行级别运行

特殊情况

Exec-exec 编译：在某些情况下，构建系统需要运行 genrule，以便 也可以在构建期间执行输出例如，如果 Genrule 构建了一些自定义编译器 随后另一个 Genrule 会使用它，第一个 Genrule 必须为其生成输出 exec 配置，因为编译器将在另一个 genrule 中运行该配置。在此示例中 构建系统会自动执行正确的操作：构建 srcs 并 exec 配置（而非目标）的第一个 Genrule 的 outs 配置。如需了解详情，请参阅用户手册 信息。

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

Genrule 环境

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

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

genrule 命令不应访问网络，除非连接 命令本身的子项（尽管目前未强制执行）。

构建系统会自动删除所有现有的输出文件，但会创建所有必要的父文件 然后再运行 Genrule。如果测试失败，此 API 还会移除所有输出文件。

一般建议

• 确保由 Genrule 运行的工具具有确定性和封闭性。用户不应写入 时间戳，并且应该对集和映射使用稳定的排序， 只写入输出的相对文件路径，不写入绝对路径。不遵守此规则会导致 导致意外的构建行为（Bazel 不会重新构建您原本认为会的 Genrule），并且 会降低缓存性能
• 对于输出、工具和源代码，广泛使用 $(location)。由于 为不同配置隔离输出文件，genrule 不能依赖于硬编码 和/或绝对路径
• 请务必编写一个常见的 Starlark 宏，以防在 多个位置。如果 Genrule 比较复杂，请考虑在脚本中或以 星罗克法则。这可以提高可读性和可测试性。
• 确保退出代码正确指示 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) 中的空格分隔列表；也可以选择某个人 srcs 目标 //x:y 可通过使用 $(location //x:y) 或 $< 获取，前提是它是 srcs。
outs	filenames 列表；不可配置；必需 此规则生成的文件的列表。 输出文件不得跨越软件包边界。 输出文件名被解释为相对于文件包。 如果设置了 executable 标志，则 outs 必须正好包含一个 标签。 genrule 命令应在预定位置创建每个输出文件。 该位置通过 genrule 专用的“Make”在 cmd 中提供 变量（$@、$(OUTS)、$(@D) 或 $(RULEDIR)）或使用 $(location)替换。
cmd	String;默认值为 "" 要运行的命令。 受$(location) 和“品牌”的约束变量替换。 应用第一个 $(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	String;默认值为 "" 要运行的 Bash 命令。 此属性的优先级高于 cmd。该命令已展开 运行方式与 cmd 属性完全相同。
cmd_bat	String;默认值为 "" 要在 Windows 上运行的批处理命令。 此属性的优先级高于 cmd 和 cmd_bash。 该命令的运行方式与 cmd 属性类似， 以下差异： 此属性仅适用于 Windows。 该命令使用具有以下默认参数的 cmd.exe /c 运行： <ph type="x-smartling-placeholder"> </ph> /S - 去除第一个引号和最后一个引号，并按原样执行所有其他内容。 /E:ON - 启用扩展命令集。 /V:ON - 启用延迟变量扩展 /D - 忽略 AutoRun 注册表条目。 $(location)和之后 “创作”变量替换，路径将是 扩展为 Windows 样式路径（使用反斜杠）。
cmd_ps	String;默认值为 "" 要在 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	Boolean;不可配置；默认值为 False 将输出声明为可执行文件。 将此标志设置为 True 表示输出是可执行文件，可以使用 run 命令。在这种情况下，genrule 必须正好生成一个输出。 如果设置了此属性，则无论何种原因，run 都会尝试执行该文件 其内容。 不支持为生成的可执行文件声明数据依赖项。
local	Boolean;默认值为 False 如果设置为 True，此选项会强制此 genrule 使用“local” 策略，这意味着无需远程执行、没有沙盒和永久性工作器。 这相当于提供“本地”以标记 (tags=["local"]) 表示。
message	String;默认值为 "" 进度消息。 执行此构建步骤时将输出的进度消息。默认情况下， 消息为“生成输出”（或者是同样平淡无奇的），但您可以提供 更具体的一个。请使用此属性，而不要使用 echo 或其他印刷品 语句，因为这样构建工具才能控制cmd 是否输出此类进度消息。
output_licenses	许可类型；默认值为 ["none"] 请参阅 common attributes
output_to_bindir	Boolean;不可配置；默认值为 False 如果设置为 True，此选项会将输出文件写入 bin 而不是 genfiles 目录下。
tools	标签列表；默认值为 [] 此规则的 tool 依赖项列表。查看 依赖项。 构建系统确保在运行 genrule 命令之前已构建这些前提条件； 它们是使用 exec 构建的， 配置，因为这些工具是作为构建的一部分执行的。一个 单个tools目标//x:y可以使用 $(location //x:y)。 任何要由 cmd 执行的 *_binary 或工具都必须显示在此 列表，而不是在 srcs 中，以确保以正确的配置构建它们。

starlark_doc_extract

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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，如所定义 在 stardoc_output.proto 在 Bazel 源代码树中

隐式输出目标

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

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

参数

属性
name	姓名；必需 此目标的唯一名称。
deps	标签列表；默认值为 [] 封装 Starlark 文件的目标列表，load() src。在正常使用的情况下，这些目标应该 bzl_library 目标，但 starlark_doc_extract 规则不强制执行该规则，而是接受 在其 DefaultInfo 中提供 Starlark 文件的任何目标。 请注意，封装的 Starlark 文件必须是源代码树中的文件；Bazel 不能 load() 个生成的文件。
src	标签；必需 要从中提取文档的 Starlark 文件。 请注意，它必须是源代码树中的一个文件；Bazel 无法load() 生成的文件
render_main_repo_name	Boolean;默认值为 False 如果为 true，则使用代码库组件在发出的文档的主代码库中呈现标签 （也就是说，//foo:bar.bzl 将作为 @main_repo_name//foo:bar.bzl）。 主代码库使用的名称是从 module(name = ...) 获取的 在主代码库的 MODULE.bazel 文件中（如果已启用 Bzlmod），或者从 workspace(name = ...) 添加到主代码库的 WORKSPACE 文件中。 在为以下各项生成文档时，应将此属性设置为 False 仅可在同一仓库中使用的 Starlark 文件，以及 True 其他代码库中使用的资源
symbol_names	字符串列表；默认值为 [] 导出函数、规则、提供程序或切面（或 结构体）中提取文档。在这里，一个合格的 name 表示实体可供模块用户使用的名称， 包括嵌套了该实体来实现命名空间的任何结构体。 当且仅当满足以下条件时，starlark_doc_extract 才会发出实体的文档 实体限定名称的每个组成部分都是公共的（也就是说，第一个 限定名称的每个组成部分均按字母顺序排列，而非 "_"); 和 symbol_names 列表为空（这是默认值） 大小写），或 实体的限定名称，或者实体在其中实体的 已嵌套，位于 symbol_names 列表中。

test_suite

<ph type="x-smartling-placeholder"></ph> 查看规则来源

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_suiteexpand”）），然后 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”或“数据库”或“-flaky”标记可以是任何有效字符串。 以“-”开头的标签字符被视为否定关键字。通过 “-”前面字符不会被视为代码的一部分，因此套件代码 的“-small”与测试的“small”匹配。系统会将所有其他代码 肯定标记。 （可选）为使正面标记更加明确，还可以以 “+”字符，因此系统不会将其作为代码文本的一部分进行评估。它 只是使正面和负面的区别更易于阅读。 仅测试与所有肯定标记且不匹配任何否定标记的规则 代码将包含在测试套件中请注意，这并不意味着 会跳过对过滤掉的测试的依赖项；跳过的依赖项 测试仍然需要合法（例如，不会被可见性限制阻止）。 manual 标记关键字的处理方式与上述标记不同， “test_suite 扩展”调用时由 blaze test 命令执行 涉及通配符 目标模式。 其中包括 test_suite 个标记为“人工”的目标会被滤除 展开）。此行为与 blaze build 和 blaze test 通常用于处理通配符目标模式。请注意，这是 与 blaze query 'tests(E)' 的行为方式明显不同，因为套件 始终由 tests 查询函数展开，而不管 manual 标记之间。 请注意，测试的 size 会被视为用于过滤的标记。 如果您需要一个包含具有互斥标记的测试的 test_suite （例如，所有中小型测试），则必须创建三个 test_suite 一条规则适用于所有小型测试，一条适用于所有中型测试，一条包含 前两行。
tests	标签列表；不可配置；默认值为 [] 任意语言的测试套件和测试目标的列表。 此处接受任何*_test，与语言无关。否 不过，系统会接受 *_binary 目标，即使它们恰好运行测试也是如此。 只能按指定的 tags 过滤直接 此属性中。如果此属性包含 test_suite，则其中包含的测试 将不会按照此test_suite进行过滤（它们会被视为 ）。 如果 tests 属性未指定或为空，则规则将默认为 包括当前 BUILD 文件中未标记为 manual。这些规则仍要应用“tag”过滤条件。