&makeot; 变量

报告问题 查看源代码

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

例如，这些脚本可用于将特定的工具链路径注入到用户构建的构建操作中。

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

之所以使用“Make”这一术语的原因，是因为这些变量的语法和语义最初是为了与 GNU Make 匹配。

使用

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

my_attr = "prefix $(FOO) suffix"

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

my_attr = "prefix bar suffix"

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

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

my_attr = "prefix $@ suffix"

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

预定义变量

预定义“Make”变量可以由任何目标上标记为“使用“Make 变量”替代的属性”引用。

如需查看这些变量的列表及其对应一组给定 build 选项的值，请运行

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。因此，其执行路径（即根下的子路径）为 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。 因此，执行路径为 bazel-out/cpu-opt-exec-hash/bin/testapp/app。有了这个额外的前缀，就可以为一个 build 中的两个不同的 CPU 构建相同的目标，而不会使结果相互重叠。

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

  • rootpath：表示已构建二进制文件在运行时可用于相对于其主文件目录（与主代码库对应的子目录）查找依赖项的路径。 注意：只有在启用 --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”变量可以由任何标记为 "Make 'Make variable' subplacement" 的属性引用，但只能依赖于依赖于定义这些变量的其他目标的目标。

除非有很好的理由将它们烘焙到核心 Bazel 中，否则所有最佳实践都应该是自定义的。这样一来，Bazel 就不必加载可能昂贵的依赖项，即可提供使用 tar 的可能并不关心的变量。

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：可供 C/C++ 编译器供 genrule 使用的最小的一组标记。具体而言，它包含用于在 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 规则使用更复杂的 Java 编译和打包方法，例如接口 Jar、标头接口 Jar 以及高度优化的 Jar 打包和合并实现。

这些变量是语言专家在极少数情况下使用的后备机制。如果您想使用它们，请先与 Bazel 开发者联系。

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

Starlark 定义的变量

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

查看 Starlark 定义的变量示例。