xiaoshuai/ROS2_learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init: ROS2 learning suite

Browse Source
This commit is contained in:
xs
2026-08-03 18:09:35 +08:00
commit 5ef38ab508
95 changed files with 13322 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/02-virtualenv.md
+277
View File
@@ -0,0 +1,277 @@
# 02 · 本机 venv 工作流(不污染系统 Python 完全指南)
> **目标**:用标准 Python venv 在 Windows / Linux / macOS 上做 ROS2 开发,**完全不污染系统 Python**。
---
## 目录
- [1. 为什么需要 venv](#1-为什么需要-venv)
- [2. 双轨制 — venv vs colcon](#2-双轨制--venv-vs-colcon)
- [3. 创建 venv(Win / Linux)](#3-创建-venvwin--linux)
- [4. venv 里装了什么](#4-venv-里装了什么)
- [5. IDE 配置](#5-ide-配置)
- [6. 在 venv 里能做什么 / 不能做什么](#6-在-venv-里能做什么--不能做什么)
- [7. 在容器里跑 ROS2 测试](#7-在容器里跑-ros2-测试)
- [8. 依赖锁文件](#8-依赖锁文件)
- [9. .venv 加进 .gitignore](#9-venv-加进-gitignore)
- [10. 故障排查](#10-故障排查)
- [11. 在本仓库里跑](#11-在本仓库里跑)
---
## 1. 为什么需要 venv
ROS2 的 Python 客户端库(`rclpy` / `sensor_msgs` / `tf2_ros` / `cv_bridge` 等)**只在 Linux 平台通过 apt 提供**,
Windows 上没有官方 pip wheels。
如果直接 `pip install` 到系统 Python:
- 失败(找不到 wheel)
- 或者和别的项目冲突(版本冲突)
- 或者哪天升级 Python 把 ROS 客户端搞挂了
**venv 的目的**:本机 Python 工具(ruff / black / pytest / mypy 等)放隔离环境,与 ROS2 运行解耦。
---
## 2. 双轨制 — venv vs colcon
| 工作 | 用什么 | 跑在哪 |
|---|---|---|
| 编辑代码、写测试 | **本机 venv + IDE** | Win/macOS/Linux |
| 跑 ROS2 节点 / colcon build / colcon test | **Docker 容器** | Linux |
| pytest (纯逻辑、不需要 ROS2) | 本机 venv | Win/macOS/Linux |
| pytest (需要 rclpy) | **Docker 容器** | Linux |
```
本机: venv (开发) Docker: colcon (运行)
───────────────── ────────────────────
ruff / black / mypy colcon build
pytest (纯逻辑) colcon test
IDE 跳转 ros2 run / launch
rclpy / sensor_msgs / tf2_ros
```
---
## 3. 创建 venv
### 3.1 Windows
```powershell
cd D:\xs\ros2
powershell .\tools\setup_venv.ps1
# 激活
.\.venv\Scripts\Activate.ps1
# 验证
python -c "import sys; print(sys.executable)"
# 期望: D:\xs\ros2\.venv\Scripts\python.exe (不是 C:\Program Files\Python310\python.exe)
```
### 3.2 Linux / macOS / WSL
```bash
cd /path/to/ros2
./tools/setup_venv.sh
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
# 期望: /path/to/ros2/.venv/bin/python
```
### 3.3 在 Docker 容器内
容器内系统 Python 已经隔离,venv 多此一举。直接用系统 Python 即可。
---
## 4. venv 里装了什么
`tools/setup_venv.{sh,ps1}` 会做:
1. `python -m venv .venv` — 创建虚拟环境
2. `pip install --upgrade pip setuptools wheel`
3. `pip install -r requirements-dev.txt` — 装开发工具:
- `ruff`(超快 linter,替代 flake8 + isort)
- `black`(格式化)
- `mypy`(类型检查)
- `pytest` + `pytest-cov` + `pytest-timeout`
- `pre-commit`(git hook,可选)
4. `pip install -e src/py_pubsub src/py_srv src/py_action_demo src/py_vision_demo`
把本项目 ROS2 Python 包装到 venv(**可编辑模式** — 改源码立即生效,不需要重装)
`--no-deps` 跳过 ROS 客户端依赖(因为 Windows 装不上)
---
## 5. IDE 配置
### 5.1 VSCode
`pyrightconfig.json` 已配置好,直接:
```json
{
"extraPaths": [
"/opt/ros/humble/lib/python3.10/site-packages" // 容器内
]
}
```
设置 VSCode 的 Python 解释器:`Ctrl+Shift+P` → "Python: Select Interpreter" → 选择 `.venv\Scripts\python.exe`
### 5.2 PyCharm
`Settings → Project → Python Interpreter → Add → Existing environment` → 选 `.venv\Scripts\python.exe`
### 5.3 看代码跳转
- 跳转到 `rclpy.Node` 定义:`Ctrl+点击` — pyright 会去 `/opt/ros/humble/lib/python3.10/site-packages` 找
- **容器外**:Windows 上 import rclpy 仍然飘红,但不影响阅读源码
- **容器内(开发容器)**:跳转正常,因为 `/opt/ros/...` 路径存在
---
## 6. 在 venv 里能做什么 / 不能做什么
| 能做 | 不能做 |
|---|---|
| 编辑 Python 源码,IDE 自动补全 | `import rclpy` (rclpy 没 Windows wheels) |
| 跑 ruff / black / mypy | 跑 ROS2 节点 / launch 文件 |
| 装纯 Python 包(numpy / torch / opencv-python) | 跑 ros2 CLI 命令 |
| 在容器内 venv(可访问 rclpy):跑纯 pytest | |
---
## 7. 在容器里跑 ROS2 测试
```bash
docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && cd /root/ros2_ws && colcon test --packages-select py_pubsub"
```
colcon test 会自动跑每个包的 `test/` 目录下的测试。本仓库:
- `py_*` 包 → pytest
- `cpp_*` 包 → ament_cmake_gtest(CTest)
- 期望全部 PASSED。
---
## 8. 依赖锁文件
生产环境建议加 `requirements.lock`(`pip freeze > requirements.lock`),精确锁版本。本仓库的
`requirements*.txt` 只列宽松版本(`>=`):
| 文件 | 用途 |
|---|---|
| `requirements.txt` | 运行时纯 Python 依赖(numpy / pytest) |
| `requirements-dev.txt` | 开发工具(ruff / black / mypy) |
---
## 9. .venv 加进 .gitignore
```gitignore
.venv/
```
已加。提交代码不会带 venv 目录。
---
## 10. 故障排查
### 10.1 `python: command not found`
- Windows:安装 Python 3.10+ 并勾选 "Add to PATH"
- Linux: `sudo apt install python3 python3-venv`
### 10.2 `venv` 模块找不到
```bash
# Debian/Ubuntu
sudo apt install python3-venv
# Fedora/RHEL
sudo dnf install python3-virtualenv
```
### 10.3 venv 里 `import rclpy` 仍然飘红
正常。rclpy 在 Windows 没有 pip wheels,需要靠 apt(在容器内)。开发时不影响阅读,
要跑 ROS2 测试就在容器里跑。
### 10.4 venv 占空间
通常 200-500 MB。删掉重建:`rm -rf .venv && tools/setup_venv.sh`。
### 10.5 激活 venv 后 pip 装不上
确认 `which python` / `which pip` 指向 `.venv/bin/`:
```bash
which python # /path/.venv/bin/python
which pip # /path/.venv/bin/pip
```
如果指向系统 Python,venv 没生效。
---
## 11. 在本仓库里跑
### 11.1 创建 venv
```powershell
cd D:\xs\ros2
powershell .\tools\setup_venv.ps1
```
输出:
```
==> Python: Python 3.10.x
==> Creating venv at .venv
==> Upgrading pip + installing requirements-dev.txt
OK py_pubsub
OK py_srv
OK py_action_demo
OK py_vision_demo
✅ venv ready. Activate with:
.\.venv\Scripts\Activate.ps1
```
### 11.2 激活 + 验证
```powershell
.\.venv\Scripts\Activate.ps1
python --version # Python 3.10.x (venv)
pip list # 已装的包
ruff check src/ # linter
mypy src/ # 类型检查(部分飘红是 rclpy 缺,忽略)
```
### 11.3 在 venv 里跑纯 Python 测试(不需要 ROS2)
```bash
# 比如写一个纯算法测试
pytest src/<pkg>/test/test_my_algorithm.py
```
### 11.4 完整工作流
```powershell
# 1. 本机开发:venv + IDE
cd D:\xs\ros2
.\.venv\Scripts\Activate.ps1
code . # VSCode 打开
# 2. 改完代码,跑容器测试
docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon build --packages-select <pkg>"
docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon test --packages-select <pkg>"
# 3. 跑 demo
docker exec ros2_dev bash -lc "source install/setup.bash && ros2 launch bringup <file>"
```
---
## 接下来读
| 主题 | 文档 |
|---|---|
| 项目总览 | [`00-overview.md`](00-overview.md) |
| 5 分钟上手 | [`01-quickstart.md`](01-quickstart.md) |
| 测试策略 | [`90-testing.md`](90-testing.md) |
| Docker | [`85-docker.md`](85-docker.md) |