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.

Recommended Layout

The recommended layout for development is as follows:

workspace_folder/        --WORKSPACE
  src/                   --SOURCE SPACE
    CMakeLists.txt       --This is symlinked to catkin/cmake/toplevel.cmake
    package_1/
      CMakeLists.txt
      package.xml
    ...
    package_n/
      CATKIN_IGNORE      --Optionally place this marker file to exclude package_n from being processed. Its file type (e.g. regular file, directory) and contents don't matter. It may even be a dangling symlink.
      CMakeLists.txt
      package.xml
  build/                 --BUILD SPACE(this is where build system is invoked, not necessarily within workspace)
    CATKIN_IGNORE        --Marking the folder to be ignored when crawling for packages (necessary when source space is in the root of the workspace, the file is emtpy)
  devel/                 --DEVEL SPACE (targets go here, parameterizable, but defaults to peer of Build Space)
    bin/
    etc/
    include/
    lib/
    share/
    .catkin              --Marking the folder as a development space (the file contains a semicolon separated list of Source space paths)
    env.bash
    setup.bash
    setup.sh
    ...
  install/               --INSTALL SPACE (this is where installed targets for test installations go, not necessarily within workspace)
    bin/
    etc/
    include/
    lib/
    share/
    .catkin              --Marking the folder as an install space (the file is empty)
    env.bash
    setup.bash
    setup.sh
    ...

Elements of the Workspace

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

cmake ../src

source RESULT-SPACE/setup.sh

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

Copyright

This document has been placed in the public domain.