ROS packages

Software in ROS is organized in packages. A package might contain a library, a dataset, configuration files or anything else that logically constitutes a useful module. The goal of these packages it to provide this functionality in an easy-to-consume manner so that software can be easily reused. In general, ROS packages follow a “Goldilocks” principle: enough functionality to be useful, but not too much that the package is heavyweight and difficult to use from other software.

Packages are easy to create by hand or with tools like roscreate-pkg. A ROS package is simply a directory descended from ROS_ROOT or ROS_PACKAGE_PATH that has a manifest.xml file in it. Packages may be organized together into ROS [[Stacks|stacks]].

Please see the package manifest files section for documentation on how to read and write manifest.xml files.

Common Files and Directories

ROS packages tend to follow a common structure. Here are some of the directories and files you may notice.

  • bin/: compiled binaries
  • include/package_name: C++ include headers (make sure to export in the package manifest)
  • src/package_name/: Source files, especially Python source that are exported to other packages.
  • scripts/: executable scripts
  • CMakeLists.txt: CMake build file (see CMakeLists)
  • manifest.xml: Package manifest

For C++ and Python developers, we strongly recommend that the package_name match namespaces/module names in your code so that it’s easy to locate what package provides your code.

Packages that are used with the ROS communication system may also have:

Command-line Tools

Packages are a very central concept to how files in ROS are organized, so there are quite a few tools in ROS that help you manage them. This includes:

  • rospack: find and retrieve information about packages. The ROS build system also uses rospack to locate a package and build its dependencies.
  • roscreate-pkg: create a new package.
  • rosmake: build a package and its dependencies.
  • rosdep: install system dependencies of a package.

There are also extensions to common Unix shells that provide additional functionality to help you navigate and use packages. The most commonly used of these is rosbash, which provides ROS-variants of common Unix shell commands for Bash and other shells. The most commonly used of these is roscd, which performs a cd to the directory of a package or stack, e.g.

roscd roscpp_tutorials