概览
为了使用适当的选项调用编译器,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
属性,您可以指定要传送到沙盒中的链接器二进制文件和工具链库。
工具链选择
工具链选择逻辑的运作方式如下:
用户在
BUILD
文件中指定cc_toolchain_suite
目标,并使用--crosstool_top
选项将 Bazel 指向目标。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' ]), ] |
特征级别。仅当启用了指定的必需功能时,才支持该功能。例如,某项功能仅在某些构建模式(opt 、dbg 或 fastbuild )下受支持。如果“require”包含多个“feature_set”,只要满足任一“feature_set”即可(启用所有指定的功能时),就支持该功能。
|
implies = ['feature'] |
特征级别。此功能暗示指定的特征。 启用某个功能也会隐式启用它隐含的所有功能(即,以递归方式运行)。 此外,它还能够从一组功能中分离出常见的功能子集,例如排错程序的常见部分。隐含功能无法停用。 |
provides = ['feature'] |
特征级别。表示此地图项是若干互斥的替代功能之一。例如,所有排错程序都可以指定 当用户要求同时提供两个或更多互斥功能时,这样可以通过列出替代方案来提高错误处理效率。 |
with_features = [ with_feature_set( features = ['feature-1'], not_features = ['feature-2'], ), ] |
标志集级别。一项功能可以指定带有多个标志的多个标志集。指定 with_features 后,仅当至少有一个 with_feature_set 启用了指定的 features 集中的所有功能,并且 not_features 集中指定的所有功能都处于停用状态时,标记集才会展开为构建命令。
如果未指定 with_features ,系统将无条件地为指定的每项操作应用该标志集。
|
Action
通过操作,您可以灵活地修改操作的执行情况,而无需假设操作的运行方式。action_config
指定操作调用的工具二进制文件,而 feature
指定配置(标志),该配置决定在调用操作时该工具的行为。
功能通过引用操作来指明它们会影响哪些 Bazel 操作,因为操作可以修改 Bazel 操作图。CcToolchainConfigInfo
提供程序包含一些操作,这些操作具有标志和相关联的工具,例如 c++-compile
。系统会通过将每项操作与某项功能相关联来为其分配标志。
每个操作名称都代表 Bazel 执行的一种操作类型,例如编译或链接。不过,操作与 Bazel 操作类型之间存在多对一关系,其中 Bazel 操作类型是指实现操作的 Java 类(如 CppCompileAction
)。具体而言,下表中的“编译器操作”和“编译器操作”为 CppCompileAction
,而链接操作为 CppLinkAction
。
汇编器操作
操作 | 说明 |
preprocess-assemble
|
通过预处理进行汇编。通常用于 .S 文件。
|
assemble
|
无需预处理即可汇编。通常用于 .s 文件。
|
编译器操作
操作 | 说明 |
cc-flags-make-variable
|
将 CC_FLAGS 传播到 Genrule。
|
c-compile
|
编译为 C 语言。 |
c++-compile
|
编译为 C++。 |
c++-header-parsing
|
对头文件运行编译器的解析器,以确保头文件是独立的,否则会产生编译错误。仅适用于支持模块的工具链。 |
链接操作
操作 | 说明 |
c++-link-dynamic-library
|
关联包含其所有依赖项的共享库。 |
c++-link-nodeps-dynamic-library
|
关联仅包含 cc_library 来源的共享库。
|
c++-link-executable
|
关联可供运行的最终库。 |
AR 操作
AR 操作通过 ar
将对象文件汇编到归档库(.a
文件)中,并将一些语义编码到名称中。
操作 | 说明 |
c++-link-static-library
|
创建静态库(归档)。 |
LTO 操作
操作 | 说明 |
lto-backend
|
将位码编译到原生对象的 ThinLTO 操作。 |
lto-index
|
生成全局索引的 ThinLTO 操作。 |
使用 action_config
action_config
是一个 Starlark 结构体,通过指定要在操作期间调用的工具(二进制文件)以及由功能定义的标志集来描述 Bazel 操作。这些标志会对操作的执行施加约束。
action_config()
构造函数包含以下参数:
属性 | 说明 |
action_name
|
此操作对应的 Bazel 操作。 Bazel 使用此属性来探索每项操作的工具和执行要求。 |
tools
|
要调用的可执行文件。应用于操作的工具将是列表中第一个具有与功能配置匹配的功能集的工具。必须提供默认值。 |
flag_sets
|
适用于一组操作的标志列表。与功能相同。 |
env_sets
|
应用于一组操作的环境限制条件列表。与功能相同。 |
action_config
可以要求并隐含其他特征和 action_config
,如前文所述的特征关系所规定。此行为与功能类似。
最后两个属性对于地图项的相应属性来说是多余的,之所以包含这些属性,是因为某些 Bazel 操作需要特定标志或环境变量,目标是避免不必要的 action_config
+feature
对。通常,最好在多个 action_config
之间共享一项功能。
在同一工具链中,不能使用相同的 action_name
定义多个 action_config
。这样可以防止工具路径产生歧义,并强制执行 action_config
背后的意图 - 操作的属性在工具链中的单个位置进行明确描述。
使用工具构造函数
action_config
可以通过其 tools
参数指定一组工具。tool()
构造函数接受以下参数:
字段 | 说明 |
path
|
相关工具的路径(相对于当前位置)。 |
with_features
|
一个特征集列表,其中必须至少满足一个特征集才能应用此工具。 |
对于给定的 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 变量的引用。
变量 | 操作 | 说明 |
source_file
|
compile | 要编译的源文件。 |
input_file
|
strip | 要剥离的工件。 |
output_file
|
编译、剥离 | 编译输出。 |
output_assembly_file
|
compile | 发出的汇编文件。仅在 compile 操作发出汇编文本时适用(通常在使用 --save_temps 标志时)。内容与 output_file 相同。
|
output_preprocess_file
|
compile | 预处理的输出。仅适用于仅对源文件进行预处理的编译操作,通常在使用 --save_temps 标志时。内容与 output_file 相同。
|
includes
|
compile | 编译器必须无条件地包含在编译的源代码中的文件序列。 |
include_paths
|
compile | 编译器会在其中搜索使用 #include<foo.h> 和 #include "foo.h" 包含的头文件的序列目录。
|
quote_include_paths
|
compile | -iquote 序列包括 - 目录,编译器会在这些目录中搜索使用 #include "foo.h" 包含的头文件。
|
system_include_paths
|
compile | -isystem 序列包括 - 目录,编译器会在这些目录中搜索使用 #include <foo.h> 包含的头文件。
|
dependency_file
|
compile | 编译器生成的 .d 依赖项文件。 |
preprocessor_defines
|
compile | defines 的序列,例如 --DDEBUG 。
|
pic
|
compile | 将输出编译为位置无关代码。 |
gcov_gcno_file
|
compile | gcov 覆盖率文件。
|
per_object_debug_info_file
|
compile | 每个对象的调试信息 (.dwp ) 文件。
|
stripotps
|
strip | stripopts 的序列。
|
legacy_compile_flags
|
compile | 旧版 CROSSTOOL 字段(如 compiler_flag 、optional_compiler_flag 、cxx_flag 和 optional_cxx_flag )的标志序列。
|
user_compile_flags
|
compile | 来自 copt 规则属性或 --copt 、--cxxopt 和 --conlyopt 标志的标志序列。
|
unfiltered_compile_flags
|
compile | unfiltered_cxx_flag 旧版 CROSSTOOL 字段或 unfiltered_compile_flags 功能的标志序列。这些规则不按 nocopts 规则属性进行过滤。 |
sysroot
|
sysroot 。
|
|
runtime_library_search_directories
|
链接 | 链接器运行时搜索路径(通常通过 -rpath 标志设置)中的条目。
|
library_search_directories
|
链接 | 链接器搜索路径中的条目(通常通过 -L 标志设置)。
|
libraries_to_link
|
链接 | 提供相应文件以在链接器调用中作为输入进行链接的标志。 |
def_file_path
|
链接 | 在装有 MSVC 的 Windows 上使用的 def 文件的位置。 |
linker_param_file
|
链接 | bazel 创建的用于克服命令行长度限制的链接器参数文件的位置。 |
output_execpath
|
链接 | 链接器输出的执行路径。 |
generate_interface_library
|
链接 | "yes" 或 "no" ,具体取决于是否应生成接口库。
|
interface_library_builder_path
|
链接 | 接口库构建器工具的路径。 |
interface_library_input_path
|
链接 | 接口库 ifso 构建器工具的输入。 |
interface_library_output_path
|
链接 | 使用 ifso 构建器工具生成接口库的路径。 |
legacy_link_flags
|
链接 | 来自旧版 CROSSTOOL 字段的链接器标记。 |
user_link_flags
|
链接 | 来自 --linkopt 或 linkopts 属性的链接器标记。
|
linkstamp_paths
|
链接 | 提供 linkstamp 路径的 build 变量。 |
force_pic
|
链接 | 此变量的存在表示应生成 PIC/PIE 代码(已传递 Bazel 选项 `--force_pic`)。 |
strip_debug_symbols
|
链接 | 此变量的存在表示应剥离调试符号。 |
is_cc_test
|
链接 | 当前操作是 cc_test 链接操作时为 true,否则为 false。
|
is_using_fission
|
编译, 链接 | 此变量的存在表示裂变(每个对象的调试信息)已激活。调试信息将位于 .dwo 文件中(而非 .o 文件中),编译器和链接器需要知道这一点。
|
fdo_instrument_path
|
编译, 链接 | 存储 FDO 插桩配置文件的目录的路径。 |
fdo_profile_path
|
compile | FDO 配置文件的路径。 |
fdo_prefetch_hints_path
|
compile | 缓存预提取配置文件的路径。 |
cs_fdo_instrument_path
|
编译, 链接 | 指向存储上下文敏感 FDO 插桩配置文件的目录的路径。 |
已知特征
以下是相关功能及其启用条件的参考文档。
功能 | 文档 |
opt | dbg | fastbuild
|
根据编译模式默认处于启用状态。 |
static_linking_mode | dynamic_linking_mode
|
根据链接模式默认处于启用状态。 |
per_object_debug_info
|
如果指定并启用 supports_fission 功能,并且在 --fission 标志中指定了当前编译模式,则启用。
|
supports_start_end_lib
|
启用后(并且设置了 --start_end_lib 选项),Bazel 不会链接到静态库,而是使用 --start-lib/--end-lib 链接器选项直接链接到对象。这样可以加快构建速度,因为 Bazel 不必构建静态库。
|
supports_interface_shared_libraries
|
启用(并且设置了 --interface_shared_objects 选项)后,Bazel 会将 linkstatic 设置为 False(默认为 cc_test )的目标关联到接口共享库。这样可以更快地进行增量重新关联。
|
supports_dynamic_linker
|
启用后,C++ 规则将知道工具链可以生成共享库。 |
static_link_cpp_runtimes
|
启用后,Bazel 会在静态链接模式下静态关联 C++ 运行时,并在动态链接模式下动态关联 C++ 运行时。在 cc_toolchain.static_runtime_lib 或 cc_toolchain.dynamic_runtime_lib 属性(具体取决于关联模式)中指定的工件将添加到关联操作中。
|
supports_pic
|
启用后,工具链将知道将 PIC 对象用于动态库。每当需要进行 PIC 编译时,都会出现 `pic` 变量。如果默认处于停用状态,并且传递了“--force_pic”,则 Bazel 将请求“supports_pic”并验证该功能已启用。如果该功能缺失或无法启用,则无法使用“--force_pic”。 |
static_linking_mode | dynamic_linking_mode
|
根据链接模式默认处于启用状态。 |
no_legacy_features
|
阻止 Bazel 将旧版功能添加到 C++ 配置(如果存在)。请参阅下面的功能的完整列表。 |
旧版功能修补逻辑
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
以使工具链更加独立。