Software in ROS is organized in packages. A package might contain ROS nodes, a ROS-independent library, a dataset, configuration files, a third-party piece of software, or anything else that logically constitutes a useful module. The goal of these packages it to provide this useful 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 (see ROS Environment Variables) that has a manifest.xml file in it. Packages may be organized together into ROS stacks.

Please see the Manifest 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 Manifest)

• msg/: Message (msg) types

• src/package_name/: Source files, especially Python source that are exported to other packages.

• srv/: Service (srv) types

• scripts/: executable scripts

• CMakeLists.txt: CMake build file (see CMakeLists)

• manifest.xml: Package Manifest

• mainpage.dox: many packages will often place their Doxygen mainpage documentation here

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 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.

• rxdeps: visualizes package dependencies as a graph.

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. 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

Client Library Support

Python

In Python, you can use the roslib.packages module in the roslib package to get information about ROS packages. For example:

import roslib.packages

# list all packages, equivalent to rospack list
roslib.packages.list_pkgs() 

# get the file path for rospy_tutorials
roslib.packages.get_pkg_dir('rospy_tutorials')

# get the file path for rospy_tutorials/talker.py
roslib.packages.find_node('rospy_tutorials', 'talker.py') 

C++

In C++, you can use ros::package in the roslib package to get information about ROS packages. For example:

#include <ros/package.h>

...

  std::string path = ros::package::getPath("roslib");
  using package::V_string;
  V_string packages;
  ros::package::getAll(packages);