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:
  .. code-block:: bash

    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:
  .. code-block:: bash

    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:
  .. code-block:: bash

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

Change from explicit to implicit chaining:
  .. code-block:: bash

    catkin clean -a
    catkin config --no-extend

Building With Other Jobservers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Build with ``distcc``:
  .. code-block:: bash

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