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 explicitly extends another workspace:
  • catkin config --init --extend /opt/ros/noetic
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 unsetting CMake options:
  • 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 additional 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 -d /path/to/folder)
… or in the current folder:
  • catkin build $(catkin list -u -d .)

Testing Packages

Test all the packages:
  • catkin test
… one at a time, with live output:
  • catkin build -p 1 -i
Test a specific package:
  • catkin test my_package
… or a specific test target of a package
  • catkin test -t my_target my_package

Cleaning Build Products

Blow away the build, devel, and install spaces (if they exist):
  • catkin clean
… or just the build space:
  • catkin clean --build
… or just clean a single package:
  • catkin clean PKGNAME
… 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
catkin config --extend /opt/ros/noetic
Change from explicit to implicit chaining:
catkin clean
catkin config --no-extend

Building With Other Job Servers

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

Changing Package’s Build Type

Set the build type to cmake in the package.xml file’s <export/> section: