一般规则

规则

• 别名
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

alias

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",
)

参数

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 的任何 build 匹配（在命令行中显式设置，或通过 .bazelrc 文件隐式设置）：

  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_25 的 constraint_value。请注意，即使平台定义了除这两个值之外的其他限制条件值，也仍会匹配。

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

备注

• 如需了解当多个 config_setting 与当前配置状态匹配时会发生什么情况，请参阅 select。
• 对于支持简写形式的标志（例如 --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，必须设置至少一个。

参数

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

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",
    ],
)

参数

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"],
)

参数

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 运行测试。系统会对测试和测试结果（包括缓存政策和环境变量）提供特殊豁免。测试通常需要在构建完成后在目标架构上运行，而 genrule 则在构建期间在执行架构上执行（这两者可能不同）。如果您需要通用测试规则，请使用 sh_test。

交叉编译注意事项

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

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

构建系统使用 exec 配置来描述构建运行的机器，并使用目标配置来描述构建输出应运行的机器。它提供了配置每种类型的选项，并将相应的文件分隔到单独的目录中，以避免冲突。

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

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

特殊情况

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

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

Genrule 环境

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

构建工具会在经过净化的进程环境中执行 Bash 命令，该环境仅定义 PATH、PWD、TMPDIR 等核心变量以及其他一些变量。 为确保 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 不会复制 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) > $@",
)

参数

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 在内部使用。

参数

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"],
)

参数