“制作”变量是一种特殊的类,可展开字符串变量, 标记为“取决于‘创建变量’的属性”替换”。
例如,这些文件可用于将特定的工具链路径注入 由用户构建的构建操作。
Bazel 同时提供预定义变量(适用于所有目标)和自定义变量(在依赖项目标中定义,仅适用于依赖于它们的目标)。
出现“品牌”一词的原因是历史: 这些变量最初旨在与 GNU 相匹配, Make。
使用
被标记为“取决于‘创建变量’的属性”替换”
您可以参阅变量 FOO
,如下所示:
my_attr = "prefix $(FOO) suffix"
换句话说,与 $(FOO)
匹配的任何子字符串都会扩展
设置为 FOO
的值。如果该值为 "bar"
,则最终
字符串变为:
my_attr = "prefix bar suffix"
如果 FOO
与使用方目标所知的变量不符,Bazel 会失败并显示错误。
名称为非字母符号(例如 @
)的“make”变量也可以仅使用美元符号(而无需括号)进行引用。例如:
my_attr = "prefix $@ suffix"
将 $
编写为字符串字面量(也就是说,为了防止变量
扩展),写 $$
。
预定义变量
预定义的“品牌”变量可以由任何标记为 “取决于‘创建变量’替换”。
查看这些变量列表及其指定一组 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
属性,通常对该属性的正常运行至关重要。
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
。这个额外的前缀 例如,为同一个项目中的两个不同的 CPU 构建相同的目标, 相同的 build,而不会产生相互影响。传递给此变量的标签必须恰好代表一个文件。对于表示源文件的标签,此属性会自动设为 true。对于标签 表示规则,规则必须只生成一个输出。如果此值为 false 或标签格式有误,构建将会失败并显示错误。
-
rootpath
:表示构建的二进制文件可用于在运行时相对于其 runfiles 目录的子目录(对应于主代码库)查找依赖项的路径。 注意:只有在启用--enable_runfiles
的情况下,此方法才有效,而 Windows 上默认情况下不会启用--enable_runfiles
。如需跨平台支持,请改用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
。外部代码库中文件的
rlocationpath
repo
开头为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”变量,但仅限于依赖于定义这些变量的其他目标的目标。
最佳做法是所有变量都应该是自定义的,除非有非常好的变量 将它们融入核心 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
:一组最少的 C/C++ 编译器标志,可供 genrules 使用。具体来说,这包含用于 如果CC
支持多个 架构。-
NM
:crosstool 中的“nm”命令。 -
OBJCOPY
:与 C/C++ 编译器来自同一套件的 objcopy 命令。 -
STRIP
:与 C/C++ 相同的套件中的 trip 命令 。
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
属性可以读取它们的值: