本教程使用一个示例场景来说明如何为项目配置 C++ 工具链。
学习内容
在本教程中,您将学习如何:
- 设置构建环境
- 使用
--toolchain_resolution_debug
调试工具链解析 - 配置 C++ 工具链
- 创建一条 Starlark 规则,为
cc_toolchain
提供其他配置,以便 Bazel 可以使用clang
构建应用 - 通过在 Linux 机器上运行
bazel build //main:hello-world
来构建 C++ 二进制文件 - 通过运行
bazel build //main:hello-world --platforms=//:android_x86_64
交叉编译 Android 二进制文件
准备工作
本教程假定您使用 Linux,并且已成功构建 C++ 应用并安装了适当的工具和库。本教程使用 clang version 16
,您可以在自己的系统上安装该工具。
设置构建环境
按如下方式设置构建环境:
请下载并安装 Bazel 7.0.2 或更高版本(如果您尚未执行此操作)。
在根文件夹下添加一个空的
WORKSPACE
文件。将以下
cc_binary
目标添加到main/BUILD
文件中:load("@rules_cc//cc:defs.bzl", "cc_binary") cc_binary( name = "hello-world", srcs = ["hello-world.cc"], )
由于 Bazel 在构建过程中会使用许多用 C++ 编写的内部工具(例如
process-wrapper
),因此会为主机平台指定预先存在的默认 C++ 工具链。这样一来,这些内部工具便可使用本教程中创建的工具链进行构建。因此,cc_binary
目标也是使用默认工具链构建的。使用以下命令运行 build:
bazel build //main:hello-world
构建成功,无需在
WORKSPACE
中注册任何工具链。如需进一步查看幕后内容,请运行以下命令:
bazel build //main:hello-world --toolchain_resolution_debug='@bazel_tools//tools/cpp:toolchain_type' INFO: ToolchainResolution: Target platform @@local_config_platform//:host: Selected execution platform @@local_config_platform//:host, type @@bazel_tools//tools/cpp:toolchain_type -> toolchain @@bazel_tools~cc_configure_extension~local_config_cc//:cc-compiler-k8
如果不指定
--platforms
,Bazel 会使用@bazel_tools//cc_configure_extension/local_config_cc//:cc-compiler-k8
为@local_config_platform//:host
构建目标
配置 C++ 工具链
如需配置 C++ 工具链,请重复构建应用并逐个消除每个错误,如下所述。
此外,该示例还假定为 clang version 9.0.1
,但细节应该只在不同版本的 Clang 之间略有变化。
将
toolchain/BUILD
添加到filegroup(name = "empty") cc_toolchain( name = "linux_x86_64_toolchain", toolchain_identifier = "linux_x86_64-toolchain", toolchain_config = ":linux_x86_64_toolchain_config", all_files = ":empty", compiler_files = ":empty", dwp_files = ":empty", linker_files = ":empty", objcopy_files = ":empty", strip_files = ":empty", supports_param_files = 0, ) toolchain( name = "cc_toolchain_for_linux_x86_64", toolchain = ":linux_x86_64_toolchain", toolchain_type = "@bazel_tools//tools/cpp:toolchain_type", exec_compatible_with = [ "@platforms//cpu:x86_64", "@platforms//os:linux", ], target_compatible_with = [ "@platforms//cpu:x86_64", "@platforms//os:linux", ], )
然后使用
WORKSPACE
register_toolchains( "//toolchain:cc_toolchain_for_linux_x86_64" )
此步骤会定义
cc_toolchain
并将其绑定到主机配置的toolchain
目标。再次运行构建。由于
toolchain
软件包尚未定义linux_x86_64_toolchain_config
目标,Bazel 会抛出以下错误:ERROR: toolchain/BUILD:4:13: in toolchain_config attribute of cc_toolchain rule //toolchain:linux_x86_64_toolchain: rule '//toolchain:linux_x86_64_toolchain_config' does not exist.
在
toolchain/BUILD
文件中,按如下方式定义一个空文件组:package(default_visibility = ["//visibility:public"]) filegroup(name = "linux_x86_64_toolchain_config")
再次运行构建。Bazel 会抛出以下错误:
'//toolchain:linux_x86_64_toolchain_config' does not have mandatory providers: 'CcToolchainConfigInfo'.
CcToolchainConfigInfo
是用于配置 C++ 工具链的提供程序。如需修复此错误,请创建一个包含以下内容的toolchain/cc_toolchain_config.bzl
文件,以创建向 Bazel 提供CcToolchainConfigInfo
的 Starlark 规则:def _impl(ctx): return cc_common.create_cc_toolchain_config_info( ctx = ctx, toolchain_identifier = "k8-toolchain", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", ) cc_toolchain_config = rule( implementation = _impl, attrs = {}, provides = [CcToolchainConfigInfo], )
cc_common.create_cc_toolchain_config_info()
会创建所需的提供程序CcToolchainConfigInfo
。如需使用cc_toolchain_config
规则,请将 load 语句添加到位于 package 语句正下方的toolchain/BUILD
中:load(":cc_toolchain_config.bzl", "cc_toolchain_config")
并将“linux_x86_64_toolchain_config”文件组替换为
cc_toolchain_config
规则的声明:cc_toolchain_config(name = "linux_x86_64_toolchain_config")
再次运行构建。Bazel 会抛出以下错误:
.../BUILD:1:1: C++ compilation of rule '//:hello-world' failed (Exit 1) src/main/tools/linux-sandbox-pid1.cc:421: "execvp(toolchain/DUMMY_GCC_TOOL, 0x11f20e0)": No such file or directory Target //:hello-world failed to build`
此时,Bazel 已掌握了足够的信息来尝试构建代码,但仍不知道使用哪些工具来完成所需的构建操作。您将修改 Starlark 规则实现,以告知 Bazel 使用哪些工具。为此,您需要
@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl
中的 tool_path() 构造函数:# toolchain/cc_toolchain_config.bzl: # NEW load("@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl", "tool_path") def _impl(ctx): tool_paths = [ # NEW tool_path( name = "gcc", path = "/usr/bin/clang", ), tool_path( name = "ld", path = "/usr/bin/ld", ), tool_path( name = "ar", path = "/usr/bin/ar", ), tool_path( name = "cpp", path = "/bin/false", ), tool_path( name = "gcov", path = "/bin/false", ), tool_path( name = "nm", path = "/bin/false", ), tool_path( name = "objdump", path = "/bin/false", ), tool_path( name = "strip", path = "/bin/false", ), ] return cc_common.create_cc_toolchain_config_info( ctx = ctx, toolchain_identifier = "local", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", tool_paths = tool_paths, # NEW )
确保
/usr/bin/clang
和/usr/bin/ld
是您的系统的正确路径。再次运行构建。Bazel 会抛出以下错误:
ERROR: main/BUILD:3:10: Compiling main/hello-world.cc failed: absolute path inclusion(s) found in rule '//main:hello-world': the source file 'main/hello-world.cc' includes the following non-builtin files with absolute paths (if these are builtin files, make sure these paths are in your toolchain): '/usr/include/c++/13/ctime' '/usr/include/x86_64-linux-gnu/c++/13/bits/c++config.h' '/usr/include/x86_64-linux-gnu/c++/13/bits/os_defines.h' ...
Bazel 需要知道在哪里搜索包含的头文件。有多种方法可以解决此问题,例如使用
cc_binary
的includes
属性,但在这里,此方法是在工具链级别使用cc_common.create_cc_toolchain_config_info
的cxx_builtin_include_directories
参数实现的。请注意,如果您使用的是不同版本的clang
,包含路径将有所不同。这些路径也可能因分布情况而异。将
toolchain/cc_toolchain_config.bzl
中的返回值修改为如下所示:return cc_common.create_cc_toolchain_config_info( ctx = ctx, cxx_builtin_include_directories = [ # NEW "/usr/lib/llvm-16/lib/clang/16/include", "/usr/include", ], toolchain_identifier = "local", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", tool_paths = tool_paths, )
再次运行构建命令,您会看到如下错误:
/usr/bin/ld: bazel-out/k8-fastbuild/bin/main/_objs/hello-world/hello-world.o: in function `print_localtime()': hello-world.cc:(.text+0x68): undefined reference to `std::cout'
这是因为链接器缺少 C++ 标准库,而且找不到其符号。解决此问题的方法有很多,例如使用
cc_binary
的linkopts
属性。在此示例中,如果使用工具链的任何目标都不需要指定此标志,则可以解决此问题。将以下代码复制到
toolchain/cc_toolchain_config.bzl
:# NEW load("@bazel_tools//tools/build_defs/cc:action_names.bzl", "ACTION_NAMES") # NEW load( "@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl", "feature", # NEW "flag_group", # NEW "flag_set", # NEW "tool_path", ) all_link_actions = [ # NEW ACTION_NAMES.cpp_link_executable, ACTION_NAMES.cpp_link_dynamic_library, ACTION_NAMES.cpp_link_nodeps_dynamic_library, ] def _impl(ctx): tool_paths = [ tool_path( name = "gcc", path = "/usr/bin/clang", ), tool_path( name = "ld", path = "/usr/bin/ld", ), tool_path( name = "ar", path = "/bin/false", ), tool_path( name = "cpp", path = "/bin/false", ), tool_path( name = "gcov", path = "/bin/false", ), tool_path( name = "nm", path = "/bin/false", ), tool_path( name = "objdump", path = "/bin/false", ), tool_path( name = "strip", path = "/bin/false", ), ] features = [ # NEW feature( name = "default_linker_flags", enabled = True, flag_sets = [ flag_set( actions = all_link_actions, flag_groups = ([ flag_group( flags = [ "-lstdc++", ], ), ]), ), ], ), ] return cc_common.create_cc_toolchain_config_info( ctx = ctx, features = features, # NEW cxx_builtin_include_directories = [ "/usr/lib/llvm-9/lib/clang/9.0.1/include", "/usr/include", ], toolchain_identifier = "local", host_system_name = "local", target_system_name = "local", target_cpu = "k8", target_libc = "unknown", compiler = "clang", abi_version = "unknown", abi_libc_version = "unknown", tool_paths = tool_paths, ) cc_toolchain_config = rule( implementation = _impl, attrs = {}, provides = [CcToolchainConfigInfo], )
运行
bazel build //main:hello-world
,它最终应该为主机成功构建二进制文件。在
toolchain/BUILD
中,复制cc_toolchain_config
、cc_toolchain
和toolchain
目标,并将目标名称中的linux_x86_64
替换为android_x86_64
。在
WORKSPACE
中,注册 Android 的工具链register_toolchains( "//toolchain:cc_toolchain_for_linux_x86_64", "//toolchain:cc_toolchain_for_android_x86_64" )
运行
bazel build //main:hello-world --android_platforms=//toolchain:android_x86_64
以构建适用于 Android 的二进制文件。
实际上,Linux 和 Android 应具有不同的 C++ 工具链配置。您可以针对差异修改现有 cc_toolchain_config
,也可以为不同平台创建单独的规则(即 CcToolchainConfigInfo
提供程序)。
检查您的工作
在本教程中,您学习了如何配置基本的 C++ 工具链,但工具链比这个简单示例更强大。
主要结论:
- 您需要在命令行中指定匹配的
platforms
标志,以便 Bazel 能够针对平台上的相同限制条件值解析到工具链。该文档提供了有关特定语言的配置标志的更多信息。 - 您必须向工具链告知工具所在位置。本教程有一个简化版本,您可以从系统访问这些工具。如果您有兴趣采用更加独立的方法,可以参阅工作区。您的工具可能来自不同的工作区,并且您必须通过目标依赖项(例如
compiler_files
)向cc_toolchain
提供其文件。您还需要更改tool_paths
。 - 您可以创建功能来自定义应将哪些标志传递给不同的操作,无论是链接操作还是任何其他类型的操作。
深入阅读
如需了解详情,请参阅 C++ 工具链配置