自动驾驶中间件iceoryx 构建指南

自动驾驶中间件iceoryx 构建指南

本文档总结了 iceoryx 的常见构建方式和配置选项，帮助开发者快速选择适合的构建方案。

所有代码、脚本都经过验证，关于构建看完本文不需要再看其他的。

📋 目录

• 快速开始
• 构建选项说明
• 常见构建场景
• 高级构建配置
• 故障排查

---

快速开始

下载源码

git clone https://github.com/eclipse-iceoryx/iceoryx.git
cd iceoryx

最小化构建（默认配置）

# 最基本的构建，只构建核心库
cmake -Bbuild -Hiceoryx_meta
cmake --build build

# 或使用简化方式
cd iceoryx_meta
mkdir -p build && cd build
cmake ..
make -j$(nproc)

包含内容：

• ✅ iceoryx_hoofs（基础工具库）
• ✅ iceoryx_posh（发布-订阅中间件）
• ✅ iox-roudi（路由守护进程）
• ✅ C 语言绑定

不包含：

• ❌ Examples
• ❌ Tests
• ❌ Introspection 工具

---

构建选项说明

核心选项

选项	默认值	说明
BINDING_C	ON	构建 C 语言绑定
BUILD_ALL	OFF	构建所有组件（examples + tests + introspection + binding_c）
BUILD_DOC	OFF	构建并生成文档
BUILD_SHARED_LIBS	OFF	构建共享库（默认为静态库）
BUILD_STRICT	OFF	启用 -Werror（将警告视为错误）
BUILD_TEST	OFF	构建所有测试
CCACHE	ON	使用 ccache 加速编译
COVERAGE	OFF	启用代码覆盖率分析
EXAMPLES	OFF	构建所有示例程序
INTROSPECTION	OFF	构建监控客户端（需要 ncurses 库）
TOML_CONFIG	ON	启用 TOML 配置文件支持

高级选项

选项	默认值	说明
ADDRESS_SANITIZER	OFF	启用地址检查器 AddressSanitizer（用于检测内存错误）
THREAD_SANITIZER	OFF	启用线程检查器 ThreadSanitizer（用于检测数据竞争）
ONE_TO_MANY_ONLY	OFF	限制为 1:n 通信模式
IOX_EXPERIMENTAL_POSH	OFF	导出实验性 posh 功能
IOX_EXPERIMENTAL_32_64_BIT_MIX_MODE	OFF	启用 32/64 位混合模式
IOX_ROUDI_DEFAULT_MONITORING_MODE	OFF	默认启用 RouDi 监控模式
IOX_REPRODUCIBLE_BUILD	ON	创建可重现构建
TEST_WITH_ADDITIONAL_USER	OFF	测试访问控制（需要额外用户账户）
TEST_WITH_HUGE_PAYLOAD	OFF	测试大于 2GB 的负载

构建类型

# Debug 构建（包含调试符号）
cmake -Bbuild -DCMAKE_BUILD_TYPE=Debug

# Release 构建（优化性能）
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release

# RelWithDebInfo（优化 + 调试符号）
cmake -Bbuild -DCMAKE_BUILD_TYPE=RelWithDebInfo

# MinSizeRel（最小化二进制大小）
cmake -Bbuild -DCMAKE_BUILD_TYPE=MinSizeRel

---

常见构建场景

场景1：学习和实验（推荐初学者）

# 构建示例程序
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DEXAMPLES=ON

cmake --build build -j$(nproc)

说明：

• 构建所有官方示例（hello world、waitset、request-response 等）
• Debug 模式便于调试
• 示例位置：build/iceoryx_examples/

运行示例：

# 1. 启动 RouDi
./build/iox-roudi &

# 2. 运行 hello world 示例
# 终端1：订阅者
./build/iceoryx_examples/icehello/iox-cpp-subscriber-helloworld

# 终端2：发布者
./build/iceoryx_examples/icehello/iox-cpp-publisher-helloworld

---

场景2：开发和调试

# 启用所有开发工具 - 会下载googletest工具
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DEXAMPLES=ON \
    -DBUILD_TEST=ON \
    -DINTROSPECTION=ON \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

cmake --build build -j$(nproc)

说明：

• 包含测试和示例
• 启用 introspection 工具（iox-introspection-client）
• 生成 compile_commands.json（用于 clangd、VS Code 等）

运行测试：

# 运行所有模块测试
./build/hoofs/test/hoofs_moduletests
./build/posh/test/posh_moduletests
./build/binding_c/test/binding_c_moduletests

# 运行集成测试
./build/posh/test/posh_integrationtests
./build/binding_c/test/binding_c_integrationtests
./build/hoofs/test/hoofs_integrationtests

# 或使用通配符运行所有测试
find ./build -name '*test*' -type f -executable -exec {} \;

使用 Introspection：

# 如果还没构建 introspection 客户端，需要先构建
make -C build/iceoryx_introspection iox-introspection-client

# 启动 RouDi
./build/iox-roudi &

# 启动 introspection 客户端查看所有信息
./build/iceoryx_introspection/iox-introspection-client --all

# 或查看特定信息
./build/iceoryx_introspection/iox-introspection-client --mempool  # 查看内存池
./build/iceoryx_introspection/iox-introspection-client --port     # 查看端口
./build/iceoryx_introspection/iox-introspection-client --process  # 查看进程

# 设置更新频率（单位：毫秒，默认 1000）
./build/iceoryx_introspection/iox-introspection-client --all --time 500

注意：

• 需要先安装 ncurses：sudo apt install libncurses5-dev
• 构建时必须启用 -DINTROSPECTION=ON 选项
• introspection 客户端需要显式构建（使用上面的 make 命令）
• 使用交互式界面时，按 q 退出

---

场景3：完整构建（包含所有功能）

# 使用 BUILD_ALL 一次性启用所有功能
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DBUILD_ALL=ON

cmake --build build -j$(nproc)

说明：

• BUILD_ALL=ON 会自动启用：
  • EXAMPLES=ON
  • BUILD_TEST=ON
  • INTROSPECTION=ON
  • BINDING_C=ON

---

场景4：生产环境构建

# Release 构建，静态库，无测试
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=OFF \
    -DEXAMPLES=OFF \
    -DBUILD_TEST=OFF \
    -DINTROSPECTION=OFF \
    -DCMAKE_INSTALL_PREFIX=/usr/local

cmake --build build -j$(nproc)
sudo cmake --build build --target install

说明：

• Release 优化
• 静态链接（便于部署）
• 不包含测试和示例
• 可选：安装到系统路径

卸载已安装的 iceoryx：

# 方法1：使用 CMake 生成的 install_manifest.txt（推荐）
# 使用 -f 参数忽略不存在的文件错误
sudo xargs rm -f < build/install_manifest.txt
sudo ldconfig

# 或者逐行检查并删除（更安全）
cat build/install_manifest.txt | while read file; do
    if [ -f "$file" ]; then
        sudo rm "$file"
        echo "Removed: $file"
    else
        echo "Skip (not found): $file"
    fi
done
sudo ldconfig

# 方法2：手动删除（如果 install_manifest.txt 不存在）
sudo rm -rf /usr/local/include/iceoryx*
sudo rm -rf /usr/local/lib/libiceoryx*
sudo rm -f /usr/local/bin/iox-roudi
sudo rm -rf /usr/local/lib/cmake/iceoryx*
sudo ldconfig

# 方法3：查看安装了哪些文件
# 如果不确定安装了哪些文件，可以先查看 install_manifest.txt
cat build/install_manifest.txt

# 或者先安装到临时目录查看
cmake -Bbuild -Hiceoryx_meta -DCMAKE_INSTALL_PREFIX=/tmp/iceoryx_test
cmake --build build --target install
find /tmp/iceoryx_test -type f

注意：

• 卸载时出现 "No such file or directory" 错误是正常的，表示文件已被删除或未安装
• 使用 -f 参数可以忽略这些错误
• 卸载后记得运行 sudo ldconfig 更新动态链接库缓存

---

场景5：性能分析和优化

# 使用 RelWithDebInfo + introspection
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DEXAMPLES=ON \
    -DINTROSPECTION=ON \
    -DCMAKE_CXX_FLAGS="-fno-omit-frame-pointer"

cmake --build build -j$(nproc)

说明：

• RelWithDebInfo：优化 + 调试符号
• -fno-omit-frame-pointer：便于性能分析工具（perf、gprof）

使用 perf 分析：

# 1. 安装 perf 工具（如果未安装）
sudo apt install linux-tools-common linux-tools-generic linux-tools-$(uname -r)

# 2. 配置 perf 权限（临时，重启后失效）
sudo sysctl -w kernel.perf_event_paranoid=-1

# 或永久配置（推荐）
echo 'kernel.perf_event_paranoid = -1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# 3. 启动 RouDi
./build/iox-roudi &

# 4. 使用 perf 分析发布者（程序会持续运行，等待几秒后 Ctrl+C 停止）
perf record -g ./build/iceoryx_examples/icehello/iox-cpp-publisher-helloworld

# 5. 查看分析报告
perf report

# 可选：使用 sudo 运行 perf（如果不想修改系统配置）
sudo perf record -g ./build/iceoryx_examples/icehello/iox-cpp-publisher-helloworld
sudo perf report

# 或使用 gprof（需要编译时加 -pg 选项）
gprof ./build/iceoryx_examples/icehello/iox-cpp-publisher-helloworld gmon.out

perf 权限说明：

• perf_event_paranoid = -1：允许所有用户使用 perf（推荐开发环境）
• perf_event_paranoid = 0：禁止访问原始跟踪点
• perf_event_paranoid = 1：禁止 CPU 事件访问
• perf_event_paranoid = 2：禁止内核分析（默认值）
• 生产环境建议使用 sudo perf 而不是修改系统配置

---

场景6：内存和并发错误检测

# 使用地址检查器 AddressSanitizer 检测内存错误
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DEXAMPLES=ON \
    -DADDRESS_SANITIZER=ON

cmake --build build -j$(nproc)

# 运行示例会自动检测内存问题
./build/iceoryx_examples/icehello/iox-cpp-publisher-helloworld

使用线程检查器 ThreadSanitizer 检测数据竞争：

cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DEXAMPLES=ON \
    -DTHREAD_SANITIZER=ON

cmake --build build -j$(nproc)

注意 ：不能同时启用 ADDRESS_SANITIZER 和 THREAD_SANITIZER。

---

场景7：代码覆盖率分析

# 启用覆盖率收集
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DBUILD_TEST=ON \
    -DCOVERAGE=ON

cmake --build build -j$(nproc)

# 运行测试
cd build
./hoofs/test/hoofs_moduletests
./posh/test/posh_moduletests
./posh/test/posh_integrationtests

# 生成覆盖率报告（需要 lcov）
# 安装 lcov（如果未安装）
sudo apt install lcov  # Ubuntu/Debian
lcov --capture --directory . --output-file coverage.info
genhtml coverage.info --output-directory coverage_report

---

场景8：交叉编译（嵌入式系统）

# 使用工具链文件交叉编译
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain.cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=OFF

cmake --build build -j$(nproc)

示例工具链文件 （arm-toolchain.cmake）：

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)

set(CMAKE_FIND_ROOT_PATH /usr/arm-linux-gnueabihf)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

---

场景9：共享库构建

# 构建动态链接库（.so 文件）
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=ON \
    -DCMAKE_INSTALL_PREFIX=/usr/local

cmake --build build -j$(nproc)
sudo cmake --build build --target install

说明：

• 生成 .so 文件而不是 .a 文件
• 减少应用程序二进制大小
• 便于多个程序共享 iceoryx 库

---

场景10：严格模式开发（推荐 CI/CD）

# 将所有警告视为错误
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DBUILD_STRICT=ON \
    -DBUILD_TEST=ON \
    -DEXAMPLES=ON

cmake --build build -j$(nproc)

说明：

• 启用 -Werror
• 确保代码质量
• 适合持续集成环境

---

高级构建配置

自定义安装路径

cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_INSTALL_PREFIX=$HOME/iceoryx \
    -DCMAKE_BUILD_TYPE=Release

cmake --build build -j$(nproc)
cmake --build build --target install

使用 Ninja 构建系统（更快）

# 安装 ninja（如果未安装）
sudo apt install ninja-build  # Ubuntu/Debian

# 使用 Ninja
cmake -Bbuild -Hiceoryx_meta -GNinja \
    -DCMAKE_BUILD_TYPE=Release \
    -DEXAMPLES=ON

ninja -C build -j$(nproc)

指定 C++ 标准

cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_CXX_STANDARD=17 \
    -DCMAKE_CXX_STANDARD_REQUIRED=ON

cmake --build build -j$(nproc)

启用 ccache 加速

# 确保安装了 ccache
sudo apt install ccache  # Ubuntu/Debian

# 构建（默认启用 CCACHE=ON）
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DEXAMPLES=ON

cmake --build build -j$(nproc)

# 查看 ccache 统计
ccache -s

清理并重新构建

# 完全清理
rm -rf build
cmake -Bbuild -Hiceoryx_meta -DEXAMPLES=ON
cmake --build build -j$(nproc)

# 或者使用工具脚本
./tools/iceoryx_build_test.sh clean

---

构建输出说明

构建产物位置

build/
├── iox-roudi                       # RouDi 守护进程
├── compile_commands.json           # 编译数据库（LSP 支持）
├── iceoryx_examples/               # 示例程序（如果启用 EXAMPLES）
│   ├── icehello/
│   │   ├── iox-cpp-publisher-helloworld
│   │   └── iox-cpp-subscriber-helloworld
│   ├── waitset/
│   ├── request_response/
│   └── ...
├── iceoryx_integrationtest/        # 集成测试（如果启用 BUILD_TEST）
├── hoofs/                          # hoofs 库和测试
├── posh/                           # posh 库和测试
└── tools/
    └── introspection/              # 监控客户端（如果启用 INTROSPECTION）
        └── iox-introspection-client

库文件位置

build/
├── hoofs/
│   └── libiceoryx_hoofs.a          # 静态库
├── posh/
│   ├── libiceoryx_posh.a
│   ├── libiceoryx_posh_roudi.a
│   ├── libiceoryx_posh_gateway.a
│   └── libiceoryx_posh_config.a
└── iceoryx_binding_c/
    └── libiceoryx_binding_c.a

---

故障排查

问题1：找不到 ncurses

CMake Error: Could NOT find Curses (missing: CURSES_LIBRARY CURSES_INCLUDE_PATH)

解决方案：

# Ubuntu/Debian
sudo apt install libncurses5-dev

# RHEL/CentOS
sudo yum install ncurses-devel

# 或禁用 introspection
cmake -Bbuild -DINTROSPECTION=OFF

---

问题2：编译速度慢

解决方案：

# 1. 启用 ccache（默认已启用）
sudo apt install ccache

# 2. 使用 Ninja 替代 Make
cmake -Bbuild -GNinja
ninja -C build -j$(nproc)

# 3. 减少并行任务数（如果内存不足）
cmake --build build -j4  # 只用 4 个并行任务

---

问题3：链接错误

undefined reference to `symbol'

解决方案：

# 1. 清理并重新构建
rm -rf build
cmake -Bbuild -Hiceoryx_meta
cmake --build build

# 2. 确保链接正确的库
# 检查 CMakeLists.txt 中的 target_link_libraries

---

问题4：运行时找不到共享库

error while loading shared libraries: libiceoryx_posh.so: cannot open shared object file

解决方案：

# 1. 添加到 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/path/to/build/iceoryx_posh:$LD_LIBRARY_PATH

# 2. 或安装到系统路径
sudo cmake --build build --target install
sudo ldconfig

---

问题5：权限问题（共享内存）

[ Roudi ] Cannot create shared memory, permission denied

解决方案：

# 1. 清理旧的共享内存文件
rm -f /dev/shm/iceoryx_*

# 2. 检查权限
ls -la /dev/shm/

# 3. 确保用户在正确的组
groups  # 查看当前用户所属组

---

使用官方构建脚本

iceoryx 提供了官方构建脚本 tools/iceoryx_build_test.sh：

基本用法

# 显示帮助
./tools/iceoryx_build_test.sh --help

# Debug 构建 + 示例
./tools/iceoryx_build_test.sh debug examples

# Release 构建 + 测试
./tools/iceoryx_build_test.sh release test

# 所有功能
./tools/iceoryx_build_test.sh debug all

# 清理构建
./tools/iceoryx_build_test.sh clean

常用参数

参数	说明
debug	Debug 构建类型
release	Release 构建类型
examples	构建示例
test	构建并运行测试
all	构建所有组件
clean	清理构建目录
--introspection	启用 introspection
--strict	启用严格模式（-Werror）

---

推荐工作流

开发流程

# 1. 初始构建（包含示例和测试）
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Debug \
    -DEXAMPLES=ON \
    -DBUILD_TEST=ON \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

# 2. 构建
cmake --build build -j$(nproc)

# 3. 运行测试
./build/hoofs/test/hoofs_moduletests
./build/posh/test/posh_moduletests
./build/posh/test/posh_integrationtests

# 4. 开发和调试
# 修改代码后，只需重新运行：
cmake --build build -j$(nproc)

# 5. 运行特定测试
./build/hoofs/test/hoofs_moduletests --gtest_filter=*YourTest*
./build/posh/test/posh_moduletests --gtest_filter=*Specific*

CI/CD 流程

# 严格模式 + 完整测试
cmake -Bbuild -Hiceoryx_meta \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_STRICT=ON \
    -DBUILD_ALL=ON

cmake --build build -j$(nproc)

# 运行所有测试
./build/hoofs/test/hoofs_moduletests
./build/posh/test/posh_moduletests
./build/posh/test/posh_integrationtests
./build/binding_c/test/binding_c_moduletests
./build/binding_c/test/binding_c_integrationtests

---

参考资料

• 官方文档：https://iceoryx.io/latest/getting-started/
• 构建选项 ：iceoryx_meta/build_options.cmake
• 构建脚本 ：tools/iceoryx_build_test.sh
• 示例代码 ：iceoryx_examples/
• GitHub Issues：https://github.com/eclipse-iceoryx/iceoryx/issues

---

快速参考卡片

最常用的5种构建命令

# 1. 最小化构建
cmake -Bbuild -Hiceoryx_meta && cmake --build build

# 2. 带示例
cmake -Bbuild -Hiceoryx_meta -DEXAMPLES=ON && cmake --build build

# 3. 开发模式（示例+测试）
cmake -Bbuild -DEXAMPLES=ON -DBUILD_TEST=ON && cmake --build build

# 4. 完整构建
cmake -Bbuild -DBUILD_ALL=ON && cmake --build build

# 5. 生产环境
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build

---

提示：构建配置可以随时修改，CMake 会自动检测变化并只重新构建必要的部分。

最佳实践：

• 开发时使用 Debug + EXAMPLES + BUILD_TEST
• 发布时使用 Release + 静态链接
• CI/CD 使用 BUILD_STRICT + BUILD_ALL