<<MenuNavi(Menus/ROSFilesystemConcepts)>>

<<TOC(3)>>

{{{#!wiki yellow
For rosbuild, see: [[rosbuild/Packages]]
}}}

Software in ROS is organized in ''packages''. A package might contain ROS [[Nodes|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 [[catkin/commands/catkin_create_pkg|catkin_create_pkg]]. A ROS package is simply a directory descended from `ROS_PACKAGE_PATH` (see [[ROS/EnvironmentVariables|ROS Environment Variables]]) that has a [[Manifest|package.xml]] file in it. Packages are the most atomic unit of build and the unit of release. This means that a package is the smallest individual thing you can build in ROS and it is the way software is bundled for release (meaning, for example, there is one debian package for each ROS package), respectively.

Please see the [[catkin/package.xml]] section for documentation on how to read and write `package.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.

 * `include/package_name`: C++ include headers (make sure to export in the [[catkin/CMakeLists.txt#catkin_package.28.29|CMakeLists.txt]])
 * `msg/`: [[msg|Folder containing Message (msg) types]]
 * `src/package_name/`: Source files, especially Python source that are exported to other packages.
 * `srv/`: [[srv|Folder containing Service (srv) types]]
 * `scripts/`: executable scripts
 * `CMakeLists.txt`: CMake build file (see [[catkin/CMakeLists.txt]])
 * `package.xml`: Package [[catkin/package.xml]]
 * `CHANGELOG.rst`: Many packages will define a changelog which can be automatically injected into binary packaging and into the wiki page for the package

== 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
 * [[catkin/commands/catkin_create_pkg|catkin_create_pkg]]: create a new package
 * [[catkin/commands/catkin_make|catkin_make]]: build a workspace of packages
 * [[rosdep]]: install system dependencies of a package
 * [[rqt]]: In [[rqt]] there is a plugin called "Introspection/Package Graph", which 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, e.g.

{{{
roscd roscpp_tutorials
}}}

== Client Library Support ==

=== Python ===

In Python, you can use the `RosPack` class in the [[http://docs.ros.org/independent/api/rospkg/html/|rospkg]] library to get information about ROS packages. For example:

{{{#!python
import rospkg

# get an instance of RosPack with the default search paths
rospack = rospkg.RosPack()

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

# get the file path for rospy_tutorials
rospack.get_path('rospy_tutorials')
}}}

See more at [[http://docs.ros.org/independent/api/rospkg/html/genindex.html|rospkg API index]].

=== 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);
}}}