📚 课程目录第3章开发环境搭建

3. 开发环境搭建

AutowareAuto作为面向L4级自动驾驶的完整开源软件栈，其开发环境的搭建质量直接决定了后续功能开发、算法验证与系统集成的效率。本章将围绕Ubuntu系统基础配置、ROS2（Robot Operating System 2）安装、AutowareAuto源码编译、依赖管理以及Docker容器化使用五个核心环节展开，帮助开发者构建一套稳定、可复现且高效的自动驾驶软件开发底座。我们将从底层系统配置出发，逐步深入到源码级编译与容器化部署，确保每一步操作都有明确的理论依据和可验证的实践路径。

上图展示了从Ubuntu系统到AutowareAuto源码编译再到Docker容器化部署的完整工程链路。整个环境搭建遵循“分层构建、逐层验证”的原则：系统层提供硬件抽象与基础运行库，ROS2层提供通信与工具链，AutowareAuto源码层实现自动驾驶核心算法，而Docker则负责将前三者封装为可移植、可复现的运行时环境。下面我们将按照这一链路逐步深入。

3.1 Ubuntu系统配置：从裸机到可用的开发底座

3.1.1 核心原理：为什么选择Ubuntu 20.04 LTS

AutowareAuto官方长期支持版本基于Ubuntu 20.04 LTS（Focal Fossa）构建，这并非随意选择。ROS2 Foxy Fitzroy（AutowareAuto所依赖的ROS2发行版）与Ubuntu 20.04的APT源、内核模块、NVIDIA驱动生态具有最佳兼容性。LTS版本提供长达5年的安全更新，确保自动驾驶开发这种长周期项目不会因系统停止维护而被迫迁移。此外，Ubuntu 20.04的Linux内核5.4对实时性补丁（PREEMPT_RT）的支持较为成熟，这对于后续可能涉及的实时控制模块至关重要。

3.1.2 操作流程：系统安装与基础配置清单

系统安装完成后，需要执行以下关键配置步骤，每一步都直接影响后续工具链的稳定性：

更新软件源与系统包：使用国内镜像源（如清华、阿里云）替换默认源，然后执行 sudo apt update && sudo apt upgrade -y，确保系统处于最新状态。
安装基础开发工具：sudo apt install -y build-essential cmake git python3-pip python3-venv curl wget，这些是编译AutowareAuto及其依赖所必需的工具链。
NVIDIA驱动与CUDA安装（可选但强烈推荐）：如果开发机配备NVIDIA GPU（用于感知模块加速），需安装与Ubuntu 20.04匹配的驱动（建议470+版本）以及CUDA 11.4+。安装后通过 nvidia-smi 验证驱动状态。
设置用户权限与目录结构：创建 ~/autoware 作为工作根目录，并赋予当前用户完全读写权限，避免后续编译时因权限问题中断。

经验提醒：在虚拟机中开发时，务必启用3D加速并分配至少8GB内存和4核CPU。AutowareAuto编译时内存峰值可达6GB以上，内存不足会导致编译进程被OOM Killer终止，且错误信息不直观，排查困难。

3.1.3 案例拆解：解决NVIDIA驱动与内核版本冲突

某开发者在Ubuntu 20.04上安装NVIDIA驱动470.86后，重启进入系统时出现黑屏，仅能通过恢复模式进入。分析过程：查看 /var/log/Xorg.0.log 发现驱动加载失败，错误指向内核模块版本不匹配。进一步执行 dkms status 发现驱动模块未注册到当前内核5.4.0-42-generic。解决方案：重新安装 linux-headers-$(uname -r)，然后执行 sudo dkms install -m nvidia -v 470.86，最后更新initramfs并重启。此案例说明，驱动安装前必须确认内核头文件完整，且驱动版本与内核版本需严格对应。

3.1.4 常见误区与总结

误区一：跳过系统更新直接安装ROS2。旧版系统库可能导致ROS2依赖冲突，且无法通过 rosdep 解析。
误区二：使用root用户进行日常开发。AutowareAuto的colcon构建系统对非root用户更友好，且root环境下环境变量管理混乱。
误区三：忽略Swap空间配置。建议设置至少8GB的Swap，防止编译过程中内存溢出。

系统配置的最终验证标准是：gcc --version、cmake --version、nvidia-smi 均能正常输出，且 sudo apt update 无报错。

3.2 ROS2 Foxy安装：通信中间件与工具链

3.2.1 核心原理：ROS2的组件架构

ROS2 Foxy采用DDS（Data Distribution Service）作为底层通信中间件，默认实现为Eclipse Cyclone DDS或Fast RTPS。与ROS1不同，ROS2去除了中心化的Master节点，节点间通过DDS的发现协议（SPDP）自动建立连接，这为自动驾驶多传感器数据的高频、低延迟传输提供了保障。AutowareAuto依赖ROS2的 rclcpp、rclpy 客户端库以及 tf2、nav_msgs 等核心包。

3.2.2 操作流程：APT源安装与验证

推荐使用APT源安装ROS2 Foxy，避免源码编译ROS2带来的时间开销。具体步骤如下：

# 1. 设置ROS2软件源
sudo apt update && sudo apt install -y curl gnupg2 lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list

# 2. 安装ROS2 Foxy桌面版（包含可视化工具）
sudo apt update && sudo apt install -y ros-foxy-desktop python3-argcomplete

# 3. 安装构建工具与版本管理工具
sudo apt install -y python3-colcon-common-extensions python3-vcstool

# 4. 配置环境变量
echo "source /opt/ros/foxy/setup.bash" >> ~/.bashrc
source ~/.bashrc

验证安装：运行 ros2 run demo_nodes_cpp talker 和 ros2 run demo_nodes_py listener，在另一个终端中应能看到消息收发。同时执行 ros2 topic list 应显示 /chatter 话题。

3.2.3 案例拆解：ROS2多机通信的DDS配置

在自动驾驶实车测试中，通常需要将感知计算单元（工控机）与车辆控制单元（MCU）通过以太网连接。某团队在配置ROS2多机通信时，发现两台机器无法互相发现节点。分析过程：检查 ros2 doctor 输出，发现DDS默认使用组播地址，而车辆以太网交换机禁用了组播。解决方案：在 /etc/profile.d/ros2_env.sh 中设置 export ROS_DOMAIN_ID=42 和 export ROS_AUTOMATIC_DISCOVERY_RANGE=SUBNET，并配置Fast DDS的XML文件指定单播地址。此案例表明，ROS2的DDS配置在复杂网络环境中需要显式指定通信策略。

3.2.4 常见误区与总结

误区一：安装ROS2基础版而非桌面版。基础版缺少 rviz2、gazebo 等调试工具，后续可视化验证会受阻。
误区二：忘记安装 python3-argcomplete。这会导致ROS2命令行自动补全失效，降低开发效率。
误区三：环境变量重复source。在 .bashrc 中重复添加source行会导致环境变量重复，可能引发未定义行为。

ROS2安装成功的标志是：ros2 --help 正常输出，且 ros2 pkg list 能列出超过200个包。

3.3 AutowareAuto源码编译：从仓库到可执行二进制

3.3.1 核心原理：基于colcon的构建系统

AutowareAuto采用colcon作为构建工具，它是对catkin的扩展，支持CMake、Python、ament等混合语言包。源码编译的核心在于依赖解析与构建顺序管理。AutowareAuto的 autoware-auto.repos 文件定义了所有依赖仓库的版本（通过git commit hash锁定），使用 vcs import 拉取后，colcon会根据包间的 package.xml 依赖关系自动确定构建顺序。

3.3.2 操作流程：源码获取与编译

# 1. 创建工作空间并拉取源码
mkdir -p ~/autoware/autoware-auto/src
cd ~/autoware/autoware-auto
wget https://raw.githubusercontent.com/autowarefoundation/autoware-auto/main/autoware-auto.repos
vcs import src < autoware-auto.repos

# 2. 安装系统依赖（rosdep）
sudo apt update
rosdep update
rosdep install -y --from-paths src --ignore-src --rosdistro foxy

# 3. 编译（使用Release模式，开启多核）
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release --parallel-workers 4

# 4. 设置环境变量
echo "source ~/autoware/autoware-auto/install/setup.bash" >> ~/.bashrc

编译过程通常需要30-60分钟（取决于CPU性能）。编译完成后，install 目录下会生成所有可执行文件与库文件。

3.3.3 案例拆解：编译失败与依赖冲突排查

某开发者在编译 autoware_auto_perception 包时，遇到 Could not find a package configuration file provided by "autoware_auto_common" 错误。分析过程：该错误表明依赖包未先编译或未正确安装。执行 colcon list 检查包列表，发现 autoware_auto_common 确实存在但未编译。进一步查看 log/latest_build/autoware_auto_common/stdout_stderr.log，发现其编译失败原因是缺少 Eigen3 开发库。解决方案：sudo apt install -y libeigen3-dev，然后重新执行 colcon build --packages-select autoware_auto_common，成功后再编译整个工作空间。此案例说明，colcon的依赖解析是递归的，底层包失败会阻断上层包。

3.3.4 常见误区与总结

误区一：使用 --symlink-install 参数。虽然该参数能加速开发迭代，但AutowareAuto部分包不支持符号链接安装，会导致运行时找不到资源文件。
误区二：忽略编译日志。colcon的日志位于 log/ 目录，是排查编译错误的唯一可靠来源。
误区三：修改源码后不重新编译。AutowareAuto的C++包必须重新编译才能生效，Python包则可通过 --symlink-install 实现热更新。

编译成功的验证方式：ros2 pkg list | grep autoware 应输出所有AutowareAuto包，且 ros2 launch autoware_auto_launch autoware_auto.launch.py 能正常启动（需配合仿真环境）。

3.4 依赖管理与Docker使用：环境复现与隔离

3.4.1 核心原理：依赖管理的层次化策略

AutowareAuto的依赖管理分为三个层次：系统级依赖（通过 rosdep 解析，如 libeigen3-dev）、ROS2包依赖（通过 package.xml 声明，如 rclcpp）、源码级依赖（通过 .repos 文件锁定版本）。Docker在此基础上增加第四层——镜像层，将前三层封装为不可变的镜像层，实现“一次构建，处处运行”。

3.4.2 操作流程：Docker镜像构建与容器运行

AutowareAuto官方提供Dockerfile，推荐使用 ghcr.io/autowarefoundation/autoware-auto:latest 镜像。自定义构建流程如下：

# 1. 拉取基础镜像（包含Ubuntu 20.04 + ROS2 Foxy + 依赖）
docker pull ghcr.io/autowarefoundation/autoware-auto:latest

# 2. 运行容器并挂载源码目录
docker run -it --rm \
  --name autoware-dev \
  --net=host \
  --gpus all \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/autoware/autoware-auto:/home/autoware/autoware-auto \
  ghcr.io/autowarefoundation/autoware-auto:latest \
  /bin/bash

# 3. 在容器内编译（可选，若镜像已包含预编译版本则跳过）
cd /home/autoware/autoware-auto
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

3.4.3 案例拆解：使用Docker解决环境不一致问题

某团队在3台不同配置的Ubuntu机器上开发，频繁出现“在我机器上能编译，在你机器上不行”的问题。引入Docker后，团队维护一个统一的 Dockerfile，将系统依赖、ROS2版本、AutowareAuto源码版本全部固化。具体做法：在CI流水线中构建镜像并推送至私有仓库，开发人员统一拉取该镜像进行开发。结果：编译错误率下降80%，新成员环境搭建时间从2天缩短至30分钟。此案例的关键在于：Docker不仅隔离了环境，更重要的是将环境配置代码化，实现了版本控制。

3.4.4 常见误区与总结

误区一：在容器内使用 sudo apt install 安装额外包。这会导致容器与镜像不一致，且容器销毁后修改丢失。正确做法是修改Dockerfile并重新构建。
误区二：忽略 --net=host 参数。ROS2的DDS通信依赖多播，默认的bridge网络模式会导致节点发现失败。
误区三：将数据存储在容器可写层。应使用 -v 挂载卷或 --mount type=bind 将源码、数据目录映射到宿主机，防止容器删除后数据丢失。

风险提示：使用 --gpus all 参数需要宿主机安装NVIDIA Container Toolkit。若未安装，容器内无法访问GPU，导致感知模块的CUDA加速不可用。安装命令：sudo apt install -y nvidia-container-toolkit，然后重启Docker服务。

依赖管理与Docker使用的最终目标是：任何开发者在任何机器上，只需执行 docker run 命令即可获得与CI完全一致的开发环境。这不仅是效率问题，更是自动驾驶软件安全性的基本保障——可复现的环境是验证算法正确性的前提。

3.5 环境验证与综合复盘

完成上述所有步骤后，建议执行一套完整的验证流程：启动AutowareAuto自带的仿真示例（如 autoware_auto_launch 中的规划仿真），观察Rviz2中是否正常显示车辆模型与感知结果。同时，通过 docker ps 确认容器状态，通过 ros2 node list 确认所有节点正常通信。若验证通过，则说明开发环境搭建成功，可以开始进行算法开发与调试。

验证项	命令/方法	预期结果
系统基础	`uname -r` / `gcc --version`	内核5.4+，GCC 9.3+
ROS2通信	`ros2 run demo_nodes_cpp talker`	listener正常接收消息
AutowareAuto编译	`colcon build` 无报错	install目录生成所有包
Docker运行	`docker run --rm hello-world`	输出Hello from Docker
GPU加速（可选）	容器内执行 `nvidia-smi`	显示GPU型号与驱动版本

本章从Ubuntu系统配置出发，逐步讲解了ROS2安装、AutowareAuto源码编译以及Docker容器化部署的完整流程。每个环节都强调了“原理-操作-案例-误区”的闭环学习方式。在实际开发中，建议将本章内容固化为团队内部的 setup.sh 脚本或Docker镜像，实现环境搭建的自动化与标准化。记住，一个稳定、可复现的开发环境是自动驾驶算法快速迭代的基石，值得投入时间精心打磨。