ROS Package

The package.xml file is the mandatory metadata file that defines the package's identity and dependencies. It is an XML file that must be present in the root of every package.

• Declares package properties: Name, version, description, maintainer, and license.
• Specifies dependencies: Categorizes required packages as build dependencies (needed at compile time), execution dependencies (needed at runtime), test dependencies, and build tool dependencies.
• Enables tooling: The ROS build system (catkin, colcon) and package managers (rosdep) read this file to resolve and install dependencies automatically.

Example essential tags:

xmlCopy
<package format="3">
  <name>my_robot_driver</name>
  <version>1.0.0</version>
  <description>A driver for my custom robot.</description>
  <maintainer email="[email protected]">Jane Developer</maintainer>
  <license>Apache 2.0</license>
  <depend>roscpp</depend>
  <depend>sensor_msgs</depend>
</package>

The CMakeLists.txt file is the build instruction manual for C++ (or mixed-language) packages. It uses the CMake build system, extended with ROS-specific macros, to define how the package's executables and libraries are compiled and linked.

• Finds dependencies: Uses find_package() to locate other ROS packages and system libraries.
• Declares build targets: Defines executables (nodes) and libraries with add_executable() and add_library().
• Links dependencies: Specifies link libraries and include directories with target_link_libraries() and include_directories().
• Installs artifacts: Uses install() commands to specify where built binaries, libraries, and launch files should be placed for system-wide use.
• ROS Macros: Utilizes convenience macros like ament_package() (ROS 2) or catkin_package() (ROS 1) to finalize package configuration.

A pure Python package may omit this file, relying solely on package.xml and a setup.py or setup.cfg.

These directories contain the package's core logic. Their structure follows standard software conventions.

• src/ (source): Contains the .cpp source files for C++ nodes and libraries. For Python packages, this often contains a Python module directory (e.g., src/my_package/).
• include/<package_name>/ (headers): Contains the .h or .hpp header files for C++ libraries. The subdirectory named after the package prevents header filename collisions across the system.

Example Node: A simple publisher node might be located at src/talker.cpp. Its corresponding header, if part of a library, would be in include/my_package/talker.hpp.

This separation enforces clean interfaces and allows other packages to include this package's headers correctly using the #include <my_package/talker.hpp> syntax.

These directories hold files that configure and orchestrate the system at runtime, separating configuration from core logic.

• launch/: Contains launch files (.launch.py in ROS 2, .launch or .launch.py in ROS 1). These files are scripts that:
  • Start multiple nodes simultaneously.
  • Set ROS parameters.
  • Remap topic names.
  • Define node namespaces.
  • Group nodes into composable containers (ROS 2).
• config/ (or params/): Contains YAML configuration files used to set node parameters. This allows parameters (e.g., controller gains, sensor settings) to be easily modified without recompiling code.

Key Benefit: This structure enables reproducible system bring-up. A complex robot can be started with a single command like ros2 launch my_robot_bringup robot.launch.py, which references launch and config files from multiple packages.

These optional directories define custom communication interfaces, making the package's APIs explicit and reusable.

• msg/: Contains .msg files that define the structure of custom messages published on topics.
  • Example Pose2D.msg: float64 x\nfloat64 y\nfloat64 theta
• srv/: Contains .srv files that define the request and response structures for custom services.
  • Example AddTwoInts.srv: int64 a\nint64 b\n---\nint64 sum
• action/: Contains .action files that define the goal, feedback, and result structures for custom long-running actions (ROS 1 & 2).
  • Example NavigateToPose.action: geometry_msgs/PoseStamped goal_pose\n---\ngeometry_msgs/PoseStamped result\n---\ngeometry_msgs/PoseStamped feedback

Build Process: During compilation, the ROS build system automatically generates language-specific code (C++, Python, etc.) from these definition files, creating the classes and functions used to send and receive this data.

These directories support package quality, verification, and usability.

• test/: Contains unit, integration, and system tests.
  • C++ Tests: Use the Google Test (gtest) framework, integrated via CMake's catkin_add_gtest() or ament_add_gtest().
  • Python Tests: Use the pytest framework.
  • Launch Tests: Test the correct startup and interaction of nodes using ROS launch testing frameworks.
  • Running colcon test from the workspace root executes all package tests.
• doc/ or package.xml tags: While a doc/ folder can hold manual documentation, the primary documentation mechanism is the <export> tag in package.xml, which can point to a URI for online API documentation (e.g., hosted by Doxygen or Sphinx).

Importance: A well-tested package with clear documentation is essential for integration into larger, reliable robotic systems and for use by other developers in the community.

The package.xml file is the metadata declaration for a ROS package. It is an XML file located at the package root that defines:

• Dependencies on other ROS packages (build, build_export, exec, test).
• Metadata like the package name, version, description, maintainer, and license.
• Export information, such as build tool flags and message dependencies. This file is critical for the build system (colcon) to resolve dependencies and for the ROS tooling to understand the package's identity and requirements.

For C++-based packages, the CMakeLists.txt file is the build instruction script. It uses the ROS-provided CMake macros to:

• Declare the project and find required ROS 2 packages (find_package).
• Define message, service, and action interfaces.
• Specify libraries and executables to build (ament_target_dependencies).
• Install targets to the appropriate locations (install). It works in tandem with package.xml, where dependencies are declared in the manifest and then located in the CMake file for the build process.

A workspace is a directory (typically named src) where you clone or create multiple ROS packages. It is the top-level environment for development. The standard workflow involves:

• Source Space: The src/ directory containing all package source code.
• Build System: Using colcon build from the workspace root to compile all packages, respecting their inter-dependencies.
• Install & Overlay: The build process creates install/, build/, and log/ directories. Sourcing the install/setup.bash file overlays these built packages into your ROS environment, making them discoverable.

Colcon is the canonical build tool for ROS 2, succeeding catkin_make. It orchestrates the build process for a workspace containing multiple packages by:

• Dependency Analysis: Parsing package.xml files to determine a build order.
• Parallel Building: Compiling independent packages in parallel for speed.
• Isolated Builds: By default, building each package in its own isolated environment to prevent cross-contamination.
• Unified Interface: Invoking the underlying build system (CMake, Python setuptools) for each package type. Common commands are colcon build, colcon test, and colcon list.

ROS 2 packages are formally Ament packages, adhering to the Ament build system specifications. The primary types are:

• CMake (ament_cmake): For C/C++ packages, using CMakeLists.txt.
• Python (ament_python): For pure Python packages, using setup.py and setup.cfg.
• Hybrid: A package can contain both CMake and Python components. The Ament infrastructure provides the common tooling for building, testing, and installing these packages, ensuring consistency across the ROS 2 ecosystem.

A metapackage is a specialized, virtual ROS package used to group related packages for easier distribution and installation. Its key characteristics are:

• No Code: It contains no libraries, nodes, or significant source code of its own.
• Grouping Function: Its package.xml file declares run dependencies (exec_depend) on a set of other packages.
• Common Use Case: Used to install all packages for a specific robot or application suite with a single command (e.g., ros-humble-desktop is a metapackage). It serves as an organizational convenience layer on top of the standard package structure.