迁移到平台

报告问题 查看来源 每晚 · 7.2。 · 7.1敬上 · 7.0 · 6.5 · 6.4。

Bazel 为建模提供复杂的支持 平台和工具链，支持多架构和 交叉编译 build。

本页总结了这项支持的状态。

另请参阅：

状态

C++

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

这意味着您可以用以下代码配置 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

在以下情况下，Android 规则会使用平台来选择工具链 已设置 --incompatible_enable_android_toolchain_resolution。

这意味着您可以用以下代码配置 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++）和平台 映射。

其他语言

如果您有语言规则集，请参阅迁移规则集，了解如何将 联系。

背景

引入了平台和工具链，以标准化软件 项目针对不同的架构并进行交叉编译。

这是 启发了 观察到语言维护者已经在广告 临时的、不兼容的方式。例如，C++ 规则使用 --cpu 和 --crosstool_top，用于声明目标 CPU 和工具链。以上都不是 对“平台”进行正确建模。这会产生尴尬且不正确的 build。

Java、Android 和其他语言也为了类似目的而演化了自己的标志， 它们之间不会相互作用这使得构建跨语言构建 复杂而复杂。

Bazel 适用于大型、多语言和多平台项目。这个 需要更有条理地支持这些概念，包括明确 标准 API。

需要迁移

升级到新 API 需要完成两项工作：发布 API 和升级 规则逻辑来使用它

第一个已经完成，但第二个仍在继续。其中包括确保 特定于语言的平台和工具链已定义，语言逻辑读取 工具链，而不是 --crosstool_top 等旧标志；以及 config_setting 选择使用新 API（而不是旧标志）。

这项工作非常简单，但需要针对每种语言做出不同的努力， 并提醒项目所有者测试即将发生的变化。

因此，此次迁移仍在进行中。

目标

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

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

这意味着：

  1. 项目的规则会为 //:myplatform 选择合适的工具链。
  2. 您项目的依赖项会为 //:myplatform 选择合适的工具链。
  3. //:myplatform 参考 通用声明 （共 CPU、OS 和其他与语言无关的通用属性）
  4. 所有相关的 select() 均与 //:myplatform 正确匹配。
  5. //:myplatform 在清晰且易于访问的位置定义：在项目的 repo（如果平台对于您的项目是唯一的）或者 使用项目可以找到它

--cpu、--crosstool_top 和 --fat_apk_cpu 等旧标志将被 我们会在安全的情况下尽快弃用并移除。

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

迁移项目

如果您使用支持平台的语言构建应用，您的 build 应该已经 处理如下调用：

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

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

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

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

  1. “//:myplatform”必须存在。这通常由项目所有者负责 因为不同的项目针对的是不同的机器。 请参阅默认平台。

  2. 您要使用的工具链必须存在。如果使用库存工具链， 语言所有者应提供注册方法说明。如果 编写自己的自定义工具链，需要在现有工具链中注册它们 WORKSPACE 或 --extra_toolchains。

  3. select() 和配置转换 正确解析。请参阅 select() 和转场。

  4. 如果您的 build 混合使用支持和不支持平台的语言，您可能 需要平台映射，以帮助旧版语言与新的 API 配合使用。 如需了解详情，请参阅平台映射。

如果仍有问题，请与我们联系以寻求支持。

默认平台

项目所有者应定义明确的 平台： 希望为之打造产品然后，您可以使用 --platforms 触发这些事件。

如果未设置 --platforms，则 Bazel 默认使用一个 platform 表示 本地构建机器。这是 @local_config_platform//:host 自动生成的 因此无需明确定义它会映射本地机器的 OS 以及 CPU（其中声明了 constraint_value） @platforms。

select()

项目可以select() constraint_value 个目标，但尚未完成 平台。这是有意为之，因此 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" }或使用平台 映射，以便在迁移过程中同时支持这两种样式。 窗口。

迁移规则集

如果您拥有一组规则，并且希望为平台提供支持，则需要执行以下操作：

  1. 让规则逻辑通过工具链 API 解析工具链。请参阅 toolchain API (ctx.toolchains)。

  2. 可选：定义一个 --incompatible_enable_platforms_for_my_language 标志， 规则逻辑通过新 API 或旧标志交替解析工具链 例如在迁移测试期间使用 --crosstool_top。

  3. 定义构成平台组件的相关属性。请参阅 通用平台属性

  4. 定义标准工具链，并让用户能够通过 规则的注册说明（详情）

  5. 确保 select() 和 配置转换支持平台。这是 最大的挑战。对于多语言项目来说，这尤其具有挑战性。 （如果所有语言都无法读取 --platforms，则可能会失败）。

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

通用平台属性

OS 和 CPU 等通用的跨语言平台属性应该 在 @platforms 中声明。 这有利于促进共享、标准化和跨语言兼容性。

您的规则所独有的属性应在规则的代码库中声明。这个 让您能够明确掌握所制定的具体概念 错误。

如果您的规则使用自定义操作系统或 CPU，则应在 与 @platforms。

平台映射

平台映射是一种临时 API，可让平台感知型逻辑与 旧版逻辑。这是一款钝器， 能够轻松顺畅地不兼容迁移时间范围。

平台映射是 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 使用此 ID 来保证所有设置，包括基于平台的设置 在整个构建过程中始终适用，包括 过渡。

默认情况下，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 是机器 属性。同一“kind”的值归到一个通用规则下 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"]) 以及他们的工具 运行位置 (exec_compatible_with = ["@platforms//os:mac"]).

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

您可以使用以下命令在 WORKSPACE 中注册这组可用工具链 register_toolchains或在 和 --extra_toolchains 搭配使用。

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

问题

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

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

另请参阅