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
This REP provides naming conventions for how to refer to paths on a computer in documentation and debugging.
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.
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
...
When talking about a workspace used in development there are several names
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.
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.
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
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.
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.
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.
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
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.
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
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:
- Create catkin_ws and catkin_ws/src folder
- Run catkin_make in catkin_ws
- 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
| [1] | REP 1, REP Purpose and Guidelines, Conley (https://ros.org/reps/rep-0001.html) |
This document has been placed in the public domain.