Understanding ROS Packages: A Comprehensive Guide

ROS (Robot Operating System) packages are the fundamental building blocks of ROS-based robotics software. This guide will explain what ROS packages are, their purpose, structure, and how to work with them effectively.

What is a ROS Package and Why Do We Need It?

1. Minimal Distribution Unit

• In ROS, all distributable, reusable, compilable, and runnable code is packaged into Packages
• GitHub repositories commonly contain one or multiple Packages

2. Dependency and Build Manager

• Each package declares its dependencies on other packages, system libraries, and toolchains
• Build systems (catkin for ROS 1 / ament for ROS 2) automatically resolve these dependencies and set compilation parameters

3. Namespace Management

• Topics, services, actions, parameters, and executables are logically organized through package names to prevent conflicts

4. Distribution and Installation

• ROS binary repositories (apt, yum, pacman, etc.) and source installation scripts are packaged and distributed by Package
• rosdep automatically installs system-level dependencies based on package.xml

What’s Inside a Typical Package?

The following example shows a ROS 1 (catkin) structure. ROS 2 (ament) structure is similar, with main differences in package.xml format being stricter and build instructions written differently in CMakeLists.txt.

my_robot_package/
├── CMakeLists.txt          # Build script: compilation options, dependencies, target executables
├── package.xml             # Metadata: package name, version, dependencies, license, maintainer
├── include/                # Header files for other packages to #include
│   └── my_robot_package/
├── src/                    # C/C++ source code, compiled into executables or libraries
│   └── main.cpp
├── scripts/                # Python / Bash scripts, requires chmod +x
│   └── talker.py
├── launch/                 # *.launch or *.py (ROS2) files, one-click startup of multiple nodes
│   └── demo.launch
├── config/                 # YAML or .rviz / .yaml parameter configurations
│   └── joystick.yaml
├── msg/                    # Custom messages *.msg
│   └── WheelVel.msg
├── srv/                    # Custom services *.srv
│   └── SetSpeed.srv
├── action/                 # Custom actions *.action
│   └── Navigate.action
├── urdf/                   # Robot models *.urdf, *.xacro
│   └── my_robot.urdf.xacro
├── rviz/                   # RViz configurations, Marker resources
├── meshes/                 # STL/DAE visual and collision models
└── README.md               # Documentation

Directory/File Responsibilities

1. package.xml

• Specify dependencies: build_depend, exec_depend, test_depend
• Metadata: version, author, license, description
• ROS 2: also carries export interfaces (e.g., ament_cmake, pluginlib_export_plugin_description_file)

2. CMakeLists.txt

• Call: find_package(catkin REQUIRED COMPONENTS roscpp std_msgs …)
• Specify compilation targets: add_executable() / ament_target_dependencies()
• Installation paths: install() for rosrun/ros2 run and system package management

3. src/ and include/

• C++/C nodes and library implementations; headers in include for easy reference by other packages

4. scripts/

• Python nodes and helper scripts; ROS 1 uses #!/usr/bin/env python; ROS 2 emphasizes entry points

5. launch/

• Describe how the entire system runs: nodes, parameters, namespaces, remapping, machine distribution

6. msg/srv/action

• Custom communication interfaces; automatically generate source code in corresponding languages during catkin_make or colcon build

7. config/

• Static parameter files; loaded using <rosparam file= or ROS 2 param file=

8. urdf/, meshes/, rviz/

• Robot models and visualization resources

ROS 1 vs ROS 2 Package Differences

1. Build System

• ROS 1: catkin (CMake-based)
• ROS 2: ament (modified CMake + Python); but directory structure differences are minimal

2. Launch Files

• ROS 1: “*.launch” XML
• ROS 2: adds Python launch with enhanced functionality

3. Security and Cross-Platform

• ROS 2 packages automatically adapt to DDS middleware, security encryption, real-time parameter declarations, and other new features

Common Development Workflow

1. Create Package

# ROS1
catkin_create_pkg my_package roscpp rospy std_msgs

# ROS2
ros2 pkg create --build-type ament_cmake my_package --dependencies rclcpp std_msgs

2. Write Code → Compile

catkin_make         # or colcon build
source devel/setup.bash

3. Run

rosrun my_package talker
roslaunch my_package demo.launch

Best Practices

Package Naming

• Use lowercase with underscores: my_robot_package
• Be descriptive but concise
• Avoid special characters

Dependency Management

• Only declare necessary dependencies
• Use appropriate dependency types (build, exec, test)
• Keep dependencies up to date

Documentation

• Always include a README.md
• Document installation and usage
• Provide examples and tutorials

Version Control

• Use semantic versioning
• Tag releases appropriately
• Maintain a changelog

Summary

ROS Packages provide a “minimal reusable unit” packaging method, making robot software modular like LEGO blocks. A package typically contains: metadata (package.xml), build scripts (CMakeLists.txt), source code, scripts, launch files, parameters, models, and custom messages. Understanding package structure and dependency declaration is the foundation for ROS development and distribution.

ROS packages are the cornerstone of modular robotics development, enabling code reuse, easy distribution, and systematic dependency management in the robotics ecosystem.