BazelCon 2024 报名现已开放！

此页面由 Cloud Translation API 翻译。

迁移到平台

报告问题查看源代码每夜 build · 7.4 .

Bazel 针对多架构和交叉编译 build 提供了完善的支持，可用于对平台和工具链进行建模。

本页面总结了此支持的状态。

另请参阅：

状态

C++

设置 --incompatible_enable_cc_toolchain_resolution 后，C++ 规则会使用平台选择工具链。

这意味着，您可以使用以下方式配置 C++ 项目：

bazel build //:my_cpp_project --platforms=//:myplatform

而不再使用旧版：

bazel build //:my_cpp_project` --cpu=... --crosstool_top=...  --compiler=...

Bazel 7.0 中默认启用该功能 (#7260)。

如需使用平台测试 C++ 项目，请参阅迁移项目和配置 C++ 工具链。

Java

Java 规则使用平台来选择工具链。

这取代了旧版标志 --java_toolchain、--host_java_toolchain、--javabase 和 --host_javabase。

如需了解详情，请参阅 Java 和 Bazel。

Android

设置 --incompatible_enable_android_toolchain_resolution 后，Android 规则会使用平台来选择工具链。

这意味着，您可以使用以下内容配置 Android 项目：

bazel build //:my_android_project --android_platforms=//:my_android_platform

而不是使用 --android_crosstool_top、--android_cpu 和 --fat_apk_cpu 等旧版标志。

在 Bazel 7.0 中，此功能将默认启用 (#16285)。

如需使用平台测试 Android 项目，请参阅迁移项目。

Apple

Apple 规则不支持平台，尚未安排支持。

您仍然可以将平台 API 与 Apple build 搭配使用（例如，在混合使用 Apple 规则和纯 C++ 进行构建时），只需使用平台映射即可。

其他语言

Go 规则完全支持平台
Rust 规则完全支持平台。

如果您有语言规则集，请参阅迁移规则集以添加支持。

背景

引入平台和工具链是为了标准化软件项目如何定位到不同的架构并进行交叉编译。

这受到启发的是，语言维护人员已经在以不兼容的临时方式这样做。例如，C++ 规则使用 --cpu 和 --crosstool_top 来声明目标 CPU 和工具链。这两种方法都无法正确对“平台”进行建模。这会生成不合适且不正确的 build。

Java、Android 和其他语言都针对类似用途开发了自己的标志，但这些标志之间无法互操作。这使得跨语言构建工作混乱而复杂

Bazel 适用于大型、多语言、多平台项目。这需要对这些概念提供更具原则性的支持，包括明确的标准 API。

需要迁移

升级到新 API 需要完成两项工作：发布 API 并升级规则逻辑以使用该 API。

第一个已完成，但第二个仍在进行中。这包括确保定义特定语言的平台和工具链，语言逻辑通过新 API（而不是 --crosstool_top 等旧标志）读取工具链，以及 config_setting 选择新 API（而不是旧标志）。

这项工作很简单，但需要针对每种语言进行不同的处理，并且需要向项目所有者发出合理的警告，以便他们针对即将发生的更改进行测试。

因此，这项迁移是一项持续性工作。

目标

当所有项目都使用以下格式构建时，此迁移即告完成：

bazel build //:myproject --platforms=//:myplatform

这意味着：

项目的规则会为 //:myplatform 选择合适的工具链。
项目的依赖项会为 //:myplatform 选择合适的工具链。
//:myplatform 引用 CPU、OS 和其他通用的与语言无关的属性的常见声明
所有相关的 select() 都与 //:myplatform 正确匹配。
//:myplatform 在一个清晰且易于访问的位置进行定义：在项目的代码库中（如果平台是您的项目独有的平台），或者所有使用方项目都可以在某个常见位置找到它

我们会尽快废弃并移除 --cpu、--crosstool_top 和 --fat_apk_cpu 等旧标志，确保安全无害。

最终，这将成为配置架构的唯一方式。

迁移项目

如果您使用支持平台的语言进行构建，您的 build 应该已经可以使用如下调用：

bazel build //:myproject --platforms=//:myplatform

如需了解确切详情，请参阅状态和您所用语言的文档。

如果某种语言需要标志才能启用平台支持，您还需要设置该标志。如需了解详情，请参阅状态。

要构建您的项目，您需要检查以下内容：

//:myplatform 必须存在。由于不同的项目定位到不同的机器，因此定义平台通常是项目所有者的责任。请参阅默认平台。
您要使用的工具链必须存在。如果使用的是标准工具链，语言所有者应添加有关如何注册这些工具链的说明。如果您要编写自己的自定义工具链，则需要在 MODULE.bazel 文件中或使用 --extra_toolchains register它们。
select() 和配置转换必须正确解析。请参阅 select() 和转换。
如果您的 build 混合了支持和不支持平台的语言，您可能需要平台映射来帮助旧版语言与新 API 搭配使用。如需了解详情，请参阅平台映射。

如果问题仍然存在，请与我们联系寻求支持。

默认平台

项目所有者应定义明确的平台，以描述他们想要针对哪些架构构建应用。然后，您可以使用 --platforms 触发这些事件。

如果未设置 --platforms，Bazel 会默认使用表示本地构建机器的 platform。这是在 @platforms//host（别名为 @bazel_tools//tools:host_platform）自动生成的，因此无需明确定义。它会将本地机器的 OS 和 CPU 映射到 @platforms 中声明的 constraint_value。

`select()`

项目可以在 constraint_value 目标上select()，但不能在完整平台上select()。这是有意为之，以便 select() 支持尽可能多的机器。包含 ARM 专用源代码的库应支持所有搭载 ARM 的机器，除非有理由更具体地指定支持的机器。

如需选择一个或多个 constraint_value，请使用以下命令：

config_setting(
    name = "is_arm",
    constraint_values = [
        "@platforms//cpu:arm",
    ],
)

这相当于传统上在 --cpu 上进行选择：

config_setting(
    name = "is_arm",
    values = {
        "cpu": "arm",
    },
)

如需了解详情，请点击此处。

--cpu、--crosstool_top 等中的 select 无法理解 --platforms。将项目迁移到平台时，您必须将其转换为 constraint_values，或使用平台映射在迁移期间同时支持这两种样式。

转场效果

Starlark 转换会更改构建图的部分标志。如果您的项目使用会设置 --cpu、--crossstool_top 或其他旧版标志的转换，则读取 --platforms 的规则将不会看到这些更改。

将项目迁移到平台时，您必须将 return { "//command_line_option:cpu": "arm" } 等更改转换为 return { "//command_line_option:platforms": "//:my_arm_platform" }，或者在迁移过程中使用平台映射来支持这两种样式。

迁移规则集

如果您拥有规则集，并且想要支持平台，则需要满足以下条件：

让规则逻辑使用 toolchain API 解析 toolchain。请参阅工具链 API (ctx.toolchains)。
可选：定义 --incompatible_enable_platforms_for_my_language 标志，以便在迁移测试期间，规则逻辑通过新 API 或旧标志（例如 --crosstool_top）交替解析工具链。
定义构成平台组件的相关属性。请参阅通用平台属性
定义标准工具链，并通过规则的注册说明向用户提供这些工具链（详情）
确保 select() 和配置转换支持平台。这是最大的挑战。这对于多语言项目而言尤其具有挑战性（如果所有语言都无法读取 --platforms，则可能会失败）。

如果您需要混用不支持平台的规则，则可能需要平台映射来弥合这方面的差异。

常见平台属性

常用的跨语言平台属性（如 OS 和 CPU）应在 @platforms 中声明。这有助于实现共享、标准化和跨语言兼容性。

规则特有的属性应在规则的代码库中声明。这样，您就可以对规则负责的具体概念保持明确的所有权。

如果您的规则使用专用操作系统或 CPU，则应在规则的代码库中声明这些操作系统或 CPU，而不是在 @platforms 中声明。

平台映射

平台映射是一个临时 API，可让平台感知型逻辑与同一 build 中的旧版逻辑混合使用。这是一种粗暴的工具，仅用于解决因迁移时间范围不同而导致的不兼容问题。

平台映射是 platform() 与一组对应的旧版标志之间的映射，或相反。例如：

platforms:
  # Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
  //platforms:ios
    --cpu=ios_x86_64
    --apple_platform_type=ios

flags:
  # Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --cpu=ios_x86_64
  --apple_platform_type=ios
    //platforms:ios

  # Maps "--cpu=darwin_x86_64 --apple_platform_type=macos" to "//platform:macos".
  --cpu=darwin_x86_64
  --apple_platform_type=macos
    //platforms:macos

Bazel 使用此机制来保证在整个 build 过程中（包括通过转换）一致地应用所有设置（包括平台级设置和旧版设置）。

默认情况下，Bazel 会从工作区根目录中的 platform_mappings 文件读取映射。您还可以设置 --platform_mappings=//:my_custom_mapping。

如需了解详情，请参阅平台映射设计。

API 审核

platform 是 constraint_value 目标的集合：

platform(
    name = "myplatform",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

constraint_value 是一种机器属性。同一“种类”的值将划分到共同的 constraint_setting 下：

constraint_setting(name = "os")
constraint_value(
    name = "linux",
    constraint_setting = ":os",
)
constraint_value(
    name = "mac",
    constraint_setting = ":os",
)

toolchain 是 Starlark 规则。其属性声明语言的工具（例如 compiler = "//mytoolchain:custom_gcc"）。其提供程序会将此信息传递给需要使用这些工具进行构建的规则。

工具链会声明其可定位的计算机的 constraint_value (target_compatible_with = ["@platforms//os:linux"])，以及其工具可在其上运行的计算机的 constraint_value (exec_compatible_with = ["@platforms//os:mac"])。

构建 $ bazel build //:myproject --platforms=//:myplatform 时，Bazel 会自动选择可在构建机器上运行的工具链，并为 //:myplatform 构建二进制文件。这称为“工具链解析”。

您可以使用 register_toolchains 在 MODULE.bazel 文件中注册一组可用工具链，也可以使用 --extra_toolchains 在命令行中注册。

如需了解详情，请点击此处。

问题

如需常规支持以及有关迁移时间表的问题，请与 bazel-discuss 或相应规则的所有者联系。

如需讨论平台/工具链 API 的设计和演变，请与 bazel-dev 联系。