创建变量

报告问题 查看源代码

“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。因此，其执行路径（即根目录下的子路径）为 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 构建相同的目标，而不会相互干扰。

    传递给此变量的标签必须恰好代表一个文件。对于表示源文件的标签，此值自动为 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”变量可以由标记为“Subject to 'Make variable' substitution"”的任何属性引用，但仅限于依赖于定义这些变量的其他目标的目标。

最佳做法是，所有变量都应是自定义变量，除非有充分的理由将它们纳入核心 Bazel。这样一来，Bazel 就无需加载可能十分昂贵的依赖项，这样就能提供使用方不关心的变量。

C++ 工具链变量

以下内容在 C++ 工具链规则中定义，适用于任何设置 toolchains = ["@bazel_tools//tools/cpp:current_cc_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：供 genrule 使用的 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 中的大多数工具不应直接使用。与上游工具（例如接口 Jars、头文件接口 Jars 以及高度优化的 Jar 打包和合并实现）相比，上游工具所能表达的）内置 Java 规则使用的 Java 编译和打包方法要复杂得多。

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

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

Starlark 定义的变量

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

查看 Starlark 定义的变量示例。