本页介绍了工具链框架，该框架可让规则作者将规则逻辑与基于平台的工具选择分离。建议您先阅读规则和平台页面，然后再继续。本页介绍了为何需要工具链、如何定义和使用工具链，以及 Bazel 如何根据平台限制条件选择合适的工具链。
设计初衷
我们先来看看工具链旨在解决的问题。假设您正在编写规则来支持“bar”编程语言。您的 bar_binary 规则将使用 barc 编译器（一种本身在工作区中构建为另一个目标的工具）编译 *.bar 文件。由于编写 bar_binary 目标的用户不应必须指定对编译器的依赖，因此您可以通过将编译器作为私有属性添加到规则定义中，使其成为隐式依赖。
bar_binary = rule(
implementation = _bar_binary_impl,
attrs = {
"srcs": attr.label_list(allow_files = True),
...
"_compiler": attr.label(
default = "//bar_tools:barc_linux", # the compiler running on linux
providers = [BarcInfo],
),
},
)
//bar_tools:barc_linux 现在是每个 bar_binary 目标的依赖项，因此它将在任何 bar_binary 目标之前构建。规则的实现函数可以像访问任何其他属性一样访问它：
BarcInfo = provider(
doc = "Information about how to invoke the barc compiler.",
# In the real world, compiler_path and system_lib might hold File objects,
# but for simplicity they are strings for this example. arch_flags is a list
# of strings.
fields = ["compiler_path", "system_lib", "arch_flags"],
)
def _bar_binary_impl(ctx):
...
info = ctx.attr._compiler[BarcInfo]
command = "%s -l %s %s" % (
info.compiler_path,
info.system_lib,
" ".join(info.arch_flags),
)
...
这里的问题在于，编译器的标签硬编码到 bar_binary 中，但不同的目标可能需要不同的编译器，具体取决于它们要构建的目标平台和构建时所用的平台（分别称为目标平台和执行平台）。此外，规则作者甚至不一定知道所有可用的工具和平台，因此无法在规则定义中对它们进行硬编码。
一种不太理想的解决方案是将负担转移到用户身上，即将 _compiler 属性设为非私有。然后，各个目标可以硬编码为针对一个平台或另一个平台进行构建。
bar_binary(
name = "myprog_on_linux",
srcs = ["mysrc.bar"],
compiler = "//bar_tools:barc_linux",
)
bar_binary(
name = "myprog_on_windows",
srcs = ["mysrc.bar"],
compiler = "//bar_tools:barc_windows",
)
您可以使用 select 根据平台选择 compiler
来改进此解决方案：
config_setting(
name = "on_linux",
constraint_values = [
"@platforms//os:linux",
],
)
config_setting(
name = "on_windows",
constraint_values = [
"@platforms//os:windows",
],
)
bar_binary(
name = "myprog",
srcs = ["mysrc.bar"],
compiler = select({
":on_linux": "//bar_tools:barc_linux",
":on_windows": "//bar_tools:barc_windows",
}),
)
但这很繁琐，而且要求每位 bar_binary 用户都这样做有点过分。
如果此样式未在整个工作区中保持一致，则会导致构建在单个平台上正常运行，但在扩展到多平台场景时失败。它也无法解决在不修改现有规则或目标的情况下添加对新平台和编译器的支持的问题。
工具链框架通过添加额外的间接层来解决此问题。从本质上讲，您声明规则对目标系列（工具链类型）的某个成员具有抽象依赖关系，而 Bazel 会根据适用的平台限制自动将其解析为特定目标（工具链）。规则作者和目标作者都不需要知道完整的可用平台和工具链集。
编写使用工具链的规则
在工具链框架下，规则不再直接依赖于工具，而是依赖于工具链类型。工具链类型是一种简单的目标，表示一类在不同平台上发挥相同作用的工具。例如，您可以声明一个表示 bar 编译器的类型：
# By convention, toolchain_type targets are named "toolchain_type" and
# distinguished by their package path. So the full path for this would be
# //bar_tools:toolchain_type.
toolchain_type(name = "toolchain_type")
修改上一部分中的规则定义，使其不再将编译器作为属性传入，而是声明它使用 //bar_tools:toolchain_type 工具链。
bar_binary = rule(
implementation = _bar_binary_impl,
attrs = {
"srcs": attr.label_list(allow_files = True),
...
# No `_compiler` attribute anymore.
},
toolchains = ["//bar_tools:toolchain_type"],
)
实现函数现在使用工具链类型作为键，在 ctx.toolchains 下（而不是 ctx.attr 下）访问此依赖项。
def _bar_binary_impl(ctx):
...
info = ctx.toolchains["//bar_tools:toolchain_type"].barcinfo
# The rest is unchanged.
command = "%s -l %s %s" % (
info.compiler_path,
info.system_lib,
" ".join(info.arch_flags),
)
...
ctx.toolchains["//bar_tools:toolchain_type"] 会返回 Bazel 将工具链依赖项解析为的任何目标的 ToolchainInfo 提供程序。ToolchainInfo 对象的字段由底层工具的规则设置；在下一部分中，此规则定义为包含一个封装 BarcInfo 对象的 barcinfo 字段。
下文介绍了 Bazel 将工具链解析为目标的过程。只有已解析的工具链目标实际上成为 bar_binary 目标的依赖项，而不是整个候选工具链空间。
强制性工具链和可选工具链
默认情况下，当规则使用裸标签（如上所示）表达工具链类型依赖项时，工具链类型被视为必需。如果 Bazel 无法为强制性工具链类型找到匹配的工具链（请参阅下文中的工具链解析），则会发生错误，并且分析会停止。
不过，您可以改为声明一个可选的工具链类型依赖项，如下所示：
bar_binary = rule(
...
toolchains = [
config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False),
],
)
当无法解析可选的工具链类型时，分析会继续进行，并且 ctx.toolchains["//bar_tools:toolchain_type"] 的结果为 None。
config_common.toolchain_type 函数默认为必需函数。
您可以使用以下表单：
- 强制性工具链类型：
toolchains = ["//bar_tools:toolchain_type"]toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type")]toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = True)]
- 可选的工具链类型：
toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False)]
bar_binary = rule(
...
toolchains = [
"//foo_tools:toolchain_type",
config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False),
],
)
您还可以在同一规则中混搭使用各种形式。不过，如果同一工具链类型列出了多次，系统将采用最严格的版本，其中强制性比可选性更严格。
使用工具链的写入方面
方面与规则一样，可以访问相同的工具链 API：您可以定义所需的工具链类型，通过上下文访问工具链，并使用它们通过工具链生成新的操作。
bar_aspect = aspect(
implementation = _bar_aspect_impl,
attrs = {},
toolchains = ['//bar_tools:toolchain_type'],
)
def _bar_aspect_impl(target, ctx):
toolchain = ctx.toolchains['//bar_tools:toolchain_type']
# Use the toolchain provider like in a rule.
return []
定义工具链
如需为给定的工具链类型定义一些工具链，您需要以下三项内容：
表示工具或工具套件类型的特定于语言的规则。按照惯例，此规则的名称以“_toolchain”为后缀。
- 注意：
\_toolchain规则无法创建任何 build 操作。 而是从其他规则中收集制品，并将其转发给使用工具链的规则。该规则负责创建所有 build 操作。
- 注意：
此规则类型的多个目标，表示不同平台的工具或工具套件版本。
对于每个此类目标，都有一个关联的通用
toolchain规则目标，用于提供工具链框架使用的元数据。此toolchain目标也指与此工具链关联的toolchain_type。 这意味着，给定的_toolchain规则可以与任何toolchain_type相关联，并且只有在使用此_toolchain规则的toolchain实例中，该规则才与toolchain_type相关联。
对于我们正在使用的示例，以下是 bar_toolchain 规则的定义。我们的示例只有一个编译器，但其他工具（例如链接器）也可以分组到该编译器下方。
def _bar_toolchain_impl(ctx):
toolchain_info = platform_common.ToolchainInfo(
barcinfo = BarcInfo(
compiler_path = ctx.attr.compiler_path,
system_lib = ctx.attr.system_lib,
arch_flags = ctx.attr.arch_flags,
),
)
return [toolchain_info]
bar_toolchain = rule(
implementation = _bar_toolchain_impl,
attrs = {
"compiler_path": attr.string(),
"system_lib": attr.string(),
"arch_flags": attr.string_list(),
},
)
该规则必须返回一个 ToolchainInfo 提供程序，该提供程序将成为使用 ctx.toolchains 和工具链类型标签检索的消耗规则的对象。ToolchainInfo 与 struct 一样，可以包含任意字段-值对。应在工具链类型中清楚地记录添加到 ToolchainInfo 中的确切字段的规范。在此示例中，返回值封装在 BarcInfo 对象中，以便重复使用上面定义的架构；此样式可能有助于验证和代码重用。
现在，您可以为特定 barc 编译器定义目标。
bar_toolchain(
name = "barc_linux",
arch_flags = [
"--arch=Linux",
"--debug_everything",
],
compiler_path = "/path/to/barc/on/linux",
system_lib = "/usr/lib/libbarc.so",
)
bar_toolchain(
name = "barc_windows",
arch_flags = [
"--arch=Windows",
# Different flags, no debug support on windows.
],
compiler_path = "C:\\path\\on\\windows\\barc.exe",
system_lib = "C:\\path\\on\\windows\\barclib.dll",
)
最后，您需要为两个 bar_toolchain 目标创建 toolchain 定义。这些定义将特定于语言的目标与工具链类型相关联，并提供约束信息，告知 Bazel 何时工具链适合给定的平台。
toolchain(
name = "barc_linux_toolchain",
exec_compatible_with = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
],
target_compatible_with = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
],
toolchain = ":barc_linux",
toolchain_type = ":toolchain_type",
)
toolchain(
name = "barc_windows_toolchain",
exec_compatible_with = [
"@platforms//os:windows",
"@platforms//cpu:x86_64",
],
target_compatible_with = [
"@platforms//os:windows",
"@platforms//cpu:x86_64",
],
toolchain = ":barc_windows",
toolchain_type = ":toolchain_type",
)
上述相对路径语法的使用表明，这些定义都在同一软件包中，但工具链类型、特定于语言的工具链目标和 toolchain 定义目标完全可以位于不同的软件包中。
如需查看实际示例，请参阅 go_toolchain。
工具链和配置
对于规则作者来说，一个重要的问题是，当分析 bar_toolchain 目标时，它会看到什么配置，以及应该为依赖项使用哪些转换？上面的示例使用了字符串属性，但如果工具链更复杂，依赖于 Bazel 代码库中的其他目标，会发生什么情况？
我们来看一个更复杂的 bar_toolchain 版本：
def _bar_toolchain_impl(ctx):
# The implementation is mostly the same as above, so skipping.
pass
bar_toolchain = rule(
implementation = _bar_toolchain_impl,
attrs = {
"compiler": attr.label(
executable = True,
mandatory = True,
cfg = "exec",
),
"system_lib": attr.label(
mandatory = True,
cfg = "target",
),
"arch_flags": attr.string_list(),
},
)
attr.label 的使用方式与标准规则相同，但 cfg 参数的含义略有不同。
从目标（称为“父级”）到工具链（通过工具链解析）的依赖关系使用一种特殊的配置转换，称为“工具链转换”。工具链过渡会保持配置不变，但会强制工具链的执行平台与父级的执行平台相同（否则，工具链的工具链解析可能会选择任何执行平台，并且不一定与父级的执行平台相同）。这样一来，工具链的任何 exec 依赖项也可用于父 build 操作。使用 cfg =
"target" 的任何工具链依赖项（或未指定 cfg 的依赖项，因为“target”是默认值）都将针对与父级相同的目标平台进行构建。这样一来，工具链规则便可将库（上面的 system_lib 属性）和工具（compiler 属性）同时贡献给需要它们的 build 规则。系统库会链接到最终制品中，因此需要针对同一平台进行构建，而编译器是在构建期间调用的工具，需要能够在执行平台上运行。
注册并使用工具链进行构建
此时，所有构建块都已组装完毕，您只需向 Bazel 的解析程序提供工具链即可。为此，您需要注册工具链，方法是在 MODULE.bazel 文件中使用 register_toolchains()，或者在命令行中使用 --extra_toolchains 标志传递工具链的标签。
register_toolchains(
"//bar_tools:barc_linux_toolchain",
"//bar_tools:barc_windows_toolchain",
# Target patterns are also permitted, so you could have also written:
# "//bar_tools:all",
# or even
# "//bar_tools/...",
)
使用目标模式注册工具链时，各个工具链的注册顺序由以下规则确定：
- 子软件包中定义的工具链在软件包本身中定义的工具链之前注册。
- 在软件包中，工具链按其名称的字典顺序注册。
现在，当您构建依赖于工具链类型的目标时，系统会根据目标平台和执行平台选择合适的工具链。
# my_pkg/BUILD
platform(
name = "my_target_platform",
constraint_values = [
"@platforms//os:linux",
],
)
bar_binary(
name = "my_bar_binary",
...
)
bazel build //my_pkg:my_bar_binary --platforms=//my_pkg:my_target_platform
Bazel 会发现 //my_pkg:my_bar_binary 是使用具有 @platforms//os:linux 的平台构建的，因此会将 //bar_tools:toolchain_type 引用解析为 //bar_tools:barc_linux_toolchain。这最终会构建 //bar_tools:barc_linux，但不会构建 //bar_tools:barc_windows。
工具链分辨率
对于使用工具链的每个目标，Bazel 的工具链解析过程都会确定目标的具体工具链依赖项。该过程将一组必需的工具链类型、目标平台、可用执行平台列表和可用工具链列表作为输入。其输出是每种工具链类型的所选工具链，以及当前目标的所选执行平台。
通过 MODULE.bazel 文件中的 register_execution_platforms 和 register_toolchains 调用，从外部依赖关系图中收集可用的执行平台和工具链。您还可以通过 --extra_execution_platforms 和 --extra_toolchains 在命令行中指定其他执行平台和工具链。宿主平台会自动包含在可用的执行平台中。可用的平台和工具链会以有序列表的形式进行跟踪，以确保确定性，并优先考虑列表中的较早项。
可用的工具链集（按优先级排序）由 --extra_toolchains 和 register_toolchains 创建：
- 使用
--extra_toolchains注册的工具链会先添加。（在这些工具链中，最后一个工具链的优先级最高。） - 使用
register_toolchains在传递性外部依赖关系图中注册的工具链，按以下顺序排列：（在这些工具链中，首先提及的工具链具有最高优先级。）- 由根模块（即工作区根目录中的
MODULE.bazel）注册的工具链； - 在用户的
WORKSPACE文件中注册的工具链，包括从该文件调用的任何宏； - 由非根模块注册的工具链（即，由根模块指定的依赖项及其依赖项等）；
- 在“工作区后缀”中注册的工具链；仅供与 Bazel 安装捆绑的某些原生规则使用。
- 由根模块（即工作区根目录中的
注意：:all、:* 和 /... 等伪目标由 Bazel 的软件包加载机制按字典顺序排序。
问题解决步骤如下。
如果
target_compatible_with或exec_compatible_with子句中的每个constraint_value都在相应平台中存在（无论是明确存在还是作为默认值存在），则该子句匹配相应平台。constraint_value如果平台具有子句未引用的来自
constraint_setting的constraint_value，则这些constraint_value不会影响匹配。如果正在构建的目标指定了
exec_compatible_with属性（或其规则定义指定了exec_compatible_with实参），则会过滤可用的执行平台列表，以移除任何不符合执行限制条件的平台。过滤可用工具链的列表，以移除指定了与当前配置不匹配的
target_settings的所有工具链。对于每个可用的执行平台，您将每个工具链类型与第一个可用的工具链（如果有）相关联，该工具链与此执行平台和目标平台兼容。
如果执行平台未能为其某个工具链类型找到兼容的强制性工具链，则该平台将被排除。在剩余的平台中，第一个平台会成为当前目标的执行平台，而其关联的工具链（如果有）会成为目标的依赖项。
所选的执行平台用于运行目标生成的所有操作。
如果同一目标可以在同一 build 中以多种配置（例如针对不同的 CPU）进行 build，则解析过程会独立应用于目标的每个版本。
如果规则使用执行组，则每个执行组会单独执行工具链解析，并且每个执行组都有自己的执行平台和工具链。
调试工具链
如果您要为现有规则添加工具链支持，请使用 --toolchain_resolution_debug=regex 标志。在工具链解析期间，该标志会为与正则表达式变量匹配的工具链类型或目标名称提供详细输出。您可以使用 .* 输出所有信息。Bazel 将输出在解析过程中检查和跳过的工具链的名称。
例如，如需调试由 //my:target 直接创建的所有操作的工具链选择，请运行以下命令：
$ bazel build //my:all --toolchain_resolution_debug=//my:target
如需调试所有构建目标的所有操作的工具链选择，请执行以下操作：
$ bazel build //my:all --toolchain_resolution_debug=.*
如果您想查看哪些 cquery 依赖项来自工具链解析，请使用 cquery 的 --transitions 标志：
# Find all direct dependencies of //cc:my_cc_lib. This includes explicitly
# declared dependencies, implicit dependencies, and toolchain dependencies.
$ bazel cquery 'deps(//cc:my_cc_lib, 1)'
//cc:my_cc_lib (96d6638)
@bazel_tools//tools/cpp:toolchain (96d6638)
@bazel_tools//tools/def_parser:def_parser (HOST)
//cc:my_cc_dep (96d6638)
@local_config_platform//:host (96d6638)
@bazel_tools//tools/cpp:toolchain_type (96d6638)
//:default_host_platform (96d6638)
@local_config_cc//:cc-compiler-k8 (HOST)
//cc:my_cc_lib.cc (null)
@bazel_tools//tools/cpp:grep-includes (HOST)
# Which of these are from toolchain resolution?
$ bazel cquery 'deps(//cc:my_cc_lib, 1)' --transitions=lite | grep "toolchain dependency"
[toolchain dependency]#@local_config_cc//:cc-compiler-k8#HostTransition -> b6df211