Bazel 可以使用链接器和编译器等多种不同版本的构建工具,基于各种硬件、操作系统和系统配置构建和测试代码。为帮助处理这种复杂性,Bazel 制定了限制条件和平台概念。限制条件是构建或生产环境可能不同的维度,例如 CPU 架构、是否存在 GPU,或系统安装的编译器的版本。平台是这些限制条件的命名集合,表示某些环境中可用的特定资源。
将环境建模为平台有助于 Bazel 自动为构建操作选择合适的工具链。平台也可以与 config_setting 规则结合使用,以编写可配置属性。
Bazel 可识别平台可能充当的三种角色:
- 主机 - 运行 Bazel 的平台。
- 执行 - 构建工具会在该平台上执行构建操作,以生成中间输出和最终输出。
- 目标 - 用于存放和执行最终输出的平台。
Bazel 支持以下关于平台的构建场景:
单平台 build(默认)- 主机、执行平台和目标平台相同。例如,在 Intel x64 CPU 上运行的 Ubuntu 上构建 Linux 可执行文件。
交叉编译 build - 托管平台和执行平台相同,但目标平台不同。例如,在 MacBook Pro 上运行的 macOS 上构建 iOS 应用。
多平台 build - 托管平台、执行平台和目标平台都各不相同。
定义限制条件和平台
平台的可能选择空间使用 BUILD
文件中的 constraint_setting
和 constraint_value
规则来定义。constraint_setting
可创建新维度,而 constraint_value
则可为给定维度创建新值;它们共同有效定义枚举及其可能的值。例如,BUILD
文件的以下代码段引入了针对系统的 glibc 版本的限制,具有两个可能的值。
constraint_setting(name = "glibc_version")
constraint_value(
name = "glibc_2_25",
constraint_setting = ":glibc_version",
)
constraint_value(
name = "glibc_2_26",
constraint_setting = ":glibc_version",
)
约束条件及其值可以在工作区的不同软件包之间定义。它们通过标签引用,并受到常规可见性控制的约束。如果可见性允许,您可以通过为现有限制条件设置自定义值来对其进行扩展。
platform
规则会引入一个具有特定约束值选择的新平台。以下代码会创建一个名为 linux_x86
的平台,并称其描述了在 x86_64 架构上运行 Linux 操作系统且 glibc 版本为 2.25 的任何环境。(如需详细了解 Bazel 的内置限制条件,请参阅下文。)
platform(
name = "linux_x86",
constraint_values = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
":glibc_2_25",
],
)
一般有用的限制和平台
为了保持生态系统的一致性,Bazel 团队维护了一个代码库,其中包含针对最热门的 CPU 架构和操作系统的限制条件定义。它们都位于 https://github.com/bazelbuild/platforms。
Bazel 附带以下特殊的平台定义:@platforms//host
(别名为 @bazel_tools//tools:host_platform
)。这是自动检测的主机平台值,表示系统针对运行 Bazel 的系统自动检测的平台。
为构建指定平台
您可以使用以下命令行标志为 build 指定主机和目标平台:
--host_platform
- 默认为@bazel_tools//tools:host_platform
- 此目标的别名为
@platforms//host
,后者由检测主机操作系统和 CPU 并写入平台目标的 Repo 规则提供支持。 - 此外,还有
@platforms//host:constraints.bzl
,它公开了一个名为HOST_CONSTRAINTS
的数组,该数组可在其他 BUILD 和 Starlark 文件中使用。
- 此目标的别名为
--platforms
- 默认为主机平台- 这意味着,如果未设置其他标志,
@platforms//host
为目标平台。 - 如果设置了
--host_platform
而不是--platforms
,则--host_platform
的值既是主机平台,也是目标平台。
- 这意味着,如果未设置其他标志,
跳过不兼容的目标
在针对特定目标平台进行构建时,通常希望跳过永远无法在该平台上工作的目标。例如,使用 //...
在 Linux 计算机上进行构建时,您的 Windows 设备驱动程序可能会产生大量编译器错误。使用 target_compatible_with
属性告知 Bazel 您的代码具有哪些目标平台约束条件。
最简单的用法是将目标限制为单个平台。系统不会针对不满足所有限制条件的任何平台构建目标。以下示例将 win_driver_lib.cc
限制为在 64 位 Windows 系统上运行。
cc_library(
name = "win_driver_lib",
srcs = ["win_driver_lib.cc"],
target_compatible_with = [
"@platforms//cpu:x86_64",
"@platforms//os:windows",
],
)
:win_driver_lib
仅兼容在 64 位 Windows 系统上进行构建,而与其他所有系统都不兼容。不兼容具有传递性。任何传递性依赖于不兼容目标的目标本身都被视为不兼容。
何时会跳过目标?
如果目标被视为不兼容,并作为目标模式扩展的一部分包含在 build 中,则会跳过。例如,以下两个调用会跳过在目标模式扩展中发现的任何不兼容的目标。
$ bazel build --platforms=//:myplatform //...
$ bazel build --platforms=//:myplatform //:all
同样,如果在命令行中使用 --expand_test_suites
指定了 test_suite
,则会跳过 test_suite
中不兼容的测试。换句话说,命令行中的 test_suite
目标的行为类似于 :all
和 ...
。使用 --noexpand_test_suites
会阻止扩展,并导致包含不兼容测试的 test_suite
目标也不兼容。
在命令行上明确指定不兼容的目标会导致错误消息和构建失败。
$ bazel build --platforms=//:myplatform //:target_incompatible_with_myplatform
...
ERROR: Target //:target_incompatible_with_myplatform is incompatible and cannot be built, but was explicitly requested.
...
FAILED: Build did NOT complete successfully
如果启用了 --skip_incompatible_explicit_targets
,则会以静默方式跳过不兼容的显式目标。
更具表现力的约束条件
为了更灵活地表示限制条件,请使用任何平台无法满足的 @platforms//:incompatible
constraint_value
。
将 select()
与 @platforms//:incompatible
结合使用可以表示更复杂的限制。例如,可用于实现基本的 OR 逻辑。以下代码标记了一个与 macOS 和 Linux 但不兼容其他平台的库。
cc_library(
name = "unixish_lib",
srcs = ["unixish_lib.cc"],
target_compatible_with = select({
"@platforms//os:osx": [],
"@platforms//os:linux": [],
"//conditions:default": ["@platforms//:incompatible"],
}),
)
上述内容可解释为:
- 以 macOS 为目标平台时,目标没有限制条件。
- 以 Linux 为目标平台时,目标没有约束条件。
- 否则,目标具有
@platforms//:incompatible
约束条件。由于@platforms//:incompatible
不属于任何平台,因此目标会被视为不兼容。
为了提高约束条件的可读性,请使用 skylib 的 selects.with_or()
。
您也可以用类似的方式表示反向兼容性。以下示例介绍了与除 ARM 以外的所有内容都兼容的库。
cc_library(
name = "non_arm_lib",
srcs = ["non_arm_lib.cc"],
target_compatible_with = select({
"@platforms//cpu:arm": ["@platforms//:incompatible"],
"//conditions:default": [],
}),
)
使用 bazel cquery
检测不兼容的目标
您可以使用 bazel cquery
的 Starlark 输出格式中的 IncompatiblePlatformProvider
将不兼容的目标与兼容的目标区分开来。
这可用于滤除不兼容的目标。以下示例将仅输出兼容的目标的标签。系统不会输出不兼容的目标。
$ cat example.cquery
def format(target):
if "IncompatiblePlatformProvider" not in providers(target):
return target.label
return ""
$ bazel cquery //... --output=starlark --starlark:file=example.cquery
已知问题
不兼容的目标会忽略可见性限制。