📚 课程目录第4章构建系统与自动化编译

4. 构建系统与自动化编译

NVIDIA DRIVE 软件栈规模庞大：感知、融合、规划、控制、中间件、HMI 与底层驱动往往由数十个代码仓库、上千个编译目标组成，且最终要运行在 NVIDIA Orin/Thor 这类 aarch64 平台上。开发机通常是 x86_64，因此“在 x86 上编译出能在 aarch64 上运行的产物”是本节的核心矛盾。围绕这一矛盾，构建系统要同时解决三件事：目标描述与依赖管理（Bazel 或 CMake）、交叉编译工具链配置、以及构建缓存与分布式构建带来的速度提升。

一、Bazel 与 CMake 在 DRIVE 项目中的分工

Bazel 的优势在于“封闭式构建”：每个 target 显式声明 srcs、hdrs、deps、copts，依赖图由 Bazel 自己解析，天然支持增量构建、远程缓存与远程执行。CMake 的优势在于生态兼容：大量第三方库（如 OpenCV、PCL、gRPC）自带 CMake 配置，工具链文件机制成熟。实际 DRIVE 项目中常见两种组织方式：

Bazel 为主：自研模块用 Bazel 管理，第三方库通过 http_archive 或 local_repository 引入，用 cc_library/cc_binary 描述。
CMake 为主 + Bazel 桥接：底层 SDK 与第三方库用 CMake 构建，上层用 Bazel 的 rules_foreign_cc 调用 CMake 生成静态库，再被 Bazel target 依赖。

一个典型的 Bazel 目标写法如下，注意 copts 中显式指定了交叉编译相关宏：

cc_library(
    name = "perception_lib",
    srcs = ["perception.cpp"],
    hdrs = ["perception.h"],
    copts = ["-O2", "-mcpu=ares", "-DDRIVE_TARGET_ORIN"],
    deps = [
        "//middleware:comm",
        "@eigen//:eigen",
    ],
    visibility = ["//visibility:public"],
)

这里 -mcpu=ares 是 Orin 上 ARM Cortex-A78AE 的代号，用于让编译器生成匹配的指令集。若目标平台是 Thor，则应替换为对应 CPU 代号，否则可能因指令不兼容在板端崩溃。

二、交叉编译工具链配置

交叉编译的关键是“让编译器知道自己在为谁编译”。在 Bazel 中通过 --crosstool_top 或平台（platform）机制指定工具链；在 CMake 中通过 CMAKE_TOOLCHAIN_FILE 指定工具链文件。以下是一个面向 aarch64 的 CMake 工具链文件示例：

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(TOOLCHAIN_ROOT /opt/nvidia/drive/toolchains/aarch64)
set(CMAKE_C_COMPILER   ${TOOLCHAIN_ROOT}/bin/aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER ${TOOLCHAIN_ROOT}/bin/aarch64-linux-gnu-g++)

set(CMAKE_FIND_ROOT_PATH ${TOOLCHAIN_ROOT}/sysroot)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O2 -mcpu=ares -fPIC")

配置完成后，用 cmake -DCMAKE_TOOLCHAIN_FILE=... -B build 生成构建目录。判断工具链是否生效，最直接的方法是检查产物架构：

file build/perception_node
# 期望输出：ELF 64-bit LSB executable, ARM aarch64, ...
readelf -h build/perception_node | grep Machine
# 期望输出：Machine: AArch64

若输出仍是 x86-64，说明工具链文件未被加载，或 CMake 缓存中残留了旧的编译器路径，需要删除 build/CMakeCache.txt 后重新生成。

三、构建缓存与分布式构建优化

DRIVE 项目全量构建动辄数小时，缓存与分布式是必选项。Bazel 提供两级缓存：本地磁盘缓存与远程缓存（Remote Cache）。远程缓存通常基于 gRPC 协议，可对接自建服务或云服务。启用方式：

bazel build //perception:perception_node \
  --remote_cache=grpc://build-cache.internal:9092 \
  --remote_timeout=60 \
  --disk_cache=/mnt/ssd/bazel_disk_cache

缓存命中的判断依据是 action 的输入哈希（源文件、编译选项、工具链版本、环境变量等）。因此，工具链版本一旦变化，缓存会整体失效。实践中应把工具链版本号写入 CI 变量，并在缓存 key 中体现，避免“用了旧缓存导致产物与工具链不匹配”的隐蔽问题。

分布式构建（Remote Execution）进一步把编译动作分发到多台 worker。Bazel 通过 --remote_executor 指定执行服务，配合 --jobs 控制并发度。经验上，8～16 台 worker 可将全量构建从数小时压缩到十几分钟，但前提是缓存命中率足够高，否则网络传输会成为新瓶颈。

缓存与分布式构建的收益高度依赖“可复现性”。若构建过程中混入了时间戳、随机数、绝对路径等不稳定输入，缓存命中率会骤降。建议在 CI 中开启 --experimental_reproducible 或等价选项，并定期用 bazel build --nobuild 检查依赖图是否稳定。

四、构建流程与缓存/分布式协同关系

下图把“源码与依赖 → 工具链 → 构建动作 → 缓存/分布式 → 产物与验证”这条链路画在一起，重点表现缓存命中与未命中时的不同路径，以及交叉编译产物必须经过架构校验才能进入部署环节。

五、实践中的常见问题与判断依据

交叉编译与缓存组合使用时，最容易踩的坑有三类。第一类是工具链路径混用：CMake 缓存中残留了上一次的编译器路径，导致部分目标仍用 x86 编译。判断方法是查看 CMakeCache.txt 中的 CMAKE_CXX_COMPILER 是否指向 aarch64 工具链。第二类是缓存污染：不同工具链版本共用同一缓存 key，取回了不匹配的产物。判断方法是比对产物 readelf -h 的 Machine 字段与预期是否一致。第三类是分布式执行环境不一致：worker 上缺少 sysroot 或头文件，导致编译失败。判断方法是查看 Bazel 的 action 日志，确认失败发生在“找不到头文件”还是“指令不兼容”。

不要把“构建成功”等同于“产物可用”。交叉编译场景下，构建成功只说明语法与链接通过，产物是否能在 Orin/Thor 上运行，必须经过架构校验与板端冒烟测试。建议在 CI 中把 readelf -h 校验作为构建后的强制门禁。

综合来看，DRIVE 软件的构建体系可以概括为：用 Bazel/CMake 描述目标与依赖，用工具链文件锁定 aarch64 编译环境，用远程缓存与分布式执行压缩构建时间，最后用架构校验与板端测试守住产物质量。这四者缺一不可，任何一环配置不当，都会让“构建快”变成“构建快但不可用”。