平台

报告问题 查看源代码 每夜 build · 8.0 . 7.4 。 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel 可以使用许多不同版本的构建工具（例如链接器和编译器）在各种硬件、操作系统和系统配置上构建和测试代码。为了帮助管理这种复杂性，Bazel 引入了约束条件和平台的概念。约束条件是 build 或生产环境可能存在差异的一个维度，例如 CPU 架构、是否存在 GPU 或系统安装的编译器的版本。平台是这些约束条件的命名选项集合，表示某些环境中可用的特定资源。

将环境建模为平台有助于 Bazel 自动为构建操作选择适当的工具链。平台还可以与 config_setting 规则结合使用，以写入可配置属性。

Bazel 可以识别平台可能承担的三种角色：

  • 主机 - Bazel 本身运行的平台。
  • 执行 - 构建工具在其中执行构建操作以生成中间和最终输出的平台。
  • 目标平台 - 最终输出所在并执行的平台。

Bazel 支持以下平台 build 场景：

  • 单平台 build（默认）- 承载平台、执行平台和目标平台相同。例如，在搭载 Intel x64 CPU 的 Ubuntu 上构建 Linux 可执行文件。

  • 交叉编译 build - 承载平台和执行平台相同，但目标平台不同。例如，在搭载 macOS 的 MacBook Pro 上构建 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 指定平台

您可以使用以下命令行标志指定 build 的宿主平台和目标平台：

  • --host_platform - 默认为 @bazel_tools//tools:host_platform
    • 此目标的别名为 @platforms//host，后者由用于检测主机操作系统和 CPU 并写入平台目标的代码库规则提供支持。
    • 此外，还有 @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"],
    }),
)

上述内容可解读为：

  1. 以 macOS 为目标平台时，目标平台没有任何限制。
  2. 定位到 Linux 时，目标没有任何限制。
  3. 否则，目标具有 @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

已知问题

不兼容的目标会忽略可见性限制。