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。
第一个已经完成,但第二个仍在继续。这包括确保定义特定语言的平台和工具链,语言逻辑通过新 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
等旧标志,确保安全无害。
最终,这将是配置架构的唯一方式。
迁移项目
如果您使用支持平台的语言进行构建,则构建应该已经可以使用如下调用:
bazel build //:myproject --platforms=//:myplatform
如需了解确切的详细信息,请参阅状态和所用语言的文档。
如果某个语言需要标志才能启用平台支持,您还需要设置该标志。如需了解详情,请参阅状态。
为了构建您的项目,您需要检查以下内容:
“
//:myplatform
”必须存在。通常,项目所有者负责定义平台,因为不同的项目针对的是不同的机器。请参阅默认平台。您要使用的工具链必须存在。如果使用库存工具链,则语言所有者应包含有关如何注册它们的说明。如果要编写自己的自定义工具链,您需要在
WORKSPACE
中或使用--extra_toolchains
注册它们。register如果您的 build 混合使用支持和不支持平台的语言,您可能需要进行平台映射,以帮助旧版语言与新的 API 配合使用。如需了解详情,请参阅平台映射。
如果仍有问题,请与我们联系以寻求支持。
默认平台
项目所有者应定义明确的平台,以描述他们想要针对哪些架构构建应用。然后,您可以使用 --platforms
触发这些事件。
如果未设置 --platforms
,则 Bazel 默认使用表示本地构建机器的 platform
。该代码是在 @local_config_platform//:host
中自动生成的,因此无需明确定义。它会将本地计算机的 OS
和 CPU
与 @platforms
中声明的 constraint_value
进行映射。
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" }
,或使用平台映射在迁移期间支持这两种样式。
迁移规则集
如果您拥有一组规则,并且希望为平台提供支持,则需要执行以下操作:
让规则逻辑通过工具链 API 解析工具链。请参阅 toolchain API (
ctx.toolchains
)。可选:定义一个
--incompatible_enable_platforms_for_my_language
标志,以便规则逻辑在迁移测试期间通过新 API 或旧标志(如--crosstool_top
)交替解析工具链。定义构成平台组件的相关属性。请参阅通用平台属性
定义标准工具链,并通过规则的注册说明允许用户访问这些工具链(详情)
确保
select()
和配置转换支持平台。这是最大的挑战。这对于多语言项目而言尤其具有挑战性(如果所有语言都无法读取--platforms
,则可能会失败)。
如果您需要混用不支持平台的规则,则可能需要平台映射来弥合这方面的差异。
通用平台属性
常用的跨语言平台属性(如 OS
和 CPU
)应在 @platforms
中声明。这有利于促进共享、标准化和跨语言兼容性。
您的规则所独有的属性应在规则的代码库中声明。这样,您就可以明确您的规则负责的特定概念。
如果您的规则使用自定义操作系统或 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 使用此方式来保证所有设置(包括基于平台的设置和旧版设置)在整个构建过程中始终如一地应用,包括通过过渡。
默认情况下,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"
)。其提供程序会将此信息传递给需要使用这些工具进行构建的规则。
工具链会声明它们可以作为目标平台 (target_compatible_with = ["@platforms//os:linux"]
) 的机器的 constraint_value
以及可以运行其工具的机器 (exec_compatible_with = ["@platforms//os:mac"]
)。
构建 $ bazel build //:myproject --platforms=//:myplatform
时,Bazel 会自动选择可以在构建机器上运行的工具链,并为 //:myplatform
构建二进制文件。这称为工具链解析。
您可以使用 register_toolchains
在 WORKSPACE
中注册这组可用工具链,也可以使用 --extra_toolchains
在命令行中注册。
如需了解详情,请点击此处。
问题
如需获得常规支持以及有关迁移时间表的问题,请与 bazel-comment 或相应规则的所有者联系。
如需讨论平台/工具链 API 的设计和演变,请与 bazel-dev 联系。