2022 年 BazelCon 将于 11 月 16 日至 17 日在纽约和线上举办。
立即报名!

工具链

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本页面介绍了工具链框架,该框架可让规则作者将其规则逻辑与基于平台的工具选择分离开来。建议您先阅读规则平台页面,然后再继续。本页面介绍了需要工具链的原因、定义和使用工具链的方式,以及 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 用户而言,这很繁琐,并且有点麻烦。如果此样式在工作区中并非保持一致,则会导致 build 可以在单个平台上正常运行,但在扩展到多平台场景时却会失败。此外,这也没有解决在不修改现有规则或目标的情况下增加对新平台和编译器的支持的问题。

工具链框架通过添加额外的间接层解决了这个问题。从本质上说,您会声明,您的规则依赖于目标系列的某个成员(工具链类型),并且 Bazel 会自动将其解析为特定目标(工具链) )。规则作者和目标作者都不需要知道完整的可用平台和工具链集。

编写使用工具链的规则

在工具链框架下,规则直接依赖于工具类型,而不是直接依赖于工具。 工具链类型是一个简单的目标,代表代表不同平台提供相同角色的一类工具。例如,您可以声明代表条形编译器的某种类型:

# 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 []

定义工具链

如需为给定的工具链类型定义一些工具链,您需要具备以下三项:

  1. 一种特定语言的规则,表示工具或工具包的类型。按照惯例,此规则的名称后缀为“_工具链”。

    1. 注意\_toolchain 规则无法创建任何构建操作。相反,它会从其他规则中收集工件,并将其转发到使用工具链的规则。该规则负责创建所有构建操作。
  2. 此规则类型的多个目标,表示不同平台的工具或工具版本。

  3. 对于每个此类目标,这是通用 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 和工具链类型的标签来检索的对象。与 struct 一样,ToolchainInfo 可以保存任意字段-值对。应在工具链类型中明确说明哪些字段添加到 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 依赖项也可由父级的构建操作执行。任何使用 cfg = "target"(或者未指定“cfg”,因为“target”是默认值)的工具链的依赖项都是与父级构建的同一目标平台构建的。这样一来,工具链规则就可以同时为需要它们的库规则(上面的 system_lib 属性)和工具(compiler 属性)贡献代码。系统库链接到最终工件,因此需要针对同一平台进行构建,而编译器是在构建期间调用的工具,并且必须能够在执行平台。

注册和构建工具链

此时,所有构建块都已组装,您只需要将工具链提供给 Bazel 的解析过程即可。为此,您可以使用 register_toolchains()WORKSPACE 文件中进行注册,也可以使用 --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",
)

现在,当您构建依赖于工具链类型的目标时,系统会根据目标和执行平台选择适当的工具链。

# 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:barc_linux_toolchain//bar_tools:toolchain_type 引用。这将最终构建 //bar_tools:barc_linux,但不会构建 //bar_tools:barc_windows

工具链解决方案

对于使用工具链的每个目标,Bazel 的工具链解析过程将确定目标的具体工具链依赖项。该过程将一组必需的工具链类型、目标平台、可用执行平台列表和可用工具链列表作为输入。它的输出是为每种工具链类型选择的工具链以及为当前目标选择的执行平台。

可用执行平台和工具链是从WORKSPACE文件: register_execution_platformsregister_toolchains 。您还可以在命令行中通过 --extra_execution_platforms--extra_toolchains 指定其他执行平台和工具链。 主机平台会自动添加为可用的执行平台。 可用平台和工具链作为确定性有序列表进行跟踪,并优先考虑列表中的早期项。

解决步骤如下。

  1. target_compatible_withexec_compatible_with 子句与平台匹配,如果对于列表中的每个 constraint_value,平台还具有该 constraint_value(任一明确或默认)。

    如果平台有 constraint_setting 未引用子句引用的 constraint_value,则这些设置不会影响匹配。

  2. 如果正在构建的目标指定了exec_compatible_with属性(或其规则定义指定了exec_compatible_with参数),系统会过滤可用执行平台列表,移除与执行约束不匹配的任何执行平台。

  3. 对于每个可用的执行平台,您需要将每个工具链类型与该第一个执行平台和目标平台兼容的第一个工具链(如果有)相关联。

  4. 任何未能为某个工具链类型找到兼容的强制工具链的执行平台都会被排除。在其余平台中,第一个平台成为当前目标的执行平台,其关联的工具链(如有)成为目标的依赖项。

所选的执行平台将用于运行目标生成的所有操作。

如果可以在同一 build 内的多个配置(例如针对不同的 CPU)中构建相同的目标,系统会单独对每个目标版本应用解析过程。

如果规则使用执行组,则每个执行组都会单独执行工具链解析,每个执行组都有自己的执行平台和工具链。

调试工具链

如果要为现有规则添加工具链支持,请使用 --toolchain_resolution_debug=regex 标志。在工具链解析期间,该标志会为与正则表达式变量匹配的工具链类型或目标名称提供详细输出。您可以使用 .* 输出所有信息。Bazel 会输出它在解析过程中检查和跳过的工具链的名称。

如果您想查看哪些 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