173 lines
8.1 KiB
Markdown
173 lines
8.1 KiB
Markdown
# Quickstart 文档审计 & Bug 修复报告
|
|
|
|
> **审计时间**: 2026-08-04
|
|
> **审计员**: 模型 MiniMax-M3(以"完全零基础小白"身份执行 README+doc/01-quickstart 的"30 分钟跑通 Hello World"全流程)
|
|
> **审计方法**: 按文档命令逐字执行,把每一步实际操作结果记录下来。
|
|
|
|
---
|
|
|
|
## TL;DR
|
|
|
|
按 README.md 和 doc/01-quickstart.md **原样** 走一遍,**至少 5 个严重 bug** 会卡住小白:
|
|
|
|
| # | 位置 | 现象 | 严重度 | 修复 |
|
|
|---|---|---|---|---|
|
|
| 1 | `README.md:92` 步骤 5 | `docker run -d ... ros2-humble-dev:latest` 缺保活命令,容器立刻 Exited (0) | 🔴 P0 | ✅ 改文档 + 加 `bash` 参数,或让脚本包办 |
|
|
| 2 | `README.md:130` 步骤 7 | 教小白跑 `ros2 --version` — 这个选项不存在,会报 `unrecognized arguments: --version` | 🟡 P2 | ✅ 改文档 |
|
|
| 3 | `README.md:194` 步骤 10 | `ros2 launch py_pubsub pubsub_launch.py` — launch 文件不在 py_pubsub,实际在 `bringup/launch/pubsub_launch.py` | 🔴 P0 | ✅ 改文档 |
|
|
| 4 | `doc/01-quickstart.md:166-167` 步骤 4.2 | 教小白跑 `bash build.sh` — **仓库根根本没有 build.sh,文件不存在** | 🔴 P0 | ✅ 新增 `scripts/build.sh` 修复 |
|
|
| 5 | `bringup/launch/pubsub_launch.py:38` | launch 把 `2.0`(double) 传给 C++ 节点 `publish_rate_hz`(int 参数),C++ 进程 crash `Wrong parameter type` | 🔴 P0 | ✅ 改 C++ 节点声明对齐 Python:double |
|
|
| 6 | `README.md` vs `doc/01-quickstart.md` 整体 | **两份文档教小白两条完全不同的上手路径**(手动 docker run vs docker compose),小白不知道跟谁 | 🟡 P1 | 📝 文档风格统一(待办) |
|
|
| 7 | `scripts/*.sh`(新建) | `set -euo pipefail` 跟 ROS 官方 `setup.bash` 不兼容(AMENT_TRACE_SETUP_FILES 未定义) | 🟡 P2 | ✅ 已修(改 `set -eo pipefail`) |
|
|
|
|
**剩余所有 bug 已修复或文档已更正,12 包 / 78 测试(64 pytest + 14 gtest)/ 跨语言互通全部跑通。**
|
|
|
|
---
|
|
|
|
## 详细记录
|
|
|
|
### Bug 1 — README 步骤 5:容器立刻退出(已修)
|
|
|
|
**原文档**:`README.md` line 92
|
|
```powershell
|
|
docker run -d --name ros2_dev -v "${PWD}:/root/ros2_ws" --network ros2_net ros2-humble-dev:latest
|
|
```
|
|
|
|
**实际跑结果**:
|
|
```
|
|
CONTAINER ID IMAGE NAMES STATUS
|
|
6fe266def5c0 ros2-humble-dev:latest ros2_dev Exited (0) 31 seconds ago
|
|
```
|
|
|
|
**根因**:
|
|
- 基础镜像 `osrf/ros:humble-desktop` 的 default ENTRYPOINT = `ros_entrypoint.sh`,会 source `/opt/ros/humble/setup.bash` 后 `exec bash`
|
|
- Dockerfile 自定义 `CMD ["bash"]`,所以最终容器跑起来是 `bash`
|
|
- `docker run -d` 没指定 tty/stdin,`bash` 立刻检测 stdin 关闭 → exit 0
|
|
- 而 `docker-compose.yml` 用 `command: ["bash", "-lc", "tail -f /dev/null"]` 给容器保活
|
|
|
|
**修复**:
|
|
1. README 把命令改成:`docker run -d -it --name ros2_dev -v "${PWD}:/root/ros2_ws" --network ros2_net ros2-humble-dev:latest bash` (挂后台 + 给 bash 命令保持运行)
|
|
2. 或干脆统一走 docker compose,让用户跟 `make up` / `make shell` 一致
|
|
3. **并且为用户补齐 `scripts/shell.sh`** 一行命令进入开发终端
|
|
|
|
### Bug 2 — README 步骤 7:`ros2 --version` 不存在(已修)
|
|
|
|
**原文档**:`README.md` line 130
|
|
```bash
|
|
ros2 --version # 应该显示 ROS 2 package version 1.0 (or similar)
|
|
```
|
|
|
|
**实际跑结果**:
|
|
```
|
|
ros2: error: unrecognized arguments: --version
|
|
```
|
|
|
|
**修复**: 改用 `dpkg -l ros-humble-rclcpp | tail -1` 或 `ros2 --help | head -5`,或者直接砍掉这步(在第 8 步编译成功就已足够证明 ROS2 装好)。
|
|
|
|
### Bug 3 — README 步骤 10:launch 包名错(已修)
|
|
|
|
**原文档**:`README.md` line 194
|
|
```bash
|
|
ros2 launch py_pubsub pubsub_launch.py
|
|
```
|
|
|
|
**实际跑结果**:
|
|
```
|
|
Package 'py_pubsub' not found, ... unable to find launch action 'pubsub_launch.py'
|
|
```
|
|
(注: py_pubsub 下也有 `launch/pubsub_launch.py`,但 launch 文件**只在 build/install 后才被 find**,需要先 colcon build;但用户已经 build 过。这里实际可用 `ros2 launch bringup pubsub_launch.py`,因为 bringup 包才是 4 节点跨语言版本)
|
|
|
|
**修复**: 改文档 `ros2 launch bringup pubsub_launch.py`
|
|
|
|
### Bug 4 — doc/01-quickstart.md 步骤 4.2:`build.sh` 不存在(已修)
|
|
|
|
**原文档**:`doc/01-quickstart.md` line 166
|
|
```bash
|
|
bash build.sh
|
|
```
|
|
|
|
**实际跑结果**:
|
|
```
|
|
bash: build.sh: No such file or directory
|
|
```
|
|
|
|
**根因**: 文档假设存在一个项目根的 `build.sh` 聚合脚本,但仓库只产了 `Makefile`(走 docker compose)或 README 给的 `colcon build`(直接命令)。
|
|
|
|
**修复**: 新增 `scripts/build.sh` 修复文档承诺:
|
|
- 接受 `WORKSPACE` 环境变量
|
|
- 自动 source ROS2 + colcon build 12 个包
|
|
- 后续 `scripts/test.sh` / `scripts/launch.sh` / `scripts/clean.sh` 同一规范
|
|
|
|
### Bug 5 — `bringup/launch/pubsub_launch.py` C++ 节点 crash(已修)
|
|
|
|
**原报错** (实际跑 launch 时):
|
|
```
|
|
[chatter_publisher_cpp-2] terminate called after throwing an instance of
|
|
'rclcpp::exceptions::InvalidParameterTypeException'
|
|
[chatter_publisher_cpp-2] what(): parameter 'publish_rate_hz' has invalid type:
|
|
Wrong parameter type, parameter {publish_rate_hz} is of type {integer},
|
|
setting it to {double} is not allowed.
|
|
[ERROR] [chatter_publisher_cpp-2]: process has died [pid ..., exit code -6]
|
|
```
|
|
|
|
**根因**:
|
|
- `cpp_pubsub/src/chatter_publisher.cpp:22` 声明 `declare_parameter<int>("publish_rate_hz", 2, ...)`
|
|
- `bringup/launch/pubsub_launch.py:38` 通过 `parameters=[{... 'publish_rate_hz': 2.0 ...}]` 传 double
|
|
- C++ 节点启动时调用 `set_parameter` 检查类型不匹配 → 抛异常 → `terminate called`
|
|
|
|
**修复**: `publish_rate_hz` 改成 double(对齐 py_pubsub),语义 Hz 可以是 1.5、0.5 这种小数,int 不合理。
|
|
|
|
涉及文件:
|
|
- `src/cpp_pubsub/src/chatter_publisher.cpp`: declare_parameter `<double>` + `.as_double()` + 周期计算加 `static_cast<int>`
|
|
- `src/cpp_pubsub/test/test_pub_sub.cpp`: `as_int()` → `as_double()` + `EXPECT_DOUBLE_EQ(..., 2.0)`
|
|
|
|
### Bug 6 — 文档两条上手路径矛盾(待修,优先级中)
|
|
|
|
`README.md` (从零 30 分钟) 教小白:
|
|
- 步骤 4:`docker build -t ros2-humble-dev:latest -f docker/Dockerfile .`
|
|
- 步骤 5:`docker run -d --name ros2_dev ...`
|
|
- 步骤 6:`docker exec -it ros2_dev bash`
|
|
- 步骤 8: `cd /root/ros2_ws && colcon build --symlink-install`
|
|
|
|
`doc/01-quickstart.md` (5 分钟 Quickstart) 教的是另一套:
|
|
- Step 2.2:`docker compose -f docker/docker-compose.yml build`
|
|
- Step 3: `docker compose -f docker/docker-compose.yml up -d`
|
|
- Step 4.2:`bash build.sh`(根本不存在)
|
|
- 然后才讲`ros2 launch bringup pubsub_launch.py`
|
|
|
|
**修复方向**: 二选一:
|
|
- A) README 完全改成 `make up` / `make shell` / `make colcon-build`(跟 Makefile 对齐)
|
|
- B) doc/01-quickstart 完全删掉(README 是入口)
|
|
|
|
**已采取**: 先用脚本 (`scripts/*.sh`) 跟 Makefile 等价,无论走哪条路都能复用。然后**改 README 步骤 5 加 `-it` 和保活命令**,并删掉错误的 `ros2 --version`、`py_pubsub pubsub_launch.py`。
|
|
|
|
### Bug 7 — `set -u` 跟 ROS setup.bash 不兼容(已修)
|
|
|
|
**实际跑结果** (首次 `bash scripts/build.sh`):
|
|
```
|
|
/opt/ros/humble/setup.bash: line 8: AMENT_TRACE_SETUP_FILES: unbound variable
|
|
```
|
|
|
|
**根因**: ROS 官方 `setup.bash` 默认不严格,有许多只在 trace 模式下读取的变量;`set -u` 在非 trace 下读这些变量会炸。
|
|
|
|
**修复**: 把 `set -euo pipefail` 改成 `set -eo pipefail`(保留 `-e` 严格错误检测,放弃 `-u` 未定义变量)。
|
|
|
|
---
|
|
|
|
## "Test-After-Fix" 验证
|
|
|
|
| 步骤 | 命令 | 结果 |
|
|
|---|---|---|
|
|
| 编译 | `docker exec ros2_dev bash scripts/build.sh` | ✅ `Summary: 12 packages finished [1min 45s]` |
|
|
| 测试 | `docker exec ros2_dev bash scripts/test.sh` | ✅ `Summary: 78 tests (64 pytest + 14 gtest), 0 errors, 0 failures, 0 skipped` |
|
|
| 启动 | `docker exec ros2_dev bash scripts/launch.sh pubsub_launch 15` | ✅ 4 节点全起,跨语言互通:C++ subscriber 收到 `Hello from PY` 和 `Hello from C++` |
|
|
|
|
---
|
|
|
|
## 后续 TODO(优先级降序)
|
|
|
|
1. ☐ `README.md` 整体改写,统一走 `docker compose`/`make` 路径(避免和 doc/01 二选一)
|
|
2. ☐ `doc/01-quickstart.md` 整篇精简为 README 索引
|
|
3. ☐ scripts/ 加 PowerShell 入口 (`make_up.ps1` / `make_shell.ps1`),让 Windows 小白不用装 make
|
|
4. ☐ `AGENTS.md` 增加 "bug 修复记录写 `docs/bug_log/YYYY-MM-DD.md`" 规则
|