此页面由 Cloud Translation API 翻译。

平台

报告问题查看源代码

每夜版 · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

简介

Bazel 可以在各种硬件、操作系统和系统配置上构建和测试代码。这可能涉及不同版本的构建工具，例如链接器和编译器。为了帮助管理这种复杂性，Bazel 引入了限制条件和平台的概念。

约束条件是 build 或生产机器的区分属性。常见限制包括 CPU 架构、是否存在 GPU 或本地安装的编译器的版本。不过，在编排 build 工作时，约束条件可以是能有效区分机器的任何内容。

平台是一组用于指定完整机器的限制条件。Bazel 使用此概念让开发者选择要构建的目标机器、应运行编译和测试操作的机器，以及构建操作应使用哪些工具链进行编译。

开发者还可以使用限制条件来选择 build 规则中的自定义属性或依赖项。例如：“当 build 目标为 Arm 机器时，使用 src_arm.cc”。

平台类型

Bazel 可识别平台可能扮演的三种角色：

主机 - Bazel 本身运行的平台。
执行 - 一种运行编译操作以生成 build 输出的平台。
目标 - 构建的代码应在哪个平台上运行。

build 通常与平台有三种关系：

单平台 build - 宿主平台、执行平台和目标平台相同。例如，在没有远程执行功能的开发者机器上进行构建，然后在同一机器上运行构建的二进制文件。
交叉编译 build - 宿主平台和执行平台相同，但目标平台不同。例如，在 Macbook Pro 上构建 iOS 应用，但不进行远程执行。
多平台 build - 宿主平台、执行平台和目标平台各不相同。例如，在 Macbook Pro 上构建 iOS 应用，并使用远程 Linux 机器编译不需要 Xcode 的 C++ 操作。

指定平台

开发者使用平台最常见的方式是通过 --platforms 标志指定所需的目标机器：

$ bazel build //:my_linux_app --platforms=//myplatforms:linux_x86

组织通常会维护自己的平台定义，因为构建机器设置因组织而异。

如果未设置 --platforms，则默认为 @platforms//host。此属性经过专门定义，用于自动检测宿主机器的操作系统和 CPU 属性，以便 build 针对 Bazel 运行的同一机器。构建规则可以使用 @platforms/os 和 @platforms/cpu 限制条件，根据这些属性进行选择。

一般有用的限制条件和平台

为了保持生态系统的一致性，Bazel 团队维护了一个代码库，其中包含最常用的 CPU 架构和操作系统的限制定义。这些都在 https://github.com/bazelbuild/platforms 中定义。

Bazel 随附以下特殊平台定义：@platforms//host（别名为 @bazel_tools//tools:host_platform）。此平台定义可自动检测运行 Bazel 的机器的操作系统和 CPU 属性。

定义限制条件

限制条件通过 constraint_setting 和 constraint_value build 规则进行建模。

constraint_setting 声明一种属性类型。例如：

constraint_setting(name = "cpu")

constraint_value 声明了相应属性的一个可能值：

constraint_value(
    name = "x86",
    constraint_setting = ":cpu"
)

在定义平台或自定义平台上的 build 规则时，可以将其作为标签进行引用。如果上述示例是在 cpus/BUILD 中定义的，您可以将 x86 限制条件引用为 //cpus:x86。

如果可见性允许，您可以为现有 constraint_setting 定义自己的值，从而对其进行扩展。

定义平台

platform build 规则将平台定义为 constraint_value 的集合：

platform(
    name = "linux_x86",
    constraint_values = [
        "//oses:linux",
        "//cpus:x86",
    ],
)

此模型表示必须同时具有 //oses:linux 和 //cpus:x86 约束的机器。

对于给定的 constraint_setting，平台只能有一个 constraint_value。这意味着，除非您创建另一个 constraint_setting 类型来对第二个值进行建模，否则平台不能有两个 CPU。

跳过不兼容的定位条件

在为特定目标平台构建时，通常需要跳过永远无法在该平台上运行的目标。例如，在搭载 //... 的 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

已知问题

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