Cheat Sheet

This is a non-exhaustive list of some common and useful invocations of the catkin command. All of the commands which do not explicitly specify a workspace path (with --workspace) are assumed to be run from within a directory contained by the target workspace. For thorough documentation, please see the chapters on each verb.

Initializing Workspaces

Initialize a workspace with a default layout (src/build/devel) in the current directory:

• catkin init
• catkin init --workspace .
• catkin config --init
• mkdir src && catkin build

... with a default layout in a different directory:

• catkin init --workspace /tmp/path/to/my_catkin_ws

... which explicity extends another workspace:

• catkin config --init --extend /opt/ros/hydro

Initialize a workspace with a source space called other_src:

• catkin config --init --source-space other_src

... or a workspace with build, devel, and install space ending with the suffix _alternate:

• catkin config --init --space-suffix _alternate

Configuring Workspaces

View the current configuration:

• catkin config

Setting and un-setting CMake options:

• catkin config --cmake-args -DENABLE_CORBA=ON -DCORBA_IMPLEMENTATION=OMNIORB
• catkin config --no-cmake-args

Toggle installing to the specified install space:

• catkin config --install

Building Packages

Build all the packages:

• catkin build

... one at a time, with additional debug output:

• catkin build -p 1

... and force CMake to re-configure for each one:

• catkin build --force-cmake

Build a specific package and its dependencies:

• catkin build my_package

... or ignore its dependencies:

• catkin build my_package --no-deps

Build the package containing the current working directory:

• catkin build --this

... but don’t rebuild its dependencies:

• catkin build --this --no-deps

Build packages with aditional CMake args:

• catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug

... and save them to be used for the next build:

• catkin build --save-config --cmake-args -DCMAKE_BUILD_TYPE=Debug

Build all packages in a given directory:

• catkin build $(catkin list -u /path/to/folder)

... or in the current folder:

• catkin build $(catkin list -u .)

Cleaning Build Products

Blow away the build, devel, and install spaces (if they exist):

• catkin clean -a

... or just the build space:

• catkin clean --build

... or just delete the CMakeCache.txt files for each package:

• catkin clean --cmake-cache

... or just delete the build directories for packages which have been disabled or removed:

• catkin clean --orphans

Controlling Color Display

Disable colors when building in a shell that doesn’t support it (like IDEs):

• catkin --no-color build

... or enable it for shells that don’t know they support it:

• catkin --force-color build

Profile Cookbook

Create “Debug” and “Release” profiles and then build them in independent build and devel spaces:

catkin config --profile debug -x _debug --cmake-args -DCMAKE_BUILD_TYPE=Debug
catkin config --profile release -x _release --cmake-args -DCMAKE_BUILD_TYPE=Release
catkin build --profile debug
catkin build --profile release

Quickly build a package from scratch to make sure all of its dependencies are satisfied, then clean it:

catkin config --profile my_pkg -x _my_pkg_test
catkin build --profile my_pkg my_pkg
catkin clean --profile my_pkg --all

Manipulating Workspace Chaining

Change from implicit to explicit chaining:

catkin clean -a
catkin config --extend /opt/ros/hydro

Change from explicit to implicit chaining:

catkin clean -a
catkin config --no-extend

Building With Other Jobservers

Build with distcc:

CC="distcc gcc" CXX="distcc g++" catkin build -p$(distcc -j) -j$(distcc -j) --no-jobserver