CMake 构建系统与依赖管理

本项目采用 CMake 3.12+ 作为核心构建工具，并围绕一个关键设计原则展开：同一套构建脚本同时支持独立部署（Debian 包模式）与 ROS 2 生态集成（ament_cmake 模式）。开发者无需维护两份构建逻辑，仅通过环境变量与可选依赖检测即可在两个场景间切换。本页将系统解析目录层级结构、多目标静态库的链接关系、外部依赖的查找策略，以及从源码编译到 Debian 包生成的完整流水线。

Sources: CMakeLists.txt

双模式构建架构

构建系统的核心挑战在于兼顾 非 ROS 用户的独立安装需求 与 ROS 2 工作空间下的标准 colcon 构建流程。项目通过 find_package(ament_cmake QUIET) 的静默探测实现自动分支：当环境中存在 ROS 2 时，ament_cmake_FOUND 为真，构建系统会执行 ament_export_libraries、ament_export_include_directories 和 ament_package()，使当前包能被 colcon 正确识别与链接；若未检测到 ROS 2，则跳过上述调用，并以纯 CMake 模式完成安装。这一设计保证了在两种场景下，add_library、target_link_libraries 与 install 等核心指令完全一致，消除了因模式差异导致的构建行为漂移。

Sources: CMakeLists.txt

flowchart TD
    A[源码树] --> B{find_package<br/>ament_cmake QUIET}
    B -->|FOUND| C[ROS 2 模式<br/>ament_package导出]
    B -->|NOT FOUND| D[独立模式<br/>纯CMake安装]
    C --> E[安装 roboto_imuConfig.cmake]
    D --> E
    E --> F[生成 Debian 包]

目录层级与目标依赖图

构建脚本按源码物理目录分层管理，形成三级 CMake 入口：根目录负责全局配置与最终目标组装，src/ 负责子模块聚合，src/drivers/ 与 src/protocol/ 负责最小单元库的编译。这种分层结构使得新增驱动或协议解析器时，仅需在对应层级新增 add_subdirectory 调用，无需修改根级脚本。

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

graph TD
    Root[CMakeLists.txt<br/>全局配置+总装] --> Src[src/CMakeLists.txt]
    Src --> Drv[src/drivers/CMakeLists.txt]
    Src --> Prot[src/protocol/CMakeLists.txt]
    Drv --> Hip[src/drivers/hipnuc/CMakeLists.txt]
    Prot --> Can[src/protocol/can]
    Prot --> Serial[src/protocol/serial]
    
    Root -->|add_library| LibIMU[imu<br/>主静态库]
    Hip -->|add_library| LibHip[hipnuc_imu<br/>驱动静态库]
    Prot -->|add_library| LibProt[imu_protocol<br/>协议静态库]
    Root -->|pybind11_add_module| PyMod[imu_py<br/>Python模块]
    
    LibIMU -->|链接| LibHip
    LibIMU -->|链接| LibProt
    LibHip -->|链接| LibProt
    PyMod -->|链接| LibIMU

外部依赖与查找策略

项目依赖的现代 C++ 库与工具链全部通过 find_package 显式声明，避免了隐式系统路径带来的可移植性问题。根级 CMakeLists.txt 统一完成查找，并将公共链接集合定义为 PUBLIC_DEPENDENCIES 变量，供子目录共享。

依赖包	用途	查找方式	是否必需
`ament_cmake`	ROS 2 构建导出与打包	`QUIET` 静默查找	否
`spdlog`	结构化日志输出	`REQUIRED`	是
`fmt`	格式化字符串	`REQUIRED`	是
`Python3`	Python 运行时与头文件	`COMPONENTS Interpreter Development REQUIRED`	是
`pybind11`	C++ / Python 绑定生成	`REQUIRED`	是

fmt 与 spdlog 不仅在编译期被链接，还在自定义的 roboto_imuConfig.cmake 中通过 find_dependency 向下游传递，确保使用 find_package(roboto_imu) 的第三方工程能自动解析这两个间接依赖。

Sources: CMakeLists.txt, cmake/roboto_imuConfig.cmake

静态库目标与链接关系

项目将代码划分为三个静态库，以实现编译隔离与增量构建效率的最大化。每个库的职责、源码组织方式与链接接口如下表所示：

目标名称	所在目录	源码收集方式	公开头文件搜索路径	链接的依赖
`imu_protocol`	`src/protocol/`	`GLOB_RECURSE *.cpp`	`./can` `./serial`	`PUBLIC_DEPENDENCIES`
`hipnuc_imu`	`src/drivers/hipnuc/`	`AUX_SOURCE_DIRECTORY`	`./` `${PROJECT_SOURCE_DIR}/include` `${PROJECT_SOURCE_DIR}/src`	`PUBLIC_DEPENDENCIES` + `imu_protocol`
`imu`	根目录	显式列出 `src/imu_driver.cpp`	`${CMAKE_CURRENT_SOURCE_DIR}/include` `${CMAKE_CURRENT_SOURCE_DIR}/src`	`PUBLIC_DEPENDENCIES` + `hipnuc_imu` + `imu_protocol`

值得注意的细节是：根级 imu 库的 target_include_directories 同时使用了 $<BUILD_INTERFACE:...> 与 $<INSTALL_INTERFACE:include> 生成器表达式。这保证了在构建期能直接引用源码树内的 include/ 与 src/ 目录，而在安装期则只暴露标准前缀下的 include/ 路径，避免将内部实现头文件泄露给下游。

Sources: src/protocol/CMakeLists.txt, src/drivers/hipnuc/CMakeLists.txt, CMakeLists.txt

Python 绑定构建

Python 扩展模块 imu_py 通过 pybind11_add_module 宏生成，该宏由 pybind11 的 CMake 配置包提供，内部已处理好 Python 头文件路径、编译标志与平台特定的动态库后缀。模块直接链接主静态库 imu，因此自动继承了 imu 的全部传递依赖（hipnuc_imu、imu_protocol、fmt、spdlog、pthread）。安装路径通过 Python3_VERSION_MAJOR/MINOR 动态拼接为 lib/pythonX.Y/site-packages，与系统 Python 的模块搜索路径对齐。

Sources: CMakeLists.txt

安装导出与下游消费

为了让非 ROS 环境的下游工程能够通过 find_package(roboto_imu) 使用本库，项目提供了手写式的 roboto_imuConfig.cmake。与 CMake 自动生成的导出文件不同，该配置文件采用 INTERFACE IMPORTED 目标 模式，手动聚合 imu、hipnuc_imu、imu_protocol 三个静态库的路径，并重新声明 fmt::fmt 与 spdlog::spdlog 的链接要求。安装路径固定为 lib/cmake/roboto_imu，符合 CMake find_package 的搜索约定。

Sources: cmake/roboto_imuConfig.cmake, CMakeLists.txt

Debian 打包流程

build_deb.sh 脚本将 CMake 的 cmake --install 与 dpkg-deb 原生工具串联，形成一条无 ROS 依赖的独立部署流水线。其核心逻辑可分为编译、组装、打包三个阶段。

flowchart LR
    A[build_deb.sh] --> B{WITH_ROS=1?}
    B -->|是| C[source ROS 2 环境]
    B -->|否| D[跳过 ROS]
    C --> E[cmake .. -DCMAKE_INSTALL_PREFIX=/opt/roboparty]
    D --> E
    E --> F[make -j]
    F --> G[DESTDIR安装到<br/>build/destdir]
    G --> H[复制到 DEBIAN 目录结构]
    H --> I[生成 control 文件]
    I --> J[dpkg-deb --build]

脚本通过 WITH_ROS 环境变量控制是否引入 ROS 2 工具链，默认值为 0，对应发布给终端用户的 Debian 包；设为 1 时则自动检测并加载 jazzy、iron、humble、rolling 等发行版环境。DESTDIR 机制将安装前缀临时重定向到 build/destdir，随后将内容平移至以 /opt/roboparty 为根的文件树中，最终与 init_imu.sh、udev rules 及维护者脚本共同封装为 .deb。

Sources: build_deb.sh, debian/control

持续集成与依赖预装

GitHub Actions 工作流在 ubuntu-22.04-arm 运行器上完成 arm64 架构的自动化打包。构建前通过 apt-get 预装系统级开发包：build-essential、cmake、ccache、libspdlog-dev、libfmt-dev、python3-dev、pybind11-dev。其中 ccache 与根级 CMAKE_CXX_COMPILER_LAUNCHER ccache 设置联动，显著加速重复编译。当推送标签匹配 imu-v* 时，工作流会自动将构建产物上传至 GitHub Release。

Sources: .github/workflows/build-deb.yml, CMakeLists.txt

构建快速参考

以下命令分别对应两种典型使用场景：

独立模式（生成 Debian 包）

sudo apt install build-essential cmake libspdlog-dev libfmt-dev python3-dev pybind11-dev
./build_deb.sh          # WITH_ROS=0 为默认值
sudo dpkg -i roboto-imu_1.1.3_*.deb

ROS 2 工作空间模式

mkdir -p ~/ws/src && cd ~/ws/src
git clone <repo> roboto_imu
cd ~/ws
colcon build --packages-select roboto_imu

若需进一步了解 ROS 2 集成的细节，请参阅 ROS 2 集成与 ament_cmake；若关注 Debian 包在 CI 中的自动发布机制，请参阅 Debian 打包与持续部署。对于 Python 绑定的内部实现原理，可阅读 pybind11 Python 绑定机制。