Managing Workspaces
This guide is an important and mandatory reading for all MRS members. Please, make a coffee and take your time to carefully study it, because it will make your (and Tomas's) life easier and it will help you avoid some compilation difficulties.
TL;DR & Tips
- Learn to configure the workspaces by hand, learn to setup and verify dependencies between the workspaces.
- Do not
source
more than one workspace in your~/.bashrc
or~/.zshrc
. - Be mindful about the workspace hierarchy It will allow you to work more efficiently.
- It is possible to maintain multiple copies of a workspace, each with a different build type or particular version of the software.
- Symlink packages from
~/git
to your workspaces, instead of directly cloning them into thesrc
folder.
What is a Catkin Workspace?
A Catkin workspace (workspace from now on) is a dedicated build space for Catkin packages, which is a package system used by ROS. A workspace is supposed to cluster together related packages, for which it manages a set of build profiles, each with a custom set of CMake arguments.
Workspace folder structure
Each maintained workspace should have the following top-level structure of folders:
workspace
├── build
├── devel
├── logs
└── src
where the build, devel and logs folders are generated by the build system, and the src contains the user's packages.
The tools to manage a workspace
Beware! Common folk on the internet will guide you towards using the catkin_make command. Don't listen to everything you hear on the internet. We use the catkin_tools package that extends the function of the original catkin_make.
Creating a workspace
- create a directory for the workspace
mkdir -p ~/my_workspace/src
- move to the root of the workspace
cd ~/my_workspace
- call
catkin_tools
's init command
catkin init
Note: The newly created workspace will extend the workspace, that is currently sourced.
If you're not sure which workspace you've extended, verify it with catkin config
.
Building a workspace
- put at least one Catkin package somewhere into
~/my_workspace/src
- call
catkin_tools
's build command
catkin build
Building a particular package
- if you are in a subdirectory of the package, do
catkin build --this
or using our alias
catkin bt
- you can invoke build using the package name form anywhere form the workspace
catkin build <package_name>
Cleaning the workspace
Cleaning can be performed in two ways:
- manually, by deleting the generated folder
cd ~/my_workspace
rm -rf build devel logs
- automatically using the
catkin
's clean command
cd ~/my_workspace
catkin clean
Sourcing the workspace
Specify to catkin
which workspace shall be loaded by sourcing the bottom-most workspace in the hierarchy in your ~/.bashrc
:
source $HOME/my_workspace/devel/setup.bash
or in ~/.zshrc
if you're using zshell:
source $HOME/my_workspace/devel/setup.zsh
This will setup the respective environment variables to enable lookup of packages (such as for using the roscd
command) contained in the sourced workspace and the workspaces it's extending.
You can verify which workspace is currently sourced by printing out the $CMAKE_PREFIX_PATH
environment variable using the command
echo $CMAKE_PREFIX_PATH
The first path printed is the currently sourced workspace and the following are the ones it's extending.
BEWARE! Unless you are 100% sure that your workspaces are correctly set and do not contain identical packages, do not source more than one workspace in your .bashrc
or .zshrc
.
Source only the bottom-most workspace that you're using in the workspace tree.
That is typically the user workspace that you're currently working with (see the recommended workspace hierarchy).
The extending hierarchy will handle the rest.
Recommended workspace hierarchy
Workspaces can be linked together such that dependencies between the workspaces can be satisfied. Linking of workspaces is an integral mechanism for separating logical packages into groups. Workspaces can be linked in an arbitrary way, e.g.:
To extend a workspace, it either has to be sourced when creating the new workspace (see creating a workspace) or extended manually using the catkin config
command (see below).
Extending ROS
The top-most workspace in the hierarchy should extend the installed ROS ecosystem:
catkin config --extend /opt/ros/noetic
Extending particular workspace
Any other workspace should extend the workspace hier in the hierarchy:
catkin config --extend ~/particular_workspace/devel
Build profiles
Workspace can maintain a set of pre-configured build profiles. A build profile provides custom compilation flags for all packages. This is typically used to specify the workspace-wide optimization level.
Setting build profiles
We typically use three build profiles that correspond to CMake build profiles:
name | description | optimization | |
---|---|---|---|
debug | corresponds to CMake's Debug profile | -Og -g | |
reldeb | default | corresponds to CMake's RelWithDebInfo profile | -O2 -g |
release | corresponds to CMake's Release profile | -O3 |
Use the following commands to set the profiles in your workspace:
catkin config --profile debug --cmake-args -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_FLAGS='-Og' -DCMAKE_C_FLAGS='-Og'
catkin config --profile release --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
catkin config --profile reldeb --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
The profiles can be switched by calling catkin profile set <profile name>
.
After the profile is switched, the whole workspace needs to be cleaned and recompiled.
See GCC optimization for info about the optimization flags.
Note: For the standard development cycle of programming-compilation-debugging, it's recommended to use the debug
profile as it provides the best compromise of fast compilation, code optimization and debugging experience.
You can set the debug
profile in your current workspace and leave the others at the default for performance.
Note2: Pre-built deb packages are typically build with the reldeb
profile.
Overriding build profiles on per-package level
Note: Take care not to override the workspace's compilation flags (unless you know what you're doing) with a CMake statement in your CMakeLists.txt
file such as
set(CMAKE_CXX_FLAGS_DEBUG "-fsanitize=address,undefined")
The correct command is
set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address,undefined")
or better yet
add_definitions(-fsanitize=address,undefined)
so that your flags are added after the workspace flags and don't replace them.
Package blacklisting
A package can be excluded from the build by:
- creating the
CATKIN_IGNORE
file in the package root, or - by blacklisting it in a workspace using
catkin config --blacklist <package_name>
.
Verifying the state of a workspace
Use the command catkin config
to obtain the current configuration for your workspace.