Skip to content

Latest commit

 

History

History
307 lines (240 loc) · 8.78 KB

rep-0128.rst

File metadata and controls

307 lines (240 loc) · 8.78 KB

REP: 128 Title: Naming Conventions for Catkin Based Workspaces Author: Tully Foote, Dirk Thomas Status: Active Type: Informational Content-Type: text/x-rst Created: 16-Oct-2012 Post-History: 03-Jul-2014

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

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

The development space can not be a folder which contains ROS packages in subfolders. E.g. it can not equal to the workspace root as this would make the source space a subfolder which would lead to packages being found multiple times.

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.

The same restriction as for development spaces applies to the install space. This also implies that install spaces and development spaces must not be nested within each other.

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.

Result Space

The term result space can be used for either a development space or an install space. In cases where either of those two specific terms would do, the generic term should be used instead. To visually distinguish the result space from spaces that have a direct folder name correspondence (such as the folder install for the install space) it is recommended to refer to the result space as RESULT-SPACE in documentation, for example:

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

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

Copyright

This document has been placed in the public domain.