“Make”变量

“Make”变量是展开式字符串变量的一个特殊的类，可用于标记为 "Subject to 'Make variable' substitution" 的属性。

例如，它们可用于将特定的工具链路径注入用户构建的构建操作。

Bazel 提供了预定义变量（适用于所有目标）和自定义变量（在依赖项目标中定义，并且仅适用于依赖于这些目标的目标）。

使用“Make”这一术语的原因是历史：这些变量的语法和语义最初旨在与 GNU Make 匹配。

使用

标记为 "Subject to 'Make variable' substitution" 的属性可引用“Make”变量 FOO，如下所示：

my_attr = "prefix $(FOO) suffix"

换句话说，任何与 $(FOO) 匹配的子字符串都会扩展为 FOO 的值。如果该值为 "bar"，则最终字符串将变为：

my_attr = "prefix bar suffix"

如果 FOO 与使用方目标已知的变量不对应，Bazel 会失败并显示错误。

名称为非字母符号（如 @）的“Make”变量也可仅使用美元符号（不带括号）进行引用。例如：

my_attr = "prefix $@ suffix"

如需将 $ 编写为字符串字面量（即为了防止变量扩展），请编写 $$。

预定义变量

在任何目标上，任何标记为“Subject to 'Make variable' substitution”的任何属性都可以引用预定义的“Make”变量。

如需查看这些变量的列表以及它们针对一组给定构建选项的值，请运行以下命令：

bazel info --show_make_env [build options]

然后看看输出中各个行的大写字母。

查看预定义变量示例。

工具链选项变量

  • COMPILATION_MODE：fastbuild、dbg 或 opt。（了解详情）

路径变量

  • BINDIR：为目标架构生成的二进制树的基。

    请注意，在构建期间在主机架构上运行的程序可以使用不同的树来支持交叉编译。

    如果要从 genrule 中运行工具，建议采用 $(execpath toolname) 来获取其路径，其中 toolname 必须在 genrule 的 tools 属性中列出。

  • GENDIR：为目标架构生成的代码树的基础。

机器架构变量

  • TARGET_CPU：目标架构的 CPU，例如 k8。

预定义的 Genrule 变量

以下内容专门用于 genrule 的 cmd 属性，通常对于使该属性正常运行非常重要。

查看预定义的 genrule 变量示例。

  • OUTS：genrule 的 outs 列表。如果您只有一个输出文件，还可以使用 $@。
  • SRCS：genrule 的 srcs 列表（或更确切地说：与 srcs 列表中的标签对应的文件的路径名）。 如果您只有一个源文件，还可以使用 $<。
  • <：SRCS（如果它是单个文件）。否则会触发构建错误。
  • @：OUTS（如果它是单个文件）。否则会触发构建错误。

  • RULEDIR：目标的输出目录，即 genfiles 或 bin 树下包含目标的软件包的名称对应的目录。对于 //my/pkg:my_genrule，结尾始终是 my/pkg，即使 //my/pkg:my_genrule 的输出位于子目录中也是如此。

  • @D：输出目录。如果 outs 包含一个条目，则会展开为包含该文件的目录。如果它有多个条目，则会扩展为 genfiles 树中软件包的根目录，即使所有输出文件都在同一子目录中！

    注意：使用 RULEDIR 而非 @D，因为 RULEDIR 的语义更简单，无论输出文件的数量如何，其行为都相同。

    如果 genrule 需要生成临时中间文件（可能是由于使用编译器之类的其他工具），则应尝试将它们写入 @D（尽管 /tmp 也可写入），并在完成之前将其移除。

    尤其要避免写入包含输入的目录。它们可能位于只读文件系统中。即使没有，这样做也会破坏源代码树。

预定义的来源/输出路径变量

预定义变量 execpath、execpaths、rootpath、rootpaths、location 和 locations 采用标签参数（例如 $(execpath //foo:bar)）并替换由该标签表示的文件路径。

对于源文件，则是相对于工作区根目录的路径。对于作为规则输出的文件，这是指该文件的输出路径（请参阅下文对输出文件的说明）。

查看预定义路径变量的示例。

  • execpath：表示 Bazel 运行构建操作的 execroot 下的路径。

    在上面的示例中，Bazel 会运行工作区根目录中 bazel-myproject 符号链接所链接的目录中的所有构建操作。源文件 empty.source 链接到路径 bazel-myproject/testapp/empty.source。因此，其 exec 路径（即根目录下的子路径）为 testapp/empty.source。这是构建操作可用于查找文件的路径。

    输出文件的暂存方式类似，但也带有子路径 bazel-out/cpu-compilation_mode/bin 作为前缀（或者用于工具的输出：bazel-out/cpu-opt-exec-hash/bin）。在上面的示例中，//testapp:app 是一个工具，因为它出现在 show_app_output 的 tools 属性中。 因此，其输出文件 app 将被写入 bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app。 因此，exec 路径为 bazel-out/cpu-opt-exec-hash/bin/testapp/app。这一额外的前缀让您可以在一次构建中针对两个不同的 CPU 构建相同的目标，而不会相互干扰结果。

    传递到此变量的标签必须恰好代表一个文件。对于表示源文件的标签，此属性自动为 true。对于表示规则的标签，规则必须仅生成一个输出。如果该值为 false 或标签的格式不正确，则构建会失败并报错。

  • rootpath：表示已构建的二进制文件在运行时可以用来查找某个依赖项的路径，该路径是相对于其 runfiles 目录（对应于主代码库）的子目录。 注意：这只有在启用 --enable_runfiles 时才有效，在 Windows 上默认不会。请改用 rlocationpath 获取跨平台支持。

    这类似于 execpath，但会去掉上述配置前缀。在上面的示例中，这意味着 empty.source 和 app 都使用纯工作区相对路径：testapp/empty.source 和 testapp/app。

    外部代码库 repo 中文件的 rootpath 以 ../repo/ 开头，后跟代码库相对路径。

    这与 execpath 具有相同的“仅限一个输出”要求。

  • rlocationpath：已构建的二进制文件可以传递给 runfiles 库的 Rlocation 函数以在运行时查找依赖项的路径，具体是在 runfiles 目录（如果有）中或使用 runfiles 清单查找。

    这与 rootpath 类似，因为它不包含配置前缀，但不同之处在于它始终以代码库的名称开头。在上面的示例中，这意味着 empty.source 和 app 会生成以下路径：myproject/testapp/empty.source 和 myproject/testapp/app。

    外部代码库 repo 中文件的 rlocationpath 以 repo/ 开头，后跟代码库相对路径。

    将此路径传递给二进制文件并使用 runfiles 库将其解析为文件系统路径，这是在运行时查找依赖项的首选方法。与 rootpath 相比，它的优势在于，它适用于所有平台，即使 runfiles 目录不可用也是如此。

    这与 execpath 具有相同的“仅限一个输出”要求。

  • location：execpath 或 rootpath 的同义词，具体取决于要展开的属性。这是 Starlark 之前的旧版行为，除非您确实了解它对特定规则有何作用，否则不推荐使用。如需了解详情，请参阅 #2475。

execpaths、rootpaths、rlocationpaths 和 locations 分别是 execpath、rootpath、rlocationpaths 和 location 的复数变体。它们支持生成多个输出的标签，在这种情况下，各个输出用空格分隔列出。零输出规则和格式错误的标签会导致构建错误。

所有引用的标签都必须出现在使用方目标的 srcs、输出文件或 deps 中。否则，构建会失败。C++ 目标还可以引用 data 中的标签。

标签不一定要采用规范形式：foo、:foo 和 //somepkg:foo 都可以。

自定义变量

任何标记为“使用‘设置变量’替换”的属性可以引用自定义“Make”变量，但仅限于依赖于定义这些变量的其他目标的目标。

根据最佳实践，所有变量都应自定义，除非有充分的理由将它们融入核心 Bazel。这样可以让 Bazel 不必加载费用可能非常高的依赖项，才能提供使用 taret 不关心的变量。

C++ 工具链变量

以下内容是在 C++ 工具链规则中定义的，并且可供任何设置 toolchains = ["@bazel_tools//tools/cpp:current_cc_toolchain"]（或针对主机工具链等效项的 "@bazel_tools//tools/cpp:current_cc_host_toolchain"）的规则使用。某些规则（如 java_binary）会在其规则定义中隐式包含 C++ 工具链。它们会自动继承这些变量。

内置的 C++ 规则比“在它上运行编译器”复杂得多。为了支持多种多样的编译模式（例如 *SAN、ThinLTO、带/不带模块），以及在多个平台上快速运行测试的同时经过精心优化的二进制文件，内置规则会付出极大的努力，以确保在每个可能的多个内部生成的操作上设置正确的输入、输出和命令行标志。

这些变量是一种回退机制，语言专家在极少数情况下会使用它们。如果您打算使用这类工具，请先与 Bazel 开发者联系。

  • ABI：C++ ABI 版本。
  • AR：来自 crosstool 的“ar”命令。
  • C_COMPILER：C/C++ 编译器标识符，例如 llvm。

  • CC：C 和 C++ 编译器命令。

    我们强烈建议始终将 CC_FLAGS 与 CC 结合使用。如果未能这样做，请自行承担风险。

  • CC_FLAGS：可供 genrules 使用的 C/C++ 编译器的最小标志集。特别是，如果 CC 支持多个架构，它包含用于选择正确架构的标志。
  • NM：来自 crosstool 的“nm”命令。
  • OBJCOPY：与 C/C++ 编译器位于同一套件中的 objcopy 命令。
  • STRIP：C/C++ 编译器所在套件中的剥离命令。

Java 工具链变量

以下内容在 Java 工具链规则中定义，可供任何设置 toolchains = ["@bazel_tools//tools/jdk:current_java_runtime"]（或主机工具链等效项的 "@bazel_tools//tools/jdk:current_host_java_runtime"）的规则使用。

JDK 中的大多数工具不应直接使用，与上游工具可以表达的相比，内置 Java 规则使用更复杂的 Java 编译和打包方法，如接口 Jars、头文件接口 Jars 以及经过高度优化的 Jar 打包和合并实现。

这些变量是一种回退机制，语言专家在极少数情况下会使用它们。如果您打算使用这类工具，请先与 Bazel 开发者联系。

  • JAVA：“java”命令（Java 虚拟机）。请避免这种情况，并尽可能改用 java_binary 规则。可能是相对路径。如果您必须在调用 java 之前更改目录，则需要先捕获工作目录，然后再进行更改。
  • JAVABASE：包含 Java 实用程序的基本目录。可能是相对路径。其中包含一个“bin”子目录。

Starlark 定义的变量

规则和工具链写入者可以通过返回 TemplateVariableInfo 提供程序来定义完全自定义变量。这样，任何通过 toolchains 属性依赖这些变量的规则便可读取其值：

查看 Starlark 定义的变量示例。