C++ 工具链配置

概览

为了使用适当的选项调用编译器，Bazel 需要一些有关编译器内部构件的知识，例如包含目录和重要标志。换句话说，Bazel 需要编译器的简化模型才能理解其工作原理。

Bazel 需要知道以下信息：

• 编译器是否支持 thinLTO、模块、动态链接或 PIC（位置无关代码）。
• 指向所需工具（例如 gcc、ld、ar、objcopy 等）的路径。
• 内置系统包含目录。Bazel 需要这些信息来验证源文件中包含的所有头文件是否已在 BUILD 文件中正确声明。
• 默认的 sysroot。
• 用于编译、链接和归档的标志。
• 要用于支持的编译模式（opt、dbg、fastbuild）的标志。
• 使变量成为编译器特别需要的变量。

如果编译器支持多种架构，则 Bazel 需要单独配置这些架构。

CcToolchainConfigInfo 提供程序，可为配置 Bazel C++ 规则的行为提供必要的精细度。默认情况下，Bazel 会自动为您的构建配置 CcToolchainConfigInfo，但您可以选择手动配置。为此，您需要一条提供 CcToolchainConfigInfo 的 Starlark 规则，并将 cc_toolchain 的 toolchain_config 属性指向您的规则。您可以通过调用 cc_common.create_cc_toolchain_config_info() 来创建 CcToolchainConfigInfo。您可以在 @rules_cc//cc:cc_toolchain_config_lib.bzl 中找到此过程中需要的所有结构体的 Starlark 构造函数。

当 C++ 目标进入分析阶段时，Bazel 会根据 BUILD 文件选择相应的 cc_toolchain 目标，并从 cc_toolchain.toolchain_config 属性中指定的目标获取 CcToolchainConfigInfo 提供程序。cc_toolchain 目标会通过 CcToolchainProvider 将这些信息传递给 C++ 目标。

例如，由 cc_binary 或 cc_library 等规则实例化的编译或链接操作需要以下信息：

• 要使用的编译器或链接器
• 编译器/链接器的命令行标记
• 通过 --copt/--linkopt 选项传递的配置标志
• 环境变量
• 执行操作的沙盒所需的工件

除了沙盒中所需的工件之外，上述所有信息都在 cc_toolchain 指向的 Starlark 目标中指定。

要传送到沙盒的工件在 cc_toolchain 目标中声明。例如，借助 cc_toolchain.linker_files 属性，您可以指定要传送到沙盒中的链接器二进制文件和工具链库。

工具链选择

工具链选择逻辑的运作方式如下：

1. 用户在 BUILD 文件中指定 cc_toolchain_suite 目标，并使用 --crosstool_top 选项将 Bazel 指向目标。

2. cc_toolchain_suite 目标引用多个工具链。--cpu 和 --compiler 标志的值决定选择哪一个工具链。具体选择是基于 --cpu 标志值，还是根据联合 --cpu | --compiler 值进行选择。选择流程如下：

   • 如果指定了 --compiler 选项，Bazel 会从具有 --cpu | --compiler 的 cc_toolchain_suite.toolchains 属性中选择对应条目。如果 Bazel 未找到相应的条目，则会抛出错误。

   • 如果未指定 --compiler 选项，Bazel 会从 cc_toolchain_suite.toolchains 属性中选择仅包含 --cpu 的相应条目。

   • 如果未指定标志，Bazel 会检查主机系统，并根据其发现结果选择 --cpu 值。请参阅检查机制代码。

选择工具链后，Starlark 规则中相应的 feature 和 action_config 对象将控制 build（即，下文所述的项）的配置。通过这些消息，您无需修改 Bazel 二进制文件，即可在 Bazel 中实现完善的 C++ 功能。C++ 规则支持多个唯一操作，Bazel 源代码中对此进行了详细介绍。

特性

功能是需要命令行标志、操作、对执行环境的限制或更改依赖项的实体。功能可以非常简单，比如允许 BUILD 文件选择标志配置（例如 treat_warnings_as_errors），或与 C++ 规则交互并向编译添加新编译操作和输入（例如 header_modules 或 thin_lto）。

理想情况下，CcToolchainConfigInfo 包含一系列功能，其中每个功能都包含一个或多个标志组，每个标志组都定义了一个适用于特定 Bazel 操作的标志列表。

功能按名称指定，这允许将 Starlark 规则配置与 Bazel 版本完全分离。换句话说，Bazel 版本不会影响 CcToolchainConfigInfo 配置的行为，前提是这些配置不需要使用新功能。

您可以通过以下其中一种方式启用功能：

• 该地图项的 enabled 字段设置为 true。
• Bazel 或规则所有者明确启用了它。
• 用户通过 --feature Bazel 选项或 features 规则属性启用该角色。

各项功能可以具有相互依赖性，具体取决于命令行标志、BUILD 文件设置和其他变量。

特征关系

依赖项通常直接使用 Bazel 进行管理，Bazel 只会强制执行要求并管理与 build 中定义的功能性质的固有冲突。工具链规范允许直接在管理功能支持和扩展的 Starlark 规则中使用更精细的限制。具体包括：

requires = [
   feature_set (features = [
       'feature-name-1',
       'feature-name-2'
   ]),
]

implies = ['feature']

provides = ['feature']

with_features = [
  with_feature_set(
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]

Action

通过操作，您可以灵活地修改操作的执行情况，而无需假设操作的运行方式。action_config 指定操作调用的工具二进制文件，而 feature 指定配置（标志），该配置决定在调用操作时该工具的行为。

功能通过引用操作来指明它们会影响哪些 Bazel 操作，因为操作可以修改 Bazel 操作图。CcToolchainConfigInfo 提供程序包含一些操作，这些操作具有标志和相关联的工具，例如 c++-compile。系统会通过将每项操作与某项功能相关联来为其分配标志。

每个操作名称都代表 Bazel 执行的一种操作类型，例如编译或链接。不过，操作与 Bazel 操作类型之间存在多对一关系，其中 Bazel 操作类型是指实现操作的 Java 类（如 CppCompileAction）。具体而言，下表中的“编译器操作”和“编译器操作”为 CppCompileAction，而链接操作为 CppLinkAction。

汇编器操作

编译器操作

链接操作

AR 操作

AR 操作通过 ar 将对象文件汇编到归档库（.a 文件）中，并将一些语义编码到名称中。

LTO 操作

使用 action_config

action_config 是一个 Starlark 结构体，通过指定要在操作期间调用的工具（二进制文件）以及由功能定义的标志集来描述 Bazel 操作。这些标志会对操作的执行施加约束。

action_config() 构造函数包含以下参数：

action_config 可以要求并隐含其他特征和 action_config，如前文所述的特征关系所规定。此行为与功能类似。

最后两个属性对于地图项的相应属性来说是多余的，之所以包含这些属性，是因为某些 Bazel 操作需要特定标志或环境变量，目标是避免不必要的 action_config+feature 对。通常，最好在多个 action_config 之间共享一项功能。

在同一工具链中，不能使用相同的 action_name 定义多个 action_config。这样可以防止工具路径产生歧义，并强制执行 action_config 背后的意图 - 操作的属性在工具链中的单个位置进行明确描述。

使用工具构造函数

action_config 可以通过其 tools 参数指定一组工具。tool() 构造函数接受以下参数：

对于给定的 action_config，只有一个 tool 会将其工具路径和执行要求应用于 Bazel 操作。如需选择某个工具，请在 action_config 上迭代 tools 属性，直到找到 with_feature 集与功能配置匹配的工具（如需了解详情，请参阅本页前面的特征关系）。您应以与空功能配置对应的默认工具作为工具列表的结尾。

用法示例

可以结合使用功能和操作来实现具有各种跨平台语义的 Bazel 操作。例如，若要在 macOS 上生成调试符号，您需要在编译操作中生成符号，然后在链接操作期间调用专用工具以创建压缩的 dsym 归档文件，接着解压缩该归档文件，生成可供 Xcode 使用的应用软件包和 .plist 文件。

使用 Bazel 时，可以按如下方式实现此流程，其中 unbundle-debuginfo 是一项 Bazel 操作：

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (path = "toolchain/mac/ld"),
        ],
    ),
]

features = [
    feature(
        name = "generate-debug-symbols",
        flag_sets = [
            flag_set (
                actions = [
                    ACTION_NAMES.c_compile,
                    ACTION_NAMES.cpp_compile
                ],
                flag_groups = [
                    flag_group(
                        flags = ["-g"],
                    ),
                ],
            )
        ],
        implies = ["unbundle-debuginfo"],
   ),
]

对于使用 fission 的 Linux 或生成 .pdb 文件的 Windows，可以完全以不同的方式实现相同的功能。例如，基于 fission 的调试符号生成实现可能如下所示：

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            tool(
                path = "toolchain/bin/gcc",
            ),
        ],
    ),
]

features = [
    feature (
        name = "generate-debug-symbols",
        requires = [with_feature_set(features = ["dbg"])],
        flag_sets = [
            flag_set(
                actions = [ACTION_NAMES.cpp_compile],
                flag_groups = [
                    flag_group(
                        flags = ["-gsplit-dwarf"],
                    ),
                ],
            ),
            flag_set(
                actions = [ACTION_NAMES.cpp_link_executable],
                flag_groups = [
                    flag_group(
                        flags = ["-Wl", "--gdb-index"],
                    ),
                ],
            ),
      ],
    ),
]

标志组

CcToolchainConfigInfo 允许您将标志捆绑到用于特定用途的组中。您可以在标记值中使用预定义变量指定一个标记，编译器会在将标记添加到构建命令时扩展该标记。例如：

flag_group (
    flags = ["%{output_execpath}"],
)

在这种情况下，该标志的内容将被替换为相应操作的输出文件路径。

标志组会按照其在列表中显示的顺序（从上到下、从左到右）展开到构建命令。

对于在添加到构建命令时需要使用不同值重复的标志，标志组可以迭代 list 类型的变量。例如，类型为 list 的变量 include_path：

flag_group (
    iterate_over = "include_paths",
    flags = ["-I%{include_paths}"],
)

对于 include_paths 列表中的每个路径元素，扩展为 -I<path>。标志组声明正文中的所有标志（或 flag_group）都作为一个单元进行扩展。例如：

flag_group (
    iterate_over = "include_paths",
    flags = ["-I", "%{include_paths}"],
)

对于 include_paths 列表中的每个路径元素，扩展为 -I <path>。

一个变量可以重复多次。例如：

flag_group (
    iterate_over = "include_paths",
    flags = ["-iprefix=%{include_paths}", "-isystem=%{include_paths}"],
)

会扩展为：

-iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1>

变量可以对应于可通过点分表示法访问的结构。例如：

flag_group (
    flags = ["-l%{libraries_to_link.name}"],
)

结构可以嵌套，也可以包含序列。为防止名称冲突并确保名称明确，您必须通过这些字段指定完整路径。例如：

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flags = ["-l%{libraries_to_link.shared_libraries.name}"],
        ),
    ],
)

条件扩展

标志组支持根据存在使用 expand_if_available、expand_if_not_available、expand_if_true、expand_if_false 或 expand_if_equal 属性的特定变量或其字段进行条件扩展。例如：

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flag_groups = [
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--whole_archive"],
                ),
                flag_group (
                    flags = ["-l%{libraries_to_link.shared_libraries.name}"],
                ),
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--no_whole_archive"],
                ),
            ],
        ),
    ],
)

CcToolchainConfigInfo 参考文档

本部分提供了成功配置 C++ 规则所需的 build 变量、功能和其他信息的参考信息。

CcToolchainConfigInfo 构建变量

以下是对 CcToolchainConfigInfo build 变量的引用。

已知特征

以下是相关功能及其启用条件的参考文档。

旧版功能修补逻辑

Bazel 会将以下更改应用于工具链的功能，以实现向后兼容性：

• 将 legacy_compile_flags 功能移至工具链顶部
• 将 default_compile_flags 功能移至工具链顶部
• 将 dependency_file（如果不存在）功能添加到工具链顶部
• 将 pic（如果不存在）功能添加到工具链顶部
• 将 per_object_debug_info（如果不存在）功能添加到工具链顶部
• 将 preprocessor_defines（如果不存在）功能添加到工具链顶部
• 将 includes（如果不存在）功能添加到工具链顶部
• 将 include_paths（如果不存在）功能添加到工具链顶部
• 将 fdo_instrument（如果不存在）功能添加到工具链顶部
• 将 fdo_optimize（如果不存在）功能添加到工具链顶部
• 将 cs_fdo_instrument（如果不存在）功能添加到工具链顶部
• 将 cs_fdo_optimize（如果不存在）功能添加到工具链顶部
• 将 fdo_prefetch_hints（如果不存在）功能添加到工具链顶部
• 将 autofdo（如果不存在）功能添加到工具链顶部
• 将 build_interface_libraries（如果不存在）功能添加到工具链顶部
• 将 dynamic_library_linker_tool（如果不存在）功能添加到工具链顶部
• 将 shared_flag（如果不存在）功能添加到工具链顶部
• 将 linkstamps（如果不存在）功能添加到工具链顶部
• 将 output_execpath_flags（如果不存在）功能添加到工具链顶部
• 将 runtime_library_search_directories（如果不存在）功能添加到工具链顶部
• 将 library_search_directories（如果不存在）功能添加到工具链顶部
• 将 archiver_flags（如果不存在）功能添加到工具链顶部
• 将 libraries_to_link（如果不存在）功能添加到工具链顶部
• 将 force_pic_flags（如果不存在）功能添加到工具链顶部
• 将 user_link_flags（如果不存在）功能添加到工具链顶部
• 将 legacy_link_flags（如果不存在）功能添加到工具链顶部
• 将 static_libgcc（如果不存在）功能添加到工具链顶部
• 将 fission_support（如果不存在）功能添加到工具链顶部
• 将 strip_debug_symbols（如果不存在）功能添加到工具链顶部
• 将 coverage（如果不存在）功能添加到工具链顶部
• 将 llvm_coverage_map_format（如果不存在）功能添加到工具链顶部
• 将 gcc_coverage_map_format（如果不存在）功能添加到工具链顶部
• 将 fully_static_link（如果不存在）功能添加到工具链底部
• 将 user_compile_flags（如果不存在）功能添加到工具链底部
• 将 sysroot（如果不存在）功能添加到工具链底部
• 将 unfiltered_compile_flags（如果不存在）功能添加到工具链底部
• 将 linker_param_file（如果不存在）功能添加到工具链底部
• 将 compiler_input_flags（如果不存在）功能添加到工具链底部
• 将 compiler_output_flags（如果不存在）功能添加到工具链底部

这是一个很长的功能列表。我们计划在完成 Starlark 中的交叉工具后即将其移除。如有好奇的读者，请参阅 CppActionConfigs 中的实现；对于生产工具链，请考虑添加 no_legacy_features 以使工具链更加独立。