Install prefix

For clarity, the install prefix is referred to as /opt/ros/<distro>. The install prefix does not have to follow this exact pattern, but it is the convention for ROS binary distributions.

This layout is also intended to enable installations within the standard /usr hierarchy.

Directory layout

The layout within the install prefix is:

bin/
etc/
include/
lib/
share/
stacks/

This generally follows FHS conventions, with the addition of the stacks directory for backwards compatibility with rosmake packages. The install also contains setup files to easily configure environment variables for this prefix.

These subdirectories are described in greater detail below.

bin/

bin is used to store top-level executables, i.e. executables that should be included in every ROS user's PATH. This replaces the old ROS_ROOT/bin location that stored core ROS binaries, like rostopic and rospack.

ROS packages that are converted to use this new layout may install into bin, but should do so sparingly as it is included in the user's PATH. Developers should also beware of name collisions in thise executables. In general, try to name executables so that their origin is obvious, perhaps using the ROS package name.

In the case of a special install prefix, PATH must include this location, e.g.:

PATH=/opt/ros/<distro>/bin:$PATH

etc/

This location is used to install global configuration files for a particular ROS distribution. Within the context of ROS, we introduce etc/ros, where ROS-specific system configuration files are stored.

Additionally, there is an etc/catkin and etc/langs that are used by the catkin build system. Although etc/langs configures the active ROS message generators, its implementation is specific to message generation using catkin, not specified here.

include/

ROS packages using the new install layout must install all header files to the include directory. Assuming a ROS package uses the namespace <ros-package-name>, its include files are stored in:

include/<ros-package-name>/

The specific include directories for a package are located using pkg-config or CMake find_package().

lib/

ROS packages using the new install layout must install library files to the lib directory.

Python modules are installed to lib/pythonX.Y, where X.Y is the Python version. This directory follows the standard Python specification for the target platform, which may be lib/pythonX.Y/dist-packages, or lib/pythonX.Y/site-packages, or somewhere else.

In the case of a special install prefix, PKG_CONFIG_PATH must enable locating libraries and include directories via pkg-config. LD_LIBRARY_PATH must be also set so that executables can load shared libraries. We use the settings:

PKG_CONFIG_PATH=/opt/ros/<distro>/lib/pkgconfig:$PKG_CONFIG_PATH
LD_LIBRARY_PATH=/opt/ros/<distro>/lib:$LD_LIBRARY_PATH

PYTHONPATH must also be set in a special install prefix and is platform dependent. For example, on Ubuntu Precise with Python 2.7, the setting is:

PYTHONPATH=/opt/ros/<distro>/python2.7/dist-packages:$PYTHONPATH

lib/<ros-package-name>/

All package-relative executables and scripts are installed in lib/<ros-package-name>/ subdirectory.

share/

All architecture-independent package-relative assets are explicitly installed to share/<ros-package-name>. These include:

• package definition files (package.xml)
• launch files
• other explicitly installed package-relative data such as bag files, or parameter definitions

stacks/

This is the installation location for rosmake-based stacks. It is included in the ROS_PACKAGE_PATH, but has lower precedence than packages following the new REP 122 layout. Converted packages do not use this folder.

ROS_ROOT

For backwards compatibility with rosmake build files, ROS_ROOT must exist within the new layout. However, its scope has been narrowed to finding legacy rosbuild and mk resources. Other uses, such as finding ROS binaries, are no longer supported. Thus, ROS_ROOT is deprecated. Although there are no plans to remove it, avoid using it for any new features.

For a full specification and rationale, see REP 123 [9], which also proposes new ROS filesystem environment variables based on the REP 122 layout.

PYTHONPATH, roslib.load_manifest()

Python modules now install into a dist-packages/site-packages in the lib directory in the install prefix. This installation uses the standard Python distutil/setuptools toolchain.

The Python install directory is added to the PYTHONPATH. Thus, these modules are immediately accessible via Python import and do not require a roslib.load_manifest().

In order to prevent unnecessary accumulation to the Python sys.path, roslib.load_manifest() does not recurse through packages built with catkin.

Python modules and scripts that are part of the FHS install layout must not use load_manifest as it does not work properly within an out-of-source build.