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,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 测试"