Debian 打包与持续部署

本文档聚焦 roboto-imu 的 Debian 软件包构建机制与持续交付流水线。内容涵盖本地一键打包脚本 build_deb.sh 的完整执行链路、软件包内部结构与依赖关系、GitHub Actions 自动化构建与发布策略，以及 ROS 2 与纯 CMake 双模式构建的切换原理。掌握这些机制后，开发者即可在本地或 CI 环境中稳定产出适用于 ARM64 目标平台的 .deb 安装包。

打包架构概览

本项目的 Debian 打包采用手动 dpkg-deb 方案，而非传统的 debhelper/dh 工具链。核心由 build_deb.sh 充当编排器：它先通过 CMake 将源码编译为静态库与 Python 扩展模块，再利用 DESTDIR 机制将产物暂存到隔离目录，随后组装 DEBIAN 元数据并调用 dpkg-deb --root-owner-group --build 生成最终包文件。整个流程以 /opt/roboparty 作为安装前缀，符合嵌入式机器人系统的 vendor-specific 部署惯例，同时避免与系统 /usr 目录冲突。

flowchart TD
    A[源码仓库] --> B{WITH_ROS?}
    B -->|是| C[source /opt/ros/&lt;distro&gt;/setup.bash]
    B -->|否| D[CMake 配置<br/>-DCMAKE_INSTALL_PREFIX=/opt/roboparty]
    C --> D
    D --> E[make -j$(nproc)]
    E --> F[DESTDIR 暂存安装<br/>build/destdir]
    F --> G[组装 DEBIAN 目录结构]
    G --> H[复制 postinst / postrm]
    H --> I[sed 生成 control]
    I --> J[dpkg-deb --root-owner-group --build]
    J --> K[roboto-imu_1.1.3_arm64.deb]

Sources: build_deb.sh, CMakeLists.txt

本地打包流程详解

执行 ./build_deb.sh 即可完成从零到 .deb 的全流程。脚本首行声明 set -e，确保任一阶段失败立即终止，避免产出残次包。脚本内部首先读取 WITH_ROS 环境变量（默认为 0）：若置为 1，则按 jazzy → iron → humble → rolling 的顺序探测并 source 首个可用的 ROS 2 环境；若置为 0，则直接进入纯 CMake 构建模式。随后脚本在 build 目录中执行 CMake，强制指定 -DCMAKE_BUILD_TYPE=Release 与安装前缀 /opt/roboparty，并通过 DESTDIR 将 cmake --install 的输出重定向到 build/destdir，实现构建与打包隔离。最后，脚本将编译产物、init_imu.sh、udev 规则（如存在）以及 DEBIAN 控制脚本汇集到以 ${PACKAGE}_${VERSION}_${ARCH} 命名的目录中，交由 dpkg-deb 封包。

Sources: build_deb.sh

软件包结构与内容

生成的 roboto-imu_1.1.3_arm64.deb 包含以下核心组件，覆盖 C++ 开发库、Python SDK 与现场配置工具。所有文件均安装于 /opt/roboparty 之下，外部项目可通过 find_package(roboto_imu) 并配合 cmake/roboto_imuConfig.cmake 完成集成。

组件类别	安装路径示例	说明
C++ 静态库	`/opt/roboparty/lib/libimu.a` 等	包含 `imu`、`hipnuc_imu`、`imu_protocol` 三个静态库
头文件	`/opt/roboparty/include/imu_driver.hpp`	对外暴露的 C++ SDK 头文件
Python 绑定	`/opt/roboparty/lib/python3.x/site-packages/imu_py*.so`	由 pybind11 编译的 Python 扩展模块
CMake 配置	`/opt/roboparty/lib/cmake/roboto_imu/roboto_imuConfig.cmake`	提供 `roboto_imu::roboto_imu` 导入目标
初始化脚本	`/opt/roboparty/bin/init_imu.sh`	通过 CAN 报文修改 HiPNUC IMU 参数的现场工具

debian/control 作为模板存在，其中 VERSION_PLACEHOLDER 与 ARCH_PLACEHOLDER 由 sed 在打包阶段动态替换。包元信息显式声明依赖 roboto-base (>= 1.0.0)，并属于 libs 分类。

Sources: build_deb.sh, debian/control, cmake/roboto_imuConfig.cmake

安装维护脚本

debian/postinst 与 debian/postrm 负责在软件包生命周期中执行系统级维护。安装完成后，postinst 调用 ldconfig 更新动态链接器缓存，并检测 /run/udev 目录是否存在；若存在，则执行 udevadm control --reload-rules 与 udevadm trigger 使新规则即时生效。卸载时，postrm 同样在 remove 或 purge 场景下重载 udev 规则并更新 ldconfig，确保系统状态回退干净。当前仓库中 debian/conffiles 为空文件，脚本仅在存在时才会将其复制到 DEBIAN 目录，保留了后续添加配置文件的扩展余地。

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

持续集成流水线

GitHub Actions 工作流定义于 .github/workflows/build-deb.yml，专门为 ARM64 架构选用 ubuntu-22.04-arm 原生运行器，避免交叉编译带来的复杂度。流水线在以下四种场景触发：向 main 或 master 分支推送代码、创建符合 imu-v* 模式的标签、针对上述分支的 Pull Request，以及手动 workflow_dispatch。构建阶段首先安装 build-essential、cmake、ccache、dpkg-dev、libspdlog-dev、libfmt-dev、python3-dev 与 pybind11-dev，随后直接调用 build_deb.sh。成功封包后，产物以 Artifact 形式上传；若触发源为标签推送，则进一步通过 softprops/action-gh-release 自动创建 Release 并附加 .deb 文件，实现标签即发布的交付体验。

flowchart LR
    A[Push / Tag / PR] --> B[ubuntu-22.04-arm 运行器]
    B --> C[安装构建依赖<br/>build-essential cmake ccache ...]
    C --> D[执行 build_deb.sh]
    D --> E[上传 Artifact<br/>roboto-imu-arm64-deb]
    E --> F{Tag 匹配 imu-v*?}
    F -->|是| G[创建 GitHub Release<br/>自动附加 .deb]
    F -->|否| H[结束]

Sources: .github/workflows/build-deb.yml

ROS 2 与纯 CMake 双模式构建

build_deb.sh 通过 WITH_ROS 环境变量实现了同一代码库、两种构建目标的灵活切换。默认模式（WITH_ROS=0）面向独立部署：CMake 将产物安装到 /opt/roboparty，并同步部署 roboto_imuConfig.cmake 供外部非 ROS 项目引用。当 WITH_ROS=1 时，脚本先 source ROS 2 环境，使 ament_cmake 可被 find_package 探测到；此时根目录 CMakeLists.txt 中的条件分支 if(ament_cmake_FOUND) 生效，额外执行 ament_export_libraries、ament_export_include_directories 与 ament_package()，生成 ROS 2 工作空间所需的编译与运行依赖信息。package.xml 中声明的版本号 1.1.3 与 build_deb.sh 保持一致，确保 ROS 生态与 Debian 包版本同源。

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

版本管理与发布策略

当前版本号 1.1.3 硬编码于 build_deb.sh 第 8 行，与 package.xml 中的 <version> 标签保持同步。发布新版本时，维护者需同时更新这两处，并推送形如 imu-v1.1.4 的 Git 标签。GitHub Actions 检测到 refs/tags/imu-v* 引用后，自动触发 Release 创建流程并将构建产物上传至对应 Release 页面，无需人工手动附加二进制文件。本地开发者亦可通过设置环境变量直接覆盖行为，例如 WITH_ROS=1 ./build_deb.sh 即可在已安装 ROS 2 的宿主机构建面向 ROS 工作空间的安装树。

Sources: build_deb.sh, .github/workflows/build-deb.yml

下一步阅读

完成 Debian 打包与部署流程的学习后，建议继续阅读以下页面，以打通从构建到硬件通信的完整链路：

若需理解本包的 CMake 目标与依赖解析细节，请参阅 CMake 构建系统与依赖管理。
若需将本库作为 ROS 2 组件集成到更大机器人系统中，请参阅 ROS 2 集成与 ament_cmake。
若需在现场使用 init_imu.sh 修改 IMU 波特率与输出格式，请参阅波特率配置与初始化脚本。
若需深入理解 Python 扩展模块的绑定机制，请参阅 pybind11 Python 绑定机制。