Package Fundamentals

A package serves as a container for organizing ROS 2 code. When distributing or sharing your software, code must be structured within packages. This organization enables others to easily build and utilize your ROS 2 projects.

ROS 2 packages utilize ament as their build system and colcon as the build tool. Packages can be created using either CMake or Python, which are officially supported approaches, though alternative methods exist.

Package Structure Requirements

Minimum file requirements differ between CMake and Python packages:

CMake Package Components:

• CMakeLists.txt: Build instructions for compiling source code
• include/<package_name>: Directory containing public header files
• package.xml: Metadata describing the package
• src: Directory containing source code files

Python Package Components:

• package.xml: Package metadata file
• resource/<package_name>: Marker file for the package
• setup.cfg: Configuration enabling ros2 run to locate executables
• setup.py: Installation instructions for the package
• /<package_name>: Directory matching the package name containing __init__.py, allowing ROS 2 tools to discover the package

Basic package directory structures:

CMake Package Layout:

my_package/
    CMakeLists.txt
    include/my_package/
    package.xml
    src/

Python Package Layout:

my_package/
    package.xml
    resource/my_package
    setup.cfg
    setup.py
    my_package/

Workspace Organization

A single workspace can accommodate multiple packages of various build types. Best practice involves creating an src directory within the workspace root to contain all packages, maintaining a clean workspace structure.

Example workspace layout:

workspace_directory/
    src/
        cpp_package_1/
            CMakeLists.txt
            include/cpp_package_1/
            package.xml
            src/

        py_package_1/
            package.xml
            resource/py_package_1
            setup.cfg
            setup.py
            py_package_1/
        ...
        cpp_package_n/
            CMakeLists.txt
            include/cpp_package_n/
            package.xml
            src/

Packages cannot be nested within other packages. Each package maintains its own separate directory structure regardless of build type.

Prerequisites

A functional ROS 2 workspace is required for package creation. Follow previous tutorial instructions to establish your development environment before proceeding with package development.