init: ROS2 learning suite

2026-08-03 18:09:35 +08:00
commit 5ef38ab508
95 changed files with 13322 additions and 0 deletions
@@ -0,0 +1,71 @@
+# =============================================================================
+# setup_venv.ps1 —— 在 Windows 上创建标准 Python venv,不污染系统 Python。
+#
+# 重要前提:
+#   - Windows 上 rclpy / sensor_msgs / cv_bridge 没有官方 pip wheels,
+#     所以 venv 里 *只能装纯 Python 工具*(ruff / black / mypy / pytest / numpy)。
+#   - 真正的 ROS2 节点必须在 Docker Desktop 容器内 / WSL Ubuntu 内运行。
+#   - 本机用 VSCode / PyCharm 等 IDE 时,把 interpreter 指向 .venv\Scripts\python.exe
+#     即可享受自动补全 / 类型检查,即使 rclpy 解析不了也没关系
+#     (pyrightconfig.json 已配置 ignore_missing_imports)。
+#
+# 使用:
+#   PS> .\tools\setup_venv.ps1
+#   PS> .\.venv\Scripts\Activate.ps1
+# =============================================================================
+
+$ErrorActionPreference = 'Stop'
+
+# 切到脚本所在目录的上一级(项目根)
+Set-Location -LiteralPath (Join-Path $PSScriptRoot '..')
+
+# 优先 python,找不到再 python3
+$PYTHON = $null
+foreach ($cand in @('python', 'python3', 'py')) {
+    $cmd = Get-Command $cand -ErrorAction SilentlyContinue
+    if ($cmd) { $PYTHON = $cand; break }
+}
+if (-not $PYTHON) {
+    throw 'Python not found in PATH. Install Python 3.10+ from python.org first.'
+}
+
+Write-Host "==> Using: $PYTHON" -ForegroundColor Cyan
+& $PYTHON --version
+
+$VENV_DIR = '.venv'
+
+# 1) 创建 venv(若已存在则提示并复用)
+if (-not (Test-Path -LiteralPath $VENV_DIR)) {
+    Write-Host "==> Creating venv at $VENV_DIR" -ForegroundColor Cyan
+    & $PYTHON -m venv $VENV_DIR
+} else {
+    Write-Host "==> Reusing existing venv at $VENV_DIR" -ForegroundColor Yellow
+}
+
+$venvPython = Join-Path $VENV_DIR 'Scripts\python.exe'
+if (-not (Test-Path -LiteralPath $venvPython)) {
+    throw "venv python.exe not found at $venvPython"
+}
+
+# 2) 升级 pip + 装开发依赖
+Write-Host "==> Upgrading pip + installing requirements-dev.txt" -ForegroundColor Cyan
+& $venvPython -m pip install --upgrade pip wheel setuptools
+& $venvPython -m pip install -r requirements-dev.txt
+
+# 3) pip install -e 把本项目 ROS2 Python 包装到 venv(纯 Python 部分,不动 ROS 客户端)
+Write-Host "==> Installing ROS2 Python packages (editable)" -ForegroundColor Cyan
+foreach ($pkg in @('py_pubsub','py_srv','py_action_demo','py_vision_demo')) {
+    $pkgDir = Join-Path 'src' $pkg
+    if (Test-Path -LiteralPath $pkgDir) {
+        & $venvPython -m pip install -e $pkgDir --no-deps
+        Write-Host "    OK $pkg" -ForegroundColor Green
+    }
+}
+
+Write-Host ''
+Write-Host 'venv ready. Activate with:' -ForegroundColor Green
+Write-Host '    .\.venv\Scripts\Activate.ps1' -ForegroundColor Green
+Write-Host ''
+Write-Host 'Next steps (Windows):' -ForegroundColor Yellow
+Write-Host '    pytest src/py_pubsub/test -m "not ros"   # 本机纯逻辑测试'
+Write-Host '    docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon test"   # 容器内 ROS2 测试'
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# =============================================================================
+# setup_venv.sh —— 在 Linux / macOS / WSL / Docker 容器内创建标准 Python venv,
+#                    不污染系统 Python。
+#
+# 流程:
+#   1) python3 -m venv .venv        —— 在项目根建一个 .venv 目录;
+#   2) source .venv/bin/activate    —— 激活 venv,后续 pip/python 都走 venv;
+#   3) pip install -r requirements-dev.txt —— 装开发工具(ruff/black/mypy/pytest);
+#   4) pip install -e <每个 ROS2 Python 包> —— 把本项目 Python 包装到 venv (editable);
+#   5) 若 ROS2 客户端库已通过 apt 装(ros-humble-desktop),把 /opt/ros/humble/lib/python3.10/site-packages
+#      加进 PYTHONPATH,使 venv 里也能 import rclpy / sensor_msgs 等。
+#
+# 注意:Windows 没有 rclpy wheels,所以在 Windows 上跑这脚本只能装"开发工具 + numpy",
+#        ROS2 节点必须在 Docker / WSL 内执行。
+# =============================================================================
+
+set -euo pipefail
+cd "$(dirname "$0")/.."   # 切到项目根(脚本在 tools/)
+
+PYTHON="${PYTHON:-python3}"
+VENV_DIR=".venv"
+
+echo "==> Python: $($PYTHON --version) at $($PYTHON -c 'import sys; print(sys.executable)')"
+
+# 1) venv
+if [ ! -d "$VENV_DIR" ]; then
+    echo "==> Creating venv at $VENV_DIR"
+    $PYTHON -m venv "$VENV_DIR"
+else
+    echo "==> Reusing existing venv at $VENV_DIR"
+fi
+
+# 2) 激活 venv(本 shell 子进程里)
+# shellcheck disable=SC1091
+source "$VENV_DIR/bin/activate"
+
+echo "==> venv Python: $(python --version) at $(which python)"
+
+# 3) 升级 pip + 装开发依赖
+echo "==> Upgrading pip + installing requirements-dev.txt"
+python -m pip install --upgrade pip wheel setuptools
+python -m pip install -r requirements-dev.txt
+
+# 4) pip install -e 把本项目 ROS2 Python 包装到 venv(可编辑模式)
+echo "==> Installing ROS2 Python packages (editable)"
+for pkg in py_pubsub py_srv py_action_demo py_vision_demo; do
+    if [ -d "src/$pkg" ]; then
+        python -m pip install -e "src/$pkg" --no-deps
+        echo "    OK $pkg"
+    fi
+done
+
+# 5) 若 /opt/ros/humble 存在,自动把 site-packages 注入 venv
+ROS_PYTHON_SITE="/opt/ros/humble/lib/python3.10/site-packages"
+if [ -d "$ROS_PYTHON_SITE" ]; then
+    echo "==> ROS2 detected at /opt/ros/humble. To import rclpy inside venv, run:"
+    echo "    export PYTHONPATH=\"$ROS_PYTHON_SITE:\${PYTHONPATH:-}\""
+    echo "    (this script does NOT mutate the system; do it manually when you need it)"
+fi
+
+echo
+echo "✅ venv ready. Activate with:"
+echo "    source $VENV_DIR/bin/activate"
+echo
+echo "Next steps:"
+echo "    pytest src/py_pubsub/test -m 'not ros'        # 本机纯逻辑测试"
+echo "    docker exec ros2_dev bash -lc 'cd /root/ros2_ws && colcon test'  # 容器内 ROS2 测试"