Organizing Files and Folders Inside a ROS 2 Package

packages-with-bows

In a ROS 2 project, code is organized into packages. A package is just a directory that contains files and folders. Each package might contain a mixture of code (e.g. ROS 2 nodes), data, libraries, images, documentation, etc. Every program you write in ROS 2 will need to be inside a package.

Suppose we have a ROS 2 package named my_robot_package. The file tree below shows a possible structure for a ROS 2 package. This structure is aligned with best practice for a ROS 2 package. I made a few tweaks (e.g. added rviz and maps folders). Note: You do not need to create all these folders in every ROS 2 package.

my_robot_package/

├── README (Describes the package*. Example)

├── CHANGELOG.rst (REP-0132 compliant changelog. Example.)

├── CONTRIBUTING (Describes the contribution guidelines. Example.)

├── LICENSE (A copy of the license or licenses for this package. Usually Apache 2.0. Example.)

├── setup.py (Where to install the Python modules. Python-only packages. Example.)

├── CMakeLists.txt (How to build the code and where to install. Packages with C++ code. Example.)

├── package.xml (Defines the package properties as defined by this convention. Example.)

├── action (Holds custom action definitions. Example.)

├── config (Holds configuration files … i.e. yaml. Example.)

├── doc (Holds all the documentation. Example.)

├── launch (Holds launch files. Example.)

├── maps (Holds map files. Example.)

├── models (Holds SDF model files. Example.)

├── msg (Holds custom message definitions. Example.)

├── rviz (Holds RViz configuration files. Example.)

├── srv (Holds custom service definitions. Example.)

├── test (All system (btw packages), integration (btw code), and/or unit (w/n code) test data. Example.)

├── urdf (Contains URDF files. Example.)

├── worlds (Contains Gazebo world files. Example.)

├── my_robot_package (Holds Python files that can be imported into other Python files. Example.)

│     ├── __init__.py

│     └── python_module_to_import.py

├── scripts (Holds Python code.**. Example.)

│     └── py_node.py

├── include (Holds C++ header files and libraries we want to use inside this package. Example.)

│     └── my_robot_package

│               └── cpp_header.hpp

└── src (Holds C++ source code.***. Example.)

        └── cpp_node.cpp

* All packages should have these documentation elements present in their README or linked to from their README:

  • Description and purpose
  • Definition and description of the public API
  • Examples
  • How to build and install (should reference external tools/workflows)
  • How to build and run tests
  • How to build documentation
  • How to develop (useful for describing things like python setup.py develop)
  • License and copyright statements

** Check this page for best practices on code style and language versions for C++, Python, and README files.

*** Each source file must have a license and copyright statement, checked with an automated linter.