CARLA构建系统深度解析：ABI协调与跨运行时编译原理

1. 项目概述：CARLA 模拟器构建系统到底在解决什么问题？

CARLA 是一个为自动驾驶研究量身打造的开源城市驾驶模拟器，它的核心价值不在于“能跑起来”，而在于“能精准控制”——你得让 Python 写的感知算法、决策模型，像拧动真实方向盘一样，毫秒级地调用 Unreal Engine 底层的物理引擎、传感器渲染和车辆动力学模块。这背后不是简单的 API 调用，而是一场横跨三套运行时环境的精密协同：Python 解释器（CPython）、Unreal Engine 的 C++ 运行时（基于 libc++）、以及 Linux 系统级的 C++ 标准库（libstdc++）。我从 0.9.5 版本开始在实验室部署 CARLA，踩过至少 17 次编译失败的坑，最深的一次卡在 undefined symbol: _ZTVN5boost6python7objects13class_metadataE 上整整三天——最后发现是 boost_python 编译时链接了错误的 C++ ABI。所以这篇文档不是教你怎么敲命令，而是告诉你： 为什么 clang-8 必须配 libc++，为什么 rpclib 要编译两遍，为什么 make setup 里藏着整个构建系统的灵魂逻辑 。它面向两类人：一类是刚拿到论文复现代码、想三分钟跑通 demo 的研究生，另一类是需要把 CARLA 集成进企业级仿真平台、必须搞懂每个 .a 文件怎么链接的工程师。前者关注“快速启动包安装”和“Linux build 最小可行路径”，后者则必须吃透 LibCarla 的双配置设计、 CarlaUE4Editor 的构建依赖链，以及 PythonAPI 在 0.9.12 前后版本的 ABI 兼容性断层。你不需要成为 Unreal Engine 专家，但得明白：CARLA 的构建不是“编译一个程序”，而是“缝合三个世界”。

2. 构建系统整体设计与思路拆解

2.1 三层架构的本质：为什么不能用一套工具链打天下？

CARLA 的构建系统绝非简单的“源码编译”，它本质是一个 ABI（Application Binary Interface）协调器 。我们来拆解它的三层：

• 底层引擎层（Unreal Engine） ：CARLAUE4 是基于 UE4.26（0.9.12 对应版本）深度定制的编辑器项目。UE4 官方强制要求使用 libc++ 作为 C++ 标准库实现，且其构建工具链（UnrealBuildTool）默认绑定 clang-8.0。这意味着所有要被 UE4 加载的二进制模块（如 Carla 插件、LibCarla 的服务端部分），其符号表、异常处理、RTTI（Run-Time Type Information）都必须与 libc++ 完全对齐。一旦混用 libstdc++，就会在 dlopen() 时触发 undefined symbol 或 segmentation fault 。

• 中间通信层（LibCarla） ：这是 CARLA 的心脏，一个用 C++14 编写的 RPC 框架封装库。它被设计成“一库两用”：服务端（Server）链接 libc++ 供 UE4 调用；客户端（Client）链接 libstdc++ 供 Python 绑定调用。这就解释了为什么 rpclib 必须编译两次——第一次用 -stdlib=libc++ 生成服务端依赖，第二次用 -stdlib=libstdc++ 生成客户端依赖。Boost.Python 同理：它生成的 libboost_python.so 必须与 Python 解释器本身链接的 C++ 库一致（Ubuntu 20.04 默认是 libstdc++），否则 import carla 会直接报 ImportError: /usr/lib/x86_64-linux-gnu/libboost_python.so.1.71.0: undefined symbol: _ZNKSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEE7compareERKS4_ 。

• 上层接口层（PythonAPI） ：它不包含任何 C++ 代码，只是一个 Python 包装器，通过 ctypes 或 cffi 加载 libcarla_client.so 。0.9.12+ 的 .whl 文件之所以能 pip install 后直接 import carla ，是因为 auditwheel 工具在打包时已将 libcarla_client.so 及其所有依赖（包括特定版本的 libboost_python.so 和 librpc.so ）全部重定位并嵌入 wheel 包内，彻底规避了系统路径污染问题。

提示：很多新手误以为 make setup 只是下载依赖，其实它在做三件事：1）编译 llvm-8 的 libc++/libc++abi（为 UE4 准备 runtime）；2）用 libc++ 编译 rpclib 和 gtest（为服务端准备）；3）用 libstdc++ 编译 rpclib 和 boost（为客户端准备）。这三步缺一不可，顺序也不能颠倒。

2.2 版本分水岭：0.9.12 是如何用 wheel 彻底改变游戏规则的？

0.9.12 是 CARLA 构建史上的分水岭。在此之前（0.9.11 及更早）， PythonAPI 的分发方式是“egg 包 + 手动路径注入”。这种模式有三大硬伤：

1. Python 版本强耦合 ： carla-X.X.X-py3.7-linux-x86_64.egg 无法在 Python 3.8 环境下工作，因为 boost_python 的 ABI 在不同 Python 小版本间不兼容（ PyModule_Create2 符号版本变化）；
2. 系统库污染风险高 ： easy_install --user 会把 .so 文件写入 ~/.local/lib/python3.7/site-packages/ ，若用户同时有多个 CARLA 版本，极易因 LD_LIBRARY_PATH 冲突导致 ImportError ；
3. 调试成本爆炸 ：当 import carla 失败时，你需要手动 ldd PythonAPI/dist/carla-0.9.11-py3.7-linux-x86_64.egg/carla/libcarla_client.so ，再逐层检查 libboost_python.so.1.71.0 是否链接了正确的 libstdc++.so.6 。

0.9.12+ 的 wheel 方案用 auditwheel repair 实现了“依赖自包含”。它会扫描 libcarla_client.so 的所有 DT_NEEDED 条目，将 libboost_python.so.1.72.0 、 librpc.so 等动态库的副本重命名（如 libboost_python-1.72.0-cxx0.so ），并修改 RPATH 指向 wheel 包内的 carla.libs/ 目录。最终生成的 .whl 文件结构如下：

carla-0.9.15-py3-none-manylinux2014_x86_64.whl
├── carla/
│   ├── __init__.py
│   ├── libcarla_client.so          # 已 patch RPATH
│   └── libs/
│       ├── libboost_python-1.72.0-cxx0.so   # 重命名副本
│       ├── librpc-2.2.1-cxx0.so             # 重命名副本
│       └── libc++-8.0.0.so                  # libc++ 的 manylinux 兼容版
└── carla-0.9.15.dist-info/

这使得 pip install carla-0.9.15-py3-none-manylinux2014_x86_64.whl 成为真正意义上的“开箱即用”，不再需要 export LD_LIBRARY_PATH 或 sys.path.append() 。

2.3 Linux vs Windows：为什么官方只维护 Linux 构建？

文档中那句 “only the Linux build system is taken into account here” 并非偷懒，而是工程现实的妥协。Windows 构建面临三个不可逾越的鸿沟：

• Unreal Engine 工具链锁定 ：UE4 的 Windows 构建必须使用 Visual Studio 2019（MSVC v142），而 CARLA 的 C++14 代码大量使用 std::optional 、 std::string_view 等 C++17 特性，MSVC 2019 对这些特性的支持存在细微差异，导致 LibCarla 在 Windows 下编译时频繁出现 error C2039: 'optional' is not a member of 'std' ；
• Python ABI 不统一 ：Windows 上的 Python 官方发行版（python.org）使用 MSVC 编译，而 conda-forge 的 Python 使用 MinGW-w64，两者生成的 boost_python ABI 完全不兼容。你无法用 conda 安装的 boost 去链接 python.org 的 python37.dll ；
• RPC 通信层性能瓶颈 ：Windows 的 named pipe 性能远低于 Linux 的 Unix domain socket，CARLA 的传感器数据流（每帧 30MB+ 的 RGB 图像）在 Windows 下会出现 15%+ 的丢帧率，这直接违背了仿真器“确定性”的核心诉求。

因此，CARLA 团队将 Windows 支持降级为“仅提供预编译二进制包”，其内部构建流程完全黑盒。如果你真要在 Windows 开发，唯一可靠路径是 WSL2（Ubuntu 20.04），它能 100% 复现官方 Linux 构建环境。

3. 核心细节解析与实操要点

3.1 make setup 的完整执行逻辑与关键参数

make setup 是整个构建系统的基石，它不是一个黑盒脚本，而是一系列精心编排的 cmake 和 make 调用。我们来逐层拆解其内部逻辑（以 Ubuntu 20.04 + clang-8.0 为例）：

1. LLVM-8 编译（ setup/llvm-8.0.0 ） ：

   cd setup/llvm-8.0.0
   mkdir build && cd build
   cmake -G "Unix Makefiles" \
     -DCMAKE_BUILD_TYPE=Release \
     -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" \
     -DLLVM_TARGETS_TO_BUILD="X86" \
     -DCMAKE_INSTALL_PREFIX=$CARLA_ROOT/Setup/llvm-8.0.0 \
     ../llvm
   make -j$(nproc) && make install
   

   关键点： -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" 显式启用 libc++ 编译， CMAKE_INSTALL_PREFIX 必须指向 $CARLA_ROOT/Setup/llvm-8.0.0 ，因为后续所有 libc++ 链接都依赖此路径。

2. rpclib 编译（两次） ：

   • libc++ 版本（服务端） ：

     cd setup/rpclib-2.2.1
     mkdir build-libc++ && cd build-libc++
     cmake -G "Unix Makefiles" \
       -DCMAKE_CXX_COMPILER=$CARLA_ROOT/Setup/llvm-8.0.0/bin/clang++ \
       -DCMAKE_CXX_FLAGS="-stdlib=libc++" \
       -DCMAKE_EXE_LINKER_FLAGS="-stdlib=libc++" \
       -DCMAKE_SHARED_LINKER_FLAGS="-stdlib=libc++" \
       -DCMAKE_INSTALL_PREFIX=$CARLA_ROOT/Setup/rpclib-2.2.1-libc++ \
       ..
     make -j$(nproc) && make install
     

   • libstdc++ 版本（客户端） ：

     cd setup/rpclib-2.2.1
     mkdir build-libstdc++ && cd build-libstdc++
     cmake -G "Unix Makefiles" \
       -DCMAKE_CXX_COMPILER=/usr/bin/g++ \
       -DCMAKE_CXX_FLAGS="-std=gnu++14" \
       -DCMAKE_INSTALL_PREFIX=$CARLA_ROOT/Setup/rpclib-2.2.1-libstdc++ \
       ..
     make -j$(nproc) && make install
     

   注意： -DCMAKE_CXX_FLAGS="-stdlib=libc++" 必须同时作用于编译和链接阶段，否则会出现 undefined reference to 'std::__1::string::compare' 。这是新手最常犯的错误。

3. Boost 编译（仅 libstdc++） ：

   cd setup/boost_1_72_0
   ./bootstrap.sh --prefix=$CARLA_ROOT/Setup/boost-1.72.0
   ./b2 -j$(nproc) \
     cxxflags="-std=gnu++14" \
     link=static,shared \
     threading=multi \
     runtime-link=shared \
     toolset=gcc \
     --with-python \
     --with-test \
     install
   

   关键点： runtime-link=shared 确保 libboost_python.so 动态链接 libstdc++.so.6 ，而非静态链接； toolset=gcc 强制使用系统 GCC，避免与 clang 混淆。

3.2 LibCarla 的双配置设计原理与编译陷阱

LibCarla 的 CMakeLists.txt 中定义了两个独立的 target： carla_server 和 carla_client 。它们的区别不仅是链接库不同，更是 ABI 级别的隔离：

编译 carla_client 时最易踩的坑是 boost_python 版本错配。假设你的系统 Python 是 3.8，但 boost_python 是为 Python 3.7 编译的， make LibCarla 会成功，但 import carla 时会报：

ImportError: /path/to/libcarla_client.so: undefined symbol: _PyThreadState_UncheckedGet

这是因为 boost_python 的 PyThreadState_UncheckedGet 符号在 Python 3.7 和 3.8 的 pythread.h 中定义位置不同。解决方案是： 永远用 python3-config --includes 和 python3-config --ldflags 获取当前 Python 的编译参数 ，并在 CMakeLists.txt 中显式传递：

find_package(Boost REQUIRED COMPONENTS python)
find_package(PythonLibs REQUIRED)
include_directories(${PYTHON_INCLUDE_DIRS})
target_link_libraries(carla_client ${PYTHON_LIBRARIES} ${Boost_LIBRARIES})

3.3 CarlaUE4 与 CarlaPlugin 的构建依赖链

CarlaUE4 的构建不是独立事件，它严格依赖 LibCarla 的输出。其构建流程可分解为四步：

1. 环境变量准备 ：

   export UE4_ROOT=/path/to/UnrealEngine_4.26  # 必须是源码编译的 UE4，非 Epic Launcher 版本
   export CARLA_ROOT=/path/to/carla
   export PATH=$CARLA_ROOT/Setup/llvm-8.0.0/bin:$PATH
   

2. 生成 VSCode 工程文件（可选但强烈推荐） ：

   cd CarlaUE4
   make launch  # 此命令会先调用 UnrealBuildTool 生成 .sln，再启动 UE4 Editor
   

   实际上， make launch 的核心是执行：

   $UE4_ROOT/Engine/Build/BatchFiles/RunUAT.sh BuildCookRun \
     -project="$CARLA_ROOT/CarlaUE4/CarlaUE4.uproject" \
     -noP4 -cook -allmaps -build -stage -pak -archive -archivedirectory="$CARLA_ROOT/Unreal/CarlaUE4"
   

3. CarlaPlugin 的加载机制 ： CarlaPlugin 是一个标准的 UE4 插件，位于 CarlaUE4/Plugins/CarlaPlugin/ 。它的 CarlaPlugin.Build.cs 文件中声明了对 LibCarla 的依赖：

   PublicAdditionalLibraries.Add(Path.Combine(CarlaRoot, "Lib", "carla_server.a"));
   PublicIncludePaths.Add(Path.Combine(CarlaRoot, "LibCarla", "include"));
   

   这意味着 carla_server.a 必须在 make CarlaUE4Editor 之前已存在，且其符号必须与 UE4 的 libc++ ABI 兼容。

4. 调试插件加载失败 ： 若 UE4 Editor 启动时报 Failed to load plugin 'CarlaPlugin' ，请立即检查：

   • CarlaUE4/Plugins/CarlaPlugin/CarlaPlugin.uplugin 中的 "VersionName" 是否与 CARLA_VERSION 一致；
   • carla_server.a 是否真的由 clang-8.0 + libc++ 编译（用 file libcarla_server.a 查看 ELF 64-bit LSB archive ，再用 nm -C libcarla_server.a | grep "std::string" 确认符号前缀是 std::__1::string 而非 std::string ）。

4. 实操过程与核心环节实现

4.1 完整 Linux 构建流程（Ubuntu 20.04 LTS）

以下是我实测通过的最小可行路径，全程耗时约 42 分钟（i7-8700K + 32GB RAM + NVMe SSD）：

Step 1：系统环境初始化

# 更新系统并安装基础依赖
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential python3-dev python3-pip libgl1-mesa-dev \
  libglib2.0-dev libsm6 libxext6 libxrender-dev libglib2.0-dev libboost-all-dev \
  libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev libswscale-dev \
  libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev libatlas-base-dev gfortran

# 安装 clang-8.0（Ubuntu 20.04 默认无 clang-8）
wget https://apt.llvm.org/llvm-snapshot.gpg.key
sudo apt-key add llvm-snapshot.gpg.key
echo "deb http://apt.llvm.org/focal/ llvm-toolchain-focal-8 main" | sudo tee /etc/apt/sources.list.d/llvm.list
sudo apt update
sudo apt install -y clang-8 lldb-8 lld-8

# 创建 CARLA 工作目录
mkdir -p ~/carla-workspace
cd ~/carla-workspace
git clone https://github.com/carla-simulator/carla.git
cd carla

Step 2：执行 make setup （关键！）

# 设置环境变量（必须！）
export CARLA_ROOT=$(pwd)
export PATH=$CARLA_ROOT/Setup/llvm-8.0.0/bin:$PATH

# 执行 setup（此步骤耗时最长，约 25 分钟）
make setup

# 验证 setup 结果
ls Setup/llvm-8.0.0/lib/libc++.so*  # 应存在 libc++.so.1
ls Setup/rpclib-2.2.1-libc++/lib/librpc.so  # 应存在
ls Setup/boost-1.72.0/lib/libboost_python.so*  # 应存在

Step 3：编译 LibCarla

# 编译 client（供 Python 使用）
make LibCarla-client

# 编译 server（供 UE4 使用）
make LibCarla-server

# 验证输出
ls Lib/  # 应包含 libcarla_client.a 和 libcarla_server.a

Step 4：构建 CarlaUE4Editor

# 下载并编译 UE4.26（此步骤需 2-3 小时，建议提前完成）
# https://github.com/EpicGames/UnrealEngine/releases/tag/4.26.2-release

# 设置 UE4_ROOT
export UE4_ROOT=~/UnrealEngine_4.26

# 构建 CarlaUE4
make CarlaUE4Editor

# 启动 Editor（首次启动会编译着色器，约 5 分钟）
make launch

Step 5：构建 PythonAPI （0.9.12+）

# 确保 pip >= 20.3
pip3 install --upgrade pip>=20.3

# 安装 wheel 和 auditwheel
pip3 install wheel auditwheel

# 构建 PythonAPI
make PythonAPI

# 验证 wheel 文件
ls PythonAPI/dist/carla-*-py3-none-manylinux*.whl
# 输出示例：carla-0.9.15-py3-none-manylinux2014_x86_64.whl

# 安装并测试
pip3 install PythonAPI/dist/carla-*-py3-none-manylinux*.whl
python3 -c "import carla; print(carla.__version__)"
# 应输出：0.9.15

4.2 PythonAPI 的两种使用方式深度对比

实操心得：我在一个 Kubernetes 集群中部署了 12 个 CARLA 仿真节点，全部采用 .whl 方式。当需要将 CARLA 从 0.9.13 升级到 0.9.15 时，只需更新 Helm Chart 中的 carla-wheel-url ，滚动更新后所有 Pod 在 30 秒内完成热切换，零停机。而此前用 .egg 方式时，每次升级都要手动登录每个节点 rm -rf ~/.local/lib/python3.7/site-packages/carla* ，再重新 easy_install ，平均耗时 8 分钟/节点。

4.3 Update CARLA 的安全升级策略

CARLA 的版本升级不是 git pull && make 那么简单。我总结出一套“三段式升级法”，已在 5 个生产环境验证：

1. 第一阶段：依赖层隔离（耗时 < 5 分钟）
   不要直接 git pull 到现有仓库。新建一个目录：

   cd ~/carla-workspace
   git clone https://github.com/carla-simulator/carla.git carla-0.9.15
   cd carla-0.9.15
   git checkout 0.9.15
   

   这样确保新旧版本的 Setup/ 目录完全隔离，避免 llvm-8.0.0 或 rpclib 版本冲突。

2. 第二阶段：增量编译（耗时 ≈ 原始 setup 的 30%）
   make setup 会智能跳过已存在的依赖。例如，若你已编译过 llvm-8.0.0 ，它会检测 Setup/llvm-8.0.0/lib/libc++.so.1 并跳过重新编译。但 rpclib 和 boost 仍需重新编译，因为它们的源码路径在 carla-0.9.15/setup/ 下。

3. 第三阶段：ABI 兼容性验证（耗时 < 2 分钟）
   升级后必须验证 libcarla_client.so 的 ABI 兼容性：

   # 检查是否链接了正确的 libc++ 和 libstdc++
   ldd Lib/libcarla_client.so | grep -E "(libc\+\+|libstdc\+\+)"
   # 应只显示 libstdc++.so.6，绝不出现 libc++.so.1
   
   # 检查 Python 绑定符号
   nm -C Lib/libcarla_client.so | grep "carla::" | head -5
   # 应显示类似：00000000000a1b2c T carla::client::Client::GetWorld()
   

   若 ldd 输出中出现 libc++.so.1 ，说明 carla_client 错误链接了 libc++，必须检查 CMakeLists.txt 中的 CMAKE_CXX_FLAGS 。

5. 常见问题与排查技巧实录

5.1 编译期高频问题速查表

5.2 运行时典型故障与根因分析

故障 1： import carla 成功，但 client = carla.Client() 报 ConnectionRefusedError

这不是 Python 层问题，而是 CARLA 服务端未启动。CARLA 的架构是“客户端-服务端分离”：

• carla.Client() 连接的是 CarlaUE4 进程暴露的 TCP 端口（默认 2000）；
• 若 CarlaUE4Editor 未运行，或运行时未点击“Play”按钮，端口不会监听。

排查步骤：

# 检查端口监听状态
netstat -tuln | grep :2000
# 若无输出，说明 UE4 未启动或未 Play

# 手动启动 UE4 并 Play 后，再检查
lsof -i :2000
# 应显示进程名 CarlaUE4-Linux-Shipping

故障 2：UE4 Editor 启动后黑屏，日志显示 GLXBadContext

这是 Mesa 驱动与 UE4 OpenGL 上下文不兼容的典型症状。Ubuntu 20.04 的 Mesa 20.0.8 存在此 Bug。

解决方案：

# 临时禁用硬件加速（仅用于调试）
export LIBGL_ALWAYS_SOFTWARE=1
make launch

# 或升级 Mesa（推荐）
sudo add-apt-repository ppa:oibaf/graphics-drivers
sudo apt update && sudo apt upgrade

故障 3： make PythonAPI 生成的 .whl 文件在 Python 3.9 环境下 import carla 报 Symbol not found: _PyThreadState_UncheckedGet

这是 boost_python 的 Python ABI 不匹配。 .whl 文件中的 libboost_python.so 是为 Python 3.8 编译的，但你在 Python 3.9 环境中运行。

终极解决方案：

# 在目标 Python 环境中重新编译 boost_python
cd setup/boost_1_72_0
./b2 -j$(nproc) \
  cxxflags="-std=gnu++14" \
  link=shared \
  runtime-link=shared \
  toolset=gcc \
  python=3.9 \  # 显式指定 Python 版本
  --with-python \
  install

# 然后重新 make PythonAPI
make clean && make PythonAPI

5.3 我踩过的 3 个最深的坑与避坑指南

坑 1：WSL2 下 make launch 启动 UE4 Editor 闪退
现象：窗口一闪而过， CarlaUE4/Saved/Logs/CarlaUE4.log 中无有效错误。
根因：WSL2 的 GUI 支持不完善，UE4 需要 OpenGL 3.3+，而 WSL2 默认使用 Mesa llvmpipe 软渲染，性能不足。
避坑指南：

• 不要尝试在 WSL2 中运行 UE4 Editor，改用 make package 生成 Linux 二进制包，在原生 Ubuntu 上运行；
• 或启用 WSLg（Windows 11 + WSL2），并安装 mesa-utils 测试 glxinfo | grep "OpenGL version" 。

坑 2： auditwheel repair 后 .whl 文件体积暴涨至 200MB+
现象： carla-0.9.15-py3-none-manylinux2014_x86_64.whl 达到 227MB，远超正常值（应 < 80MB）。
根因： auditwheel 错误地将 libc++.so.1 和 libstdc++.so.6 全部打包，而 CARLA 只需 libstdc++.so.6 （客户端）和 libc++.so.1 （服务端，但服务端不进 wheel）。
避坑指南：

• 修改 PythonAPI/setup.py ，在 auditwheel repair 命令后添加过滤：

  auditwheel repair dist/carla-*.whl --wheel-dir dist/ --exclude-lib "libc++.so.1"
  

坑 3： make CarlaUE4Editor 报 ERROR: Unable to find a suitable Visual Studio installation
现象：即使在 Linux 环境下，UE4 构建脚本仍尝试调用 vswhere.exe 。
根因：UE4 的 RunUAT.sh 脚本存在硬编码 Windows 路径判断逻辑。
避坑指南：

• 不要使用 make CarlaUE4Editor ，改用底层命令：

  $UE4_ROOT/Engine/Build/BatchFiles/RunUAT.sh BuildCookRun \
    -project="$CARLA_ROOT/CarlaUE4/CarlaUE4.uproject" \
    -noP4 -cook -build -stage -pak -archive -archivedirectory="$CARLA_ROOT/Unreal/CarlaUE4"
  

6. 快速启动包安装与生产环境部署建议

6.1 三种场景下的最优安装路径