[REP Index] [REP Source]

REP:128
Title:Naming Conventions for Catkin Based Workspaces
Author:Tully Foote
Status:Active
Type:Informational
Content-Type:text/x-rst
Created:16-Oct-2012
Post-History:30-Aug-2002

Abstract

This REP provides naming conventions for how to refer to paths on a computer in documentation and debugging.

Rationale

This REP has been written to make reading and writing documentation easier and more consistent and to remove ambiguities when communicating about the code layout of a specific installation.

Elements of the Workspace

When talking about a workspace used in development there are several names

Workspace

The workspace is the folder inside which you are going to be actively developing. Keeping things in a folder with connected development helps keep seperation of development models.

Source Space

The source space is the folder is where catkin will be expected to look for packages when building. This folder is easily identifed as it is where the toplevel.cmake is linked from the catkin project.

Each catkin project desired to be compiled from source should be checked out into subdirectories inside this directory. Packages are found recursively so they do not have to be direct subfolders.

Build Space

The build space is the folder in which cmake is invoked and generates artifacts such as the CMakeCache

A typical invocation of cmake will look like this when following the recommended layout.

cmake ../src

Development Space

The development space is where catkin generates the binaries and runtime libraries which are executable before installation. This folder will be an approximation of FHS layout however only containing artifacts from the associated source space.

After the build step, inside this folder is expected everything needed to run nodes in packages which have been built.

Install Space

If make install is called this is the directory into which cmake will target all installations. Again creating an FHS style directory structure with a setup.(ba)sh in the root. This can be set to any directory using the -DCMAKE_INSTALL_PREFIX=/any/directory as an option to cmake. The cmake default is /usr/local.

System Install Space

The system install space is a special category of the installation space which is expected to be a shared installation for all users on the system. Usually this is installed from your package manager. The default for this location is /opt/ros/ROSDISTRO where ROSDISTRO is the codename for the ROS distro being used.

Overlays

In catkin style workspaces, overlaying of one workspace on top of another workspace is supported. Each overlay can be built on top of another overlay, and any packages in a higher overlay will mask out packages in lower overlays.

Note: When overlaying any package all packages which depend on that package must be overlayed if they are intended to be used. This must be checked by the user creating the overlays. If a core package is overlayed and changes how it works, any package which depends on it and relies on the old behavior (whether runtime, or link time) will crash.

Catkin creates FHS [CITE FHS] style layouts in the devel and install spaces. [cite above] These spaces can be included into another workspace using the CMAKE_PREFIX_PATH pointing to either the devel space or install space. If it is an installed space make install must have been called, if a devel space, it must have been built with make.

Examples

Here are some examples showing basic usage.

Let us say we have several catkin workspaces in our home folder (~/).

~/workspace1/
    /src
    /build
    /devel
~/workspace2/
    /src
    /build
    /devel
~/workspace3/
    /src
    /build
    /devel

Example 1: Installing workspace1 to system

export CMAKE_INSTALL_PREFIX=/opt/ros/groovy
cd ~/workspace1/build
cmake ../src
make
make install

Alternatively you can set CMAKE_INSTALL_PREFIX when calling cmake in the third step:

cd ~/workspace1/build
cmake -DCMAKE_INSTALL_PREFIX=/opt/ros/groovy ../src
make
make install

Example 2: Overlaying workspace2 on top of workspace1's devel space

source ~/workspace1/devel/setup.bash
cd ~/workspace2/build
cmake ../src
make

Example 3: Overlaying workspace 2 on top of workspace1's devel space on top of system installation

source ~/workspace1/devel/setup.bash
cd ~/workspace2/build
cmake ../src
make

Example 4: Overlaying workspace 3 on top of local workspace2 install space on top of workspace1 devel space on top of system install

cd ~/workspace2/build
cmake -DCMAKE_INSTALL_PREFIX=~/ws2_installed ../src
make
make install

source ~/ws2_installed/setup.bash

cd ~/workspace3/build
cmake ../src
make

Mixing catkin And rosbuild Workspaces

catkin was designed to allow rosbuild packages to sit on top of catkin ones. This is accomplished by using overlays. A rosbuild overlay can overlay either a catkin workspace devel space or installspace. The setup.*sh file for the rosbuild workspace will, when sourced, also source the respective setup.*sh of the catkin workspace.

Though one could technically utilize the same folder for a rosbuild workspace and a catkin workspace, our recommended layout is to isolate rosbuild and catkin workspaces in their own folders.

~/rosbuild_ws/
   dry_pkg1/
   ...
   dry_pkgN/
   setup.bash
   setup.sh
~/catkin_ws/
   src/
     wet_pkg1/
     ...
     wet_pkgN/
   build/
   devel/
     setup.bash
     setup.sh
   install/
     setup.bash
     setup.sh

The steps to achieve this layout are:

  1. Create catkin_ws and catkin_ws/src folder
  2. Run catkin_make in catkin_ws
  3. Run rosws init ~/rosbuild_ws/ ~/catkin_ws/devel (or install)

With this layout, sourcing ~/rosbuild_ws/setup.*sh also sources ~/catkin_ws/devel/setup.*sh

References

[1]REP 1, REP Purpose and Guidelines, Warsaw, Hylton (http://ros.org/reps/rep-0001.html)