本文档面向初次接触 roboto_motors 的开发者，系统梳理从空白系统到成功编译、安装本库所需的全部依赖与操作步骤。在阅读本文前，请确保你的开发机或工控机已运行 Ubuntu 22.04（或同类 Debian 系发行版），且 CAN 硬件已完成物理接线；若尚未配置 CAN 网络接口，建议先前往 CAN总线接口配置 完成相关设置。

Sources: CMakeLists.txt, build_deb.sh, package.xml

依赖概览

roboto_motors 采用 CMake 构建系统，核心代码使用 C++17 标准，并同时输出 C++ 静态库与 Python 绑定模块。下表按功能分类列出所有编译与运行依赖，其中标为「可选」的项仅在 ROS 2 场景下才需要。

若你选择通过预编译的 Debian 包安装，则运行时额外依赖 roboto-base (>= 1.0.0)，该包负责提供底层系统配置与通用库；源码编译时无需手动处理此项。

Sources: CMakeLists.txt, CMakeLists.txt, package.xml, debian/control

环境准备：一键安装系统依赖

在 Ubuntu 22.04 上，绝大多数依赖均可通过官方 apt 源直接安装。打开终端并执行以下命令，即可一次性补齐编译工具链与第三方库。该命令涵盖了 GCC、CMake、ccache 以及 fmt、spdlog、Boost、Eigen3、pybind11、Python3 开发头文件等全部核心依赖，执行前建议先执行 sudo apt update 刷新软件包索引。

sudo apt-get update
sudo apt-get install -y \
  build-essential cmake ccache \
  libfmt-dev libspdlog-dev libboost-system-dev \
  libeigen3-dev pybind11-dev python3-dev

对于 ARM64 架构的嵌入式工控机（如 Jetson、Raspberry Pi），依赖包名称与 x86_64 完全一致，可直接使用相同命令安装。若你的项目基于 ROS 2 生态，还需确保已安装 ros-dev-tools 或对应发行版的 ament_cmake 包，以便后续使用 colcon 编译。

Sources: .github/workflows/build-deb.yml, README.md

安装方式对比与选型

roboto_motors 支持三种主流安装路径，分别面向不同的工程场景。初学者若不确定应选哪一种，可遵循「有 ROS 2 用 colcon，无 ROS 2 用独立 CMake，部署生产环境用 Deb 包」的原则快速决策。

无论选择哪种方式，底层源码与 CMake 结构完全一致：顶层 CMakeLists.txt 通过 add_subdirectory(src) 依次进入 src/drivers 与 src/protocol 目录，分别编译出品牌电机驱动库（dm_motors、evo_motors、lro_motors）与通信协议库（motors_can、motors_canfd），最终由主 motors 库统一链接并导出。

Sources: CMakeLists.txt, src/CMakeLists.txt, src/drivers/CMakeLists.txt, src/protocol/CMakeLists.txt, build_deb.sh

独立 CMake 编译：逐步操作

对于不使用 ROS 2 的开发者，推荐通过独立 CMake 方式编译。该流程完全自包含，不依赖任何 ROS 环境变量，且生成的静态库可直接被外部 CMake 项目通过 find_package(roboto_motors) 引入。下图展示了从源码到安装的核心步骤与分支判断。

flowchart TD
    A[克隆源码仓库] --> B[安装系统依赖]
    B --> C[创建并进入 build 目录]
    C --> D[运行 cmake 配置]
    D --> E{是否交叉编译?}
    E -->|否| F[启用 -march=native 优化]
    E -->|是| G[跳过原生架构优化]
    F --> H[执行 make -j$(nproc)]
    G --> H
    H --> I[安装到指定前缀路径]
    I --> J[验证 C++ 与 Python 模块]

在实际终端中，对应命令如下所示。此处将安装前缀设为 /opt/roboparty，与官方 Debian 包的安装路径保持一致，便于后续切换为包管理安装时不发生路径冲突。若将 -DCMAKE_INSTALL_PREFIX 改为 /usr/local，则可实现系统级安装。

cd /path/to/roboto_motors
rm -rf build && mkdir -p build
cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/opt/roboparty \
  -DCMAKE_PREFIX_PATH=/opt/roboparty
cmake --build build -j$(nproc)
DESTDIR=/tmp/staging cmake --install build

上述命令中，顶层 CMakeLists.txt 会自动检测 ament_cmake，由于未 source ROS 2 环境，检测将以 QUIET 模式静默失败，随后进入纯 CMake 路径；同时 ccache 被设为编译器启动器（CMAKE_CXX_COMPILER_LAUNCHER），可显著减少重复编译时间。产物包括：位于 build/ 下的多个静态库、motors_py Python 扩展模块，以及可供外部项目消费的 roboto_motorsConfig.cmake。

Sources: CMakeLists.txt, CMakeLists.txt, build_deb.sh, cmake/roboto_motorsConfig.cmake

ROS 2 工作空间编译

如果你的机器人软件栈基于 ROS 2（如 Humble、Jazzy），推荐将本仓库置于 ROS 2 工作空间的 src 目录下，通过 colcon 统一构建。ament_cmake 会自动被 find_package(ament_cmake QUIET) 找到，进而激活 ament_export_libraries 与 ament_package 逻辑，使其他 ROS 2 包能够通过 find_package(roboto_motors) 直接引用头文件与库。

# 1. 进入你的 ROS 2 工作空间
cd ~/ros2_ws/src
# 2. 将 roboto_motors 放入 src（假设已克隆或软链接至此）
# 3. 返回工作空间根目录并编译
cd ~/ros2_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select roboto_motors --cmake-args -DCMAKE_BUILD_TYPE=Release
# 4. 加载编译结果
source install/setup.bash

在 ROS 2 模式下，pybind11_add_module 生成的 Python 模块会被正确打包进 install/ 目录，并通过 ament_python 机制暴露在 Python 路径中；C++ 库则通过 ament_export_include_directories 自动暴露头文件搜索路径，无需手动设置 CMAKE_PREFIX_PATH。

Sources: CMakeLists.txt, CMakeLists.txt, package.xml

Debian 包构建（进阶）

对于需要批量部署到多台无编译环境工控机的场景，可使用仓库根目录提供的 build_deb.sh 脚本将源码打包为 .deb。该脚本内部先执行独立 CMake 编译，随后将产物 staged 到临时目录，再调用 dpkg-deb 生成标准 Debian 包。运行前请确保已安装 dpkg-dev 包以提供 dpkg-deb 工具。

sudo apt-get install dpkg-dev
chmod +x build_deb.sh
./build_deb.sh          # 默认生成非 ROS 的部署包
WITH_ROS=1 ./build_deb.sh   # 若需集成 ROS 2，自动检测并 source 环境

生成的 .deb 包依赖 roboto-base (>= 1.0.0)，安装时会通过 postinst 脚本执行 ldconfig，确保动态链接器缓存及时更新。普通开发者通常直接下载 CI 发布的 .deb 包即可，无需自行执行此步骤。

Sources: build_deb.sh, debian/control, debian/postinst

验证安装

完成编译或安装后，建议通过以下两条极简命令快速验证环境是否正常。第一条验证 Python 绑定模块能否成功导入，第二条验证 C++ 头文件与 CMake Config 是否位于系统搜索路径。

# 验证 Python 绑定
python3 -c "import motors_py; print('Python OK')"

# 验证 C++ 头文件存在（以安装到 /opt/roboparty 为例）
ls /opt/roboparty/include/motor_driver.hpp
ls /opt/roboparty/lib/cmake/roboto_motors/roboto_motorsConfig.cmake

若使用 ROS 2 方式编译，验证命令应替换为 python3 -c "from roboto_motors import motors_py" 或检查 ~/ros2_ws/install/roboto_motors/include/ 目录。一旦验证通过，即表示编译依赖与安装步骤已全部就绪。

Sources: CMakeLists.txt, CMakeLists.txt, cmake/roboto_motorsConfig.cmake

下一步

环境准备就绪后，可根据你的开发语言选择对应的上手教程继续学习：

• 如果你计划使用 Python 快速验证电机控制逻辑，请阅读 Python SDK快速上手。
• 如果你需要集成到现有 C++ 项目或关注底层性能，请阅读 C++ SDK快速上手。

若想深入理解构建系统的设计原理（如各子目录 CMake 的模块化组织、roboto_motorsConfig.cmake 的导出机制），可进一步参考 CMake构建系统与依赖管理。