迁移到平台

报告问题 查看源代码

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 规则不支持平台,尚未安排提供支持。

您仍然可以将平台 API 用于 Apple build(例如,在混合使用 Apple 规则和纯 C++ 进行构建时)和平台映射

其他语言

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

背景

我们引入了平台和工具链,以便使软件项目针对不同架构和交叉编译的方式实现标准化。

这一发现的灵感来源于一项观察,即语言维护人员已经以不兼容的方式临时执行此操作。例如,C++ 规则使用 --cpu--crosstool_top 来声明目标 CPU 和工具链。这两者并不能正确地为“平台”建模。这会产生尴尬且错误的 build。

Java、Android 和其他语言出于类似目的演化了自己的标记,这些标记彼此之间没有互操作性。这使得跨语言构建变得混乱和复杂。

Bazel 适用于大型、多语言和多平台项目。这需要对这些概念的支持更有原则,包括一个明确的标准 API。

需要迁移

升级到新 API 需要完成两项工作:发布 API 以及升级规则逻辑以使用它。

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

这项工作很简单,但需要针对每种语言分别付出努力,此外还需要为项目所有者提供合理警告,让其针对即将发生的更改进行测试。

因此,此次迁移正在进行中。

目标

当所有项目都通过以下表单构建后,即完成了此迁移:

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

这意味着:

  1. 您的项目规则会为 //:myplatform 选择合适的工具链。
  2. 项目的依赖项为 //:myplatform 选择正确的工具链。
  3. //:myplatform 引用了 CPUOS 和其他与语言无关的通用属性的通用声明
  4. 所有相关的select()都与//:myplatform正确匹配。
  5. //:myplatform 在一个清晰且可访问的位置进行定义:如果平台是您的项目所独有的,请在项目的代码库中;或者所有使用项目的常用位置都可以找到该平台

我们会在安全的情况下立即弃用并移除 --cpu--crosstool_top--fat_apk_cpu 等旧标志。

归根结底,这是配置架构的唯一方式。

迁移项目

如果您使用支持平台的语言进行构建,您的构建应该已可使用如下调用:

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

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

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

为了构建项目,您需要检查以下内容:

  1. //:myplatform 必须存在。通常,项目所有者负责定义平台,因为不同的项目面向不同的机器。请参阅默认平台

  2. 您要使用的工具链必须存在。如果使用库存工具链,语言所有者应包含有关如何注册它们的说明。如果您要编写自己的自定义工具链,则需要在 MODULE.bazel 文件或 --extra_toolchainsregister它们。

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

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

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

默认平台

项目所有者应定义明确的平台,以描述他们希望针对哪些架构构建应用。然后,系统会使用 --platforms 触发这些事件。

如果未设置 --platforms,则 Bazel 默认采用表示本地构建机器的 platform。它是在 @local_config_platform//:host 中自动生成的,因此无需明确定义。它会使用 @platforms 中声明的 constraint_value 映射本地机器的 OSCPU

select()

项目可以在 constraint_value 目标上执行 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 转换会改变 build 图的下部分标志。如果您的项目使用的转换设置了 --cpu--crossstool_top 或其他旧版标志,则读取 --platforms 的规则不会看到这些更改。

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

正在迁移规则集

如果您有规则集并希望支持平台,则需要:

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

  2. 可选:定义一个 --incompatible_enable_platforms_for_my_language 标志,以便规则逻辑在迁移测试期间通过新 API 或旧标志(如 --crosstool_top)交替解析工具链。

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

  4. 定义标准工具链,并通过规则的注册说明使其可供用户访问(详细信息

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

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

通用平台属性

常见的跨语言平台属性(如 OSCPU)应在 @platforms 中声明。这有助于促进共享、标准化和跨语言兼容性。

您的规则所独有的属性应在规则的代码库中声明。这样,您就可以始终清楚自己对规则负责的特定概念的所有权。

如果您的规则使用自定义用途的操作系统或 CPU,则应在规则的代码库中(而不是在 @platforms)中进行声明。

平台映射

平台映射是一种临时 API,可让平台感知型逻辑在同一 build 中与旧版逻辑混合使用。这是一个钝器,仅用于消除与不同迁移时间范围的不兼容性。

平台映射是 platform() 到一组相应的旧版标志的映射或反向的映射。例如:

platforms:
  # Maps "--platforms=//platforms:ios" to "--ios_multi_cpus=x86_64 --apple_platform_type=ios".
  //platforms:ios
    --ios_multi_cpus=x86_64
    --apple_platform_type=ios

flags:
  # Maps "--ios_multi_cpus=x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --ios_multi_cpus=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 使用此机制来确保所有设置(包括基于平台的设置和旧版的设置)都能在整个构建过程中(包括通过转换)保持一致。

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

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

API 审核

platformconstraint_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",
)

toolchainStarlark 规则。其属性声明了语言的工具(如 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 构建二进制文件的工具链。这称为“工具链解析”。

您可以使用 register_toolchainsMODULE.bazel 文件中注册这组可用工具链,也可以使用 --extra_toolchains 在命令行中注册。

如需了解详情,请点击此处

问题

如需获得常规支持或存在有关迁移时间表的问题,请与 bazel-think 或相应规则的所有者联系。

如需了解有关平台/工具链 API 的设计和演变的讨论,请联系 bazel-dev

另请参阅