环境与构建

基线环境

macOS 可以执行源码检查和不依赖 ROS 的单元测试，但 ROS Noetic 构建和仿真必须在 Ubuntu 20.04 上完成。

获取源码

目标机须预先安装 Ubuntu 20.04 和 ROS Noetic。先安装 Git：

# 更新软件包索引。
sudo apt update
# 安装 Git。
sudo apt install -y git
# 返回当前用户主目录，仓库将保存为 ~/robotac。
cd ~

GitHub 和 Gitee 选择一种即可。网络能够稳定访问 GitHub 时使用：

# 从 GitHub 获取 Robotac 源码。
git clone https://github.com/YunDrone-Team/robotac.git

网络条件不佳时使用 Gitee 镜像：

# 从 Gitee 镜像获取 Robotac 源码。
git clone https://gitee.com/yundrone_sunray2023/robotac.git

两种方式都会创建 ~/robotac。该目录本身就是 catkin 工作空间，不需要另建工作空间目录， 也不要将本仓库放入另一个 catkin 工作空间。本文后续命令均从 ~/robotac 执行。

首次安装

Jetson Orin Nano、Nano Super 和 Orin NX 首次安装时执行：

# 进入 Robotac 仓库根目录。
cd ~/robotac
# 完成平台预检、依赖和定制 SDK 安装、比赛构建及离线测试。
./tools/setup_jetson_orin.sh
# 加载构建后的工作空间环境。
source devel/setup.bash

部署脚本只接受 ARM64 的 Jetson Orin Nano、Nano Super 或 Orin NX（包括设备树显示为 NVIDIA Orin NX Developer Kit 的开发套件），以及 Ubuntu 20.04 和 ROS Noetic 环境，并要求 由工作空间所有者以普通用户身份运行。它不会启动 ROS 节点、 不连接飞机、不安装相机或舵机 udev、不写雷达持久网络，也不修改 PX4 参数。脚本完成后，表示依赖 已经安装、工作空间已经构建并完成离线检查；雷达、相机、飞控、舵机和机械机构仍须按硬件配置 文档逐项确认。旧入口 ./tools/setup_orin_nano_super.sh 继续保留，并转发到相同的部署流程。

依赖安装脚本 install_ubuntu20.sh 安装 apt 与 rosdep 依赖，并构建系统级 Livox-SDK2 和 apriltag。比赛运行构建使用系统预编译的 MAVROS、MAVROS Extras 和 AprilTag ROS；安装 脚本会一并安装对应的 Noetic 包。项目不下载 GeographicLib 数据集，当前 MAVROS 白名单也 不启用全局定位插件。 第三方库和 catkin 默认使用 nproc - 1 个并行任务 （单核主机使用 1 个），为系统和 ROS 进程保留一个逻辑 CPU。内存受限时可显式降低 ROBOTAC_BUILD_JOBS，资源充足时也可按需覆盖：

# 使用 4 个并行任务安装依赖。
ROBOTAC_BUILD_JOBS=4 ./tools/install_ubuntu20.sh
# 使用 4 个并行任务完成安装、构建和检查。
ROBOTAC_BUILD_JOBS=4 ./tools/setup_jetson_orin.sh
# 使用 4 个并行任务执行 catkin 构建。
ROBOTAC_BUILD_JOBS=4 ./tools/test_02_build.sh

比赛运行构建

# 只编译比赛运行需要的本地包，并检查系统 ROS 包没有被源码遮蔽。
./tools/test_02_build.sh
# 加载构建后的工作空间环境。
source devel/setup.bash

比赛运行构建编译 livox_ros_driver2、fast_lio、web_cam 和四个 Robotac 自有包。 libmavconn、mavros_msgs、mavros、mavros_extras 和 apriltag_ros 直接使用 /opt/ros/noetic 的二进制包。构建成功后应能发现以下项目包：

# 查找硬件启动包。
rospack find robotac_bringup
# 查找定位包。
rospack find robotac_localization
# 查找教学示例包。
rospack find robotac_examples
# 查找舵机驱动包。
rospack find robotac_servo

日常增量构建

# 执行日常 catkin 增量构建。
./tools/build.sh
# 重新加载工作空间环境。
source devel/setup.bash

修改 Python、launch 或配置后仍应重新执行源码检查。修改本地比赛包的 package.xml、CMake 或消息依赖后，重新执行比赛运行构建。

全源码构建

需要验证仓库内 MAVROS、MAVROS Extras、AprilTag ROS 和上游测试包时执行：

# 在独立 build/full 和 devel_full 中构建全部源码包。
./tools/build_full.sh
# 仅在验证全源码构建结果时加载该环境。
source devel_full/setup.bash

全源码构建不覆盖比赛运行环境 devel，日常运行仍应加载 devel/setup.bash。

离线测试

# 检查源码、接口和文档链接。
./tools/test_01_source.sh
# 运行纯单元测试。
./tools/test_03_unit.sh
# 运行简化假飞控仿真。
./tools/test_04_simulation.sh

各工具检查的内容如下：

test_05_hardware_readonly.sh 不属于离线测试，不应在容器或无设备环境执行。

常见构建问题

未找到 ROS Noetic

确认 /opt/ros/noetic/setup.bash 存在，并在 Ubuntu 20.04 执行。不得用其他 ROS 发行版的 环境变量继续构建。

rosdep 未初始化

# 初始化 rosdep（仅在系统尚未初始化时执行）。
sudo rosdep init
# 更新 rosdep 依赖索引。
rosdep update

系统已初始化时不重复执行 rosdep init。

找不到 Livox SDK 或 apriltag

重新执行 tools/install_ubuntu20.sh，检查 cmake --install 与 ldconfig 是否成功。不要在 第三方源码目录中临时复制动态库。

构建目录来自其他机器

build/ 和 devel/ 不应跨机器同步。删除本机生成目录后重新构建；该操作不得影响 src/ 和未提交源码。

下一步

首次连接真实硬件时，不要直接启动整套 bringup。先按硬件与配置 运行 sensor_setup.py，确认机载网卡地址、雷达地址和相机稳定设备名，再分别启动传感器节点。