跳至主要内容

Workspace 與 Package

自訂的 ROS 2 Package 通常會在 colcon Workspace 中進行開發。本頁會建立後續 Publisher/Subscriber、Service 與 Action 以及 Parameter 與 Launch 實作範例所使用的 Workspace 與 Package。

概述​

Workspace 是一個具有特定目錄結構的資料夾，通常包含 src/，而在完成 Build 後還會產生 build/、install/ 與 log/。colcon — ROS 2 標準的 Build Tool — 會使用這種結構來管理編譯流程。

Package 則是位於 src/ 內的一個資料夾，並包含 package.xml Manifest，用來描述 Package 名稱、Dependency 與 Build Type。

ros2_ws/
├── src/
│   └── my_package/
│       ├── package.xml
│       ├── setup.py            # (Python package)
│       └── my_package/
│           └── my_node.py
├── build/     # generated by colcon build
├── install/   # generated by colcon build — this is what you source
└── log/       # generated by colcon build

為什麼重要​

許多 ROS 2 中的 "package not found" 或 "no executable found" 錯誤，通常都可以追溯到幾個常見原因：Workspace 沒有成功 Build、Workspace Overlay 沒有被 source，或 Executable 沒有正確安裝或註冊到 Package 中。

核心概念​

Workspace vs. Package vs. Install​

  • 一個 Workspace 可以包含許多 Package。
  • colcon build 會對 src/ 底下的 Package 進行編譯與安裝準備，並將結果放到 build/ 與 install/。
  • source install/setup.bash 後，這個 Workspace 會成為一個 Overlay，讓其中的 Package 可以在先前已載入的 ROS 2 Distribution Underlay 之上使用。可參考 CLI 基礎操作。

Build Types​

ROS 2 Package 常見的 Build Type 包括：

Build typeLanguageManifest hints
ament_pythonPythonsetup.py, setup.cfg, package.xml
ament_cmakeC++CMakeLists.txt, package.xml

本文件系列使用 ament_python，與本章其餘 Python 範例保持一致。

使用 rosdep 管理 Dependency​

Package 會在 package.xml 中宣告 Dependency，例如 <depend>rclpy</depend>。

rosdep 會讀取 src/ 下各個 Package 的 Dependency 宣告，並安裝對應的系統或 ROS Package：

# One-time setup (skip if already initialized on this machine/container)
sudo rosdep init
rosdep update

# Run from the workspace root, before building
rosdep install --from-paths src --ignore-src -r -y

-r 會讓 rosdep 在某個 Dependency 安裝發生錯誤時，繼續處理其他 Dependency，而不是立即停止；-y 則會略過互動式確認。

實作步驟​

1. 建立 Workspace​

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

2. 建立 Python Package​

cd ~/ros2_ws/src
ros2 pkg create --build-type ament_python --license Apache-2.0 my_ros2_tutorial \
  --dependencies rclpy std_msgs

執行後會產生：

my_ros2_tutorial/
├── package.xml
├── setup.py
├── setup.cfg
├── resource/
│   └── my_ros2_tutorial
├── test/
└── my_ros2_tutorial/
    └── __init__.py

Publisher/Subscriber 中的 Python 範例，會在 my_ros2_tutorial/my_ros2_tutorial/ 下加入 Node 檔案。

3. 解析 Dependency​

cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y

4. 使用 colcon Build​

cd ~/ros2_ws
colcon build --symlink-install

--symlink-install 會將 Python Package 檔案以 Symbolic Link 的方式放到 install/，而不是直接複製，因此一般 .py 原始碼修改通常不需要重新 Build 就能生效。

如果修改的是 Package Metadata、Dependency 或 console_scripts Entry Point，仍然需要重新 Build。

如果 Workspace 中有很多 Package，也可以只 Build 指定的 Package：

colcon build --packages-select my_ros2_tutorial

5. Source the Overlay​

source ~/ros2_ws/install/setup.bash

每一個需要執行該 Package 的新 Terminal 都要執行這個步驟。

可以使用以下指令確認是否成功：

ros2 pkg list | grep my_ros2_tutorial

預期成果​

colcon build 應該能在沒有錯誤的情況下完成，並顯示類似：

Summary: 1 package finished

source install/setup.bash 後：

ros2 pkg list | grep my_ros2_tutorial

應該會顯示該 Package 名稱。

常用指令​

# Build
colcon build                              # build every package in src/
colcon build --symlink-install            # symlink Python files (recommended while developing)
colcon build --packages-select <name>     # build one package only
colcon build --packages-up-to <name>      # build a package and its workspace dependencies

# Clean rebuild
rm -rf build/ install/ log/
colcon build

# Dependency management
rosdep install --from-paths src --ignore-src -r -y

# Inspecting packages
ros2 pkg list
ros2 pkg xml <package_name>               # print package.xml contents
ros2 pkg prefix <package_name>            # where it installed to

常見問題​

  • Package 'my_ros2_tutorial' not found — 目前這個 Terminal 尚未 source Overlay，或之前的 Build 沒有成功完成。重新執行 colcon build 並確認輸出內容，再次 source install/setup.bash。
  • 修改 Python Node 後沒有任何變化 — Workspace 可能不是使用 --symlink-install Build。重新 Build Package，或清除產生的目錄後，再使用 --symlink-install Build。
  • colcon: command not found — colcon 尚未安裝。在某些精簡 ROS 2 安裝中，colcon 是獨立工具。請依目前的 Distribution / OS 安裝 python3-colcon-common-extensions。
  • rosdep 顯示 unknown key — package.xml 中的 Dependency 名稱可能不符合已知的 rosdep key。請確認拼字是否正確，並確認最近已執行過 rosdep update。
  • Underlay / Overlay 混用造成問題 — 每一個新的 Terminal 都應先 source ROS 2 Distribution 的 Underlay，再 source Workspace Overlay，順序不要顛倒。可參考 CLI 基礎操作。

重點整理​

  • Workspace 可以在 src/ 下包含多個 Package；colcon build 會產生 build/、install/ 與 log/。
  • ros2 pkg create --build-type ament_python 可以建立一個包含正確 Manifest 與 Entry Point 結構的 Python Package。
  • rosdep install --from-paths src --ignore-src -r -y 會處理各個 Package 在 package.xml 中宣告的 Dependency。
  • 開發 Python Node 時使用 --symlink-install，可以避免每次修改原始碼後都重新 Build。
  • Build 完成後，所有需要使用該 Package 的 Terminal 都要 source install/setup.bash。

下一步​

接著前往 Publisher/Subscriber，在這裡建立的 my_ros2_tutorial Package 中加入第一組可以實際執行的 Node。