一般规则

规则

别名

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

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

别名仅适用于“常规”目标。特别是,package_grouptest_suite 不能有别名。

别名规则有自己的可见性声明。在所有其他方面,它的行为方式与它引用的规则类似(例如,系统会忽略 testonly 别名,改用所引用规则的 testonly 性),但有一些细微的例外情况:

  • 如果命令行中提及了相应别名,测试不会运行。如需定义运行所引用测试的别名,请使用 test_suite 规则,且该规则的 tests 属性中包含一个目标。
  • 定义环境组时,不支持为 environment 规则指定别名。--target_environment 命令行选项也不支持它们。

示例

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

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

参数

属性
name

Name; required

此目标的唯一名称。

actual

Label; required

此别名所指的目标。它不必是规则,也可以是输入文件。

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 为目标并应用自定义定义 FOO=bar(例如 bazel build --cpu=arm --define FOO=bar ...)的 build:

  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_25constraint_value)。请注意,如果平台定义了这两个值以外的其他约束值,则平台仍然匹配。

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  
在所有这些情况下,配置都可能会在 build 中发生更改,例如,如果需要针对与其依赖项不同的平台构建目标。这意味着,即使 config_setting 与顶级命令行标志不匹配,它仍然可能匹配某些构建目标。

备注

  • 如需了解当多个 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,bios_multi_cpus=a --ios_multi_cpus=b 都会生成 ["a", "b"]。请检查标志定义并仔细测试您的条件,以验证确切预期。

  • 如果您需要定义不通过内置构建标志建模的条件,请使用 Starlark 定义的标志。您也可以使用 --define,但这种方法提供的支持较弱,因此不推荐使用。如需查看更多讨论,请点击此处
  • 避免在不同软件包中重复使用相同的 config_setting 定义。请改为引用规范软件包中定义的通用 config_setting
  • valuesdefine_valuesconstraint_values 可在同一 config_setting 中以任意组合使用,但必须至少为任何指定的 config_setting 设置一个。

参数

属性
name

Name; required

此目标的唯一名称。

constraint_values

List of labels; optional; nonconfigurable

目标平台为了匹配此 config_setting 而必须指定的最小 constraint_values 集。(此处未考虑执行平台。)平台已忽略的所有其他限制条件值都会被忽略。如需了解详情,请参阅 可配置的 build 属性

如果两个 config_setting 在同一 select 中匹配,则系统不会考虑此属性来确定其中一个 config_setting 是否为另一个 config_setting 的特化。换言之,一个config_setting平台与另一个平台的匹配程度不亚于另一个平台。

define_values

Dictionary: String -> String; optional; nonconfigurable

values 相同,但专门用于 --define 标志。

--define 很特殊,因为从 Bazel 标志的角度来看,其语法 (--define KEY=VAL) 表示 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

Dictionary: label -> String; optional; nonconfigurable

values 相同,但适用于 用户定义的 build 标志

这是一个不同的属性,因为用户定义的标志以标签的形式引用,而内置标志以任意字符串的形式引用。

values

Dictionary: String -> String; optional; nonconfigurable

与此规则匹配的一组配置值(以 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(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

Name; required

此目标的唯一名称。

srcs

List of labels; optional

作为文件组成员的目标的列表。

通常使用 glob 表达式的结果作为 srcs 属性的值。

data

List of labels; optional

此规则在运行时所需的文件列表。

data 属性中指定的目标将添加到此 filegroup 规则的 runfiles 中。在另一条规则的 data 属性中引用 filegroup 时,其 runfiles 会添加到依赖规则的 runfiles 中。如需详细了解如何依赖和使用数据文件,请参阅数据依赖项部分和 data 的常规文档

output_group

String; optional

用于从来源收集工件的输出组。如果指定了此属性,则将导出依赖项的指定输出组中的工件,而不是默认输出组。

“输出组”是目标的输出工件类别,在规则的实现中指定。

genquery

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

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

为了确保构建的一致性,系统只允许查询访问 scope 属性中指定的目标的传递闭包。如果 strict 未指定或为 true,违反此规则的查询将在执行期间失败(如果 strict 为 false,系统会直接跳过超出范围的目标并显示警告)。要确保不会发生这种情况,最简单的方法是在作用域内提及与查询表达式中相同的标签。

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

genquery 的输出使用 --order_output=full 进行排序,以强制执行确定性输出。

输出文件的名称即为规则的名称。

示例

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

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

参数

属性
name

Name; required

此目标的唯一名称。

expression

String; required

要执行的查询。与命令行和 BUILD 文件中的其他位置相反,此处的标签是相对于工作区的根目录进行解析的。例如,在 a/BUILD 文件中,此属性中的标签 :b 会引用目标 //:b
opts

List of strings; optional

传递给查询引擎的选项。这些选项对应于可以传递给 bazel query 的命令行选项。不允许在此处使用某些查询选项:--keep_going--query_file--universe_scope--order_results--order_output。此处未指定的选项将具有其默认值,就像在命令行中 bazel query 一样。
scope

null; required

查询的范围。不允许查询触摸这些目标的传递闭包之外的目标。
strict

Boolean; optional; default is 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, exec_tools, 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 用于运行测试。测试和测试结果存在特殊分配,包括缓存政策和环境变量。测试通常需要在构建完成后并在目标架构上运行,而 Genrule 在构建期间和主机架构上执行(两者可能有所不同)。如果您需要通用测试规则,请使用 sh_test

交叉编译注意事项

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

虽然 Genrule 在构建期间运行,但其输出通常在构建后用于部署或测试。请考虑为微控制器编译 C 代码的示例:编译器接受 C 源文件并生成可在微控制器上运行的代码。很明显,生成的代码无法在用于构建代码的 CPU 上运行,但 C 编译器(如果从源代码编译)本身却必须如此。

构建系统使用主机配置来描述运行 build 的机器,并使用目标配置来描述应该运行 build 的输出的机器。它提供了用于配置上述各项的选项,并将相应的文件隔离到了单独的目录中,以避免冲突。

对于 genrules,构建系统确保正确构建依赖项:针对目标配置构建 srcs(如有必要),针对主机配置构建 tools,而输出则被视为目标配置。它还提供 Make 变量,genrule 命令可将其传递给相应工具。

我们特意没有定义任何 deps 属性:其他内置规则会使用在规则之间传递的依赖于语言的元信息来自动确定如何处理依赖规则,但这种自动化程度不适用于 genrule。Genrule 仅在文件和 runfile 级别工作。

特殊情况

主机-主机编译:在某些情况下,构建系统需要运行 Genrule,以便在构建期间执行输出。例如,如果一个 genrule 构建了一些自定义编译器,随后另一个 genrule 将使用它,那么第一个 genrule 必须为主机配置生成其输出,因为编译器将在另一个 genrule 中运行。在这种情况下,构建系统会自动执行正确的操作:它会为主机配置(而不是目标配置)构建第一个 Genrule 的 srcsouts。如需了解详情,请参阅用户手册

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

Genrule 环境

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

构建工具会在经过净化的进程环境中执行 Bash 命令,该进程环境仅定义 PATHPWDTMPDIR 等核心变量。 为了确保 build 的可重现性,系统不会将用户 shell 环境中定义的大多数变量传递给 genrule 的命令。不过,Bazel(而不是 Blaze)会传递用户的 PATH 环境变量的值。对 PATH 的值所做的任何更改都将导致 Bazel 在下次构建时重新执行该命令。

genrule 命令不应访问网络,除非连接是命令本身的子进程,但目前并未强制要求这样做。

构建系统会自动删除所有现有的输出文件,但会在运行 genrule 之前创建所有必要的父级目录。如果失败,它还会移除所有输出文件。

一般建议

  • 请确保由 Genrule 运行的工具是确定的并且是封闭的。它们不应将时间戳写入输出,对集和映射使用稳定排序,并且只将相对文件路径写入输出,而不写入绝对路径。不遵循此规则将导致意外的构建行为(Bazel 不会重新构建您预期的 genrule),并降低缓存性能。
  • 对于输出、工具和源代码,请广泛使用 $(location)。由于不同配置的输出文件是隔离的,因此 Genrule 无法依赖于硬编码路径和/或绝对路径。
  • 请编写一个通用的 Starlark 宏,以防在多个位置使用相同或非常相似的 Genrule。如果 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 不会复制由 genrules 创建的目录/符号链接结构,并且对目录的依赖项检查不正常。
  • 在其他规则中引用 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

Name; required

此目标的唯一名称。


您可以在其他 BUILD 规则的 srcsdeps 部分按名称引用此规则。如果规则会生成源文件,您应使用 srcs 属性。
srcs

List of labels; optional

此规则的输入列表,例如要处理的源文件。

此属性不适合列出由 cmd 执行的工具;请为这些工具改用 tools 属性。

构建系统可确保在运行 genrule 命令之前构建这些前提条件;使用与原始构建请求相同的配置进行构建。这些前提条件的文件的名称在 $(SRCS) 中以空格分隔的列表的形式提供给命令;或者,您也可以使用 $(location //x:y)$<(如果它是 srcs 中的唯一条目)获取单个 srcs 目标 //x:y 的路径。

outs

List of filenames; required; nonconfigurable

此规则生成的文件列表。

输出文件不得跨越软件包边界。 输出文件名会被解释为相对于软件包。

如果设置了 executable 标志,则 outs 必须正好包含一个标签。

genrule 命令应在预定位置创建每个输出文件。位置信息可在 cmd 中使用 Genrule 专用“Make”变量$@$(OUTS)$(@D) $(RULEDIR))或使用 $(location) 替换获得。

cmd

String; optional

要运行的命令。 可以使用 $(location) “Make”变量替换。
  1. 应用第一次 $(location) 替换,替换所有出现的 $(location label)$(locations label)(以及使用相关变量 execpathexecpathsrootpathrootpaths 的类似构造)。
  2. 接下来,系统会展开“Make”变量。请注意,预定义变量 $(JAVA)$(JAVAC)$(JAVABASE) 会在主机配置下展开,因此作为构建步骤的一部分运行的 Java 调用可以正确加载共享库和其他依赖项。
  3. 最后,使用 Bash shell 执行生成的命令。如果其退出代码不为零,则认为该命令已失败。
这是 cmd_bashcmd_pscmd_bat 的回退(如果它们都不适用)。

如果命令行长度超过平台限制(在 Linux/macOS 上为 64K,在 Windows 上为 8K),那么 genrule 会将命令写入脚本并执行该脚本来解决问题。这适用于所有 cmd 属性(cmdcmd_bashcmd_pscmd_bat)。

cmd_bash

String; optional

要运行的 Bash 命令。

此属性的优先级高于 cmd。该命令会展开,其运行方式与 cmd 属性完全相同。

cmd_bat

String; optional

要在 Windows 上运行的 Batch 命令。

此属性的优先级高于 cmdcmd_bash。该命令的运行方式与 cmd 属性类似,但存在以下差异:

  • 此属性仅适用于 Windows。
  • 该命令通过带有以下默认参数的 cmd.exe /c 运行:
    • /S - 去掉名字和最后一个引号,并按原样执行其他所有操作。
    • /E:ON - 启用扩展命令集。
    • /V:ON - 启用延迟变量扩展
    • /D - 忽略 AutoRun 注册表条目。
  • 替换 $(location)“Make”变量后,路径将扩展为 Windows 样式路径(带反斜杠)。
cmd_ps

String; optional

要在 Windows 上运行的 Powershell 命令。

此属性的优先级高于 cmdcmd_bashcmd_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。
exec_tools

List of labels; optional

此规则的 tool 依赖项列表。此属性的行为与 tools 属性完全相同,只不过将针对规则的执行平台(而不是主机配置)配置这些依赖项。这意味着,exec_tools 中的依赖项不会像 tools 中的依赖项受到相同的限制。特别是,它们不需要将主机配置用于自己的传递依赖项。如需了解详情,请参阅 tools

Blaze 团队正在迁移对 tools 的所有使用以使用 exec_tools 语义。我们建议用户优先选择 exec_tools 而不是 tools,这样不会导致任何问题。功能迁移完成后,我们可以将 exec_tools 重命名为 tools。在发生这种情况之前,您会收到弃用警告和迁移说明。

executable

Boolean; optional; nonconfigurable; default is False

将输出声明为可执行。

如果将此标志设为 True,输出结果是可执行文件,可以使用 run 命令运行。在这种情况下,genrule 必须仅生成一个输出。如果设置了此属性,run 将尝试执行文件,而不考虑其内容。

不支持为生成的可执行文件声明数据依赖项。

local

Boolean; optional; default is False

如果设置为 True,此选项会强制此 genrule 使用“本地”策略运行,这意味着没有远程执行、没有沙盒化和永久性工作器。

这相当于提供“local”作为标记 (tags=["local"])。

message

String; optional

进度消息。

执行此构建步骤时会输出的进度消息。默认情况下,消息为“正在生成输出”(或同样平淡的内容),但您可以提供更具体的消息。在 cmd 命令中使用此属性,而不要使用 echo 或其他输出语句,因为这样,构建工具就可以控制是否输出此类进度消息。

output_licenses

Licence type; optional

请参阅 common attributes
output_to_bindir

Boolean; optional; nonconfigurable; default is False

如果设置为 True,此选项会使输出文件写入 bin 目录,而不是 genfiles 目录。

tools

List of labels; optional

此规则的 tool 依赖项列表。如需了解详情,请参阅依赖项的定义。

构建系统可确保在运行 genrule 命令之前构建这些前提条件;使用 host 配置构建这些前提条件,因为这些工具是在构建过程中执行的。可以使用 $(location //x:y) 获取各个 tools 目标 //x:y 的路径。

cmd 要执行的任何 *_binary 或工具都必须显示在此列表中,而不是出现在 srcs 中,以确保它们是在正确的配置中构建的。

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

Name; required

此目标的唯一名称。

tags

List of strings; optional; nonconfigurable

文本标记列表,例如“small”“database”或“-flaky”。标记可以是任何有效的字符串。

以“-”字符开头的代码会被视为否定关键字。前面的“-”字符不会被视为该标记的一部分,因此“-small”套件标记与测试的“small”大小匹配。所有其他标记均被视为肯定标记。

(可选)为了让肯定标记更加明确,标记也可以以“+”字符开头,但该字符不会作为标记文本的一部分进行评估。而只会让正面和负面的区别更易于阅读。

测试套件仅包含与所有正例标记而任何否定标记匹配的测试规则。请注意,这并不意味着系统会跳过对已过滤掉的测试的依赖关系的错误检查;对已跳过测试的依赖关系仍然需要保持合法(例如,不会因可见性限制而阻止)。

对于涉及通配符目标模式的调用,blaze test 命令执行“test_suite 扩展”后,系统处理 manual 标记关键字的方式与上文不同。 这样,系统会过滤掉标记为“manual”的 test_suite 目标(因此不会展开)。此行为与 blaze buildblaze test 处理通配符目标模式的总体方式一致。请注意,这与 blaze query 'tests(E)' 的行为方式明显不同,因为套件始终由 tests 查询函数扩展,而不管 manual 标记为何。

请注意,测试的 size 被视为用于过滤的标记。

如果您需要的 test_suite 中包含带有互斥标记的测试(例如所有小型和中型测试),则必须创建三条 test_suite 规则:一条适用于所有小型测试,一条用于所有中型测试,另一条包含前两条规则。

tests

List of labels; optional; nonconfigurable

各种语言的测试套件和测试目标的列表。

无论使用哪种语言,此处接受任何 *_test。不过,不接受任何 *_binary 目标,即使它们恰好在运行测试也是如此。只有直接列在此属性中的测试才会按指定的 tags 进行过滤。如果此属性包含 test_suite,则其中的测试将不会通过此 test_suite 进行过滤(它们会被视为已被滤除)。

如果 tests 属性未指定或为空,该规则默认包含当前 BUILD 文件中未标记为 manual 的所有测试规则。这些规则仍需通过 tag 过滤。