Catkin Command Line Tools¶

Installing on Ubuntu with apt-get¶

First you must have the ROS repositories which contain the .deb for catkin_tools:

$ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu `lsb_release -sc` main" > /etc/apt/sources.list.d/ros-latest.list'
$ wget http://packages.ros.org/ros.key -O - | sudo apt-key add -

Once you have added that repository, run these commands to install catkin_tools:

$ sudo apt-get update
$ sudo apt-get install python-catkin-tools

Installing on other platforms with pip¶

Simply install it with pip:

$ sudo pip install -U catkin_tools

Installing from source¶

First clone the source for catkin_tools:

$ git clone https://github.com/catkin/catkin_tools.git
$ cd catkin_tools

Then install with the setup.py file:

$ python setup.py install

Note: Depending on your environment/machine, you may need to use sudo with this command.

Install catkin_tools for developing¶

To setup catkin_tools for fast iteration during development, use the develop verb to setup.py:

$ python setup.py develop

Now the commands, like catkin, will be in the system path and the local source files located in the catkin_tools folder will be on the PYTHONPATH. When you are done with your development, undo this by running this command:

$ python setup.py develop -u

Legacy Catkin Workflow¶

The core Catkin meta-buildsystem was originally designed in order to efficiently build numerous inter-dependent, but separately developed, CMake projects. This was developed by the Robot Operating System (ROS) community, originally as a successor to the standard meta-buildtool rosbuild. The ROS community’s distributed development model with many modular projects and the need for building distributable binary packages motivated the design of a system which efficiently merged numerous disparate projects so that they utilize a single target dependency tree and build space.

To facilitate this “merged” build process, a workspace’s source space would contain boiler-plate “top-level” CMakeLists.txt which automatically added all of the Catkin CMake projects below it to the single large CMake project.

Then the user would build this collection of projects like a single unified CMake project with a workflow similar to the standard CMake out-of-source build workflow. They would all be configured with one invocation of cmake and subsequently targets would be built with one or more invocations of make:

$ mkdir build
$ cd build
$ cmake ../src
$ make

In order to help automate the merged build process, Catkin was distributed with a command-line tool called catkin_make. This command automated the above CMake work flow while setting some variables according to standard conventions. These defaults would result in the execution of the following commands:

$ mkdir build
$ cd build
$ cmake ../src -DCATKIN_DEVEL_SPACE=../devel -DCMAKE_INSTALL_PREFIX=../install
$ make -j<number of cores> -l<number of cores> [optional target, e.g. install]

An advantage of this approach is that the total configuration would be smaller than configuring each package individually and that the Make targets can be parallelized even amongst dependent packages.

In practice, however, it also means that in large workspaces, modification of the CMakeLists.txt of one package would necessitate the reconfiguration of all packages in the entire workspace.

A critical flaw of this approach, however, is that there is no fault isolation. An error in a leaf package (package with no dependencies) will prevent all packages from configuring. Packages might have colliding target names. The merged build process can even cause CMake errors to go undetected if one package defines variables needed by another one, and can depend on the order in which independent packages are built. Since packages are merged into a single CMake invocation, this approach also requires developers to specify explicit dependencies on some targets inside of their dependencies.

Another disadvantage of the merged build process is that it can only work on a homogeneous workspace consisting only of Catkin CMake packages. Other types of packages like plain CMake packages and autotools packages cannot be integrated into a single configuration and a single build step.

Isolated Catkin Workflow¶

The numerous drawbacks of the merged build process and the catkin_make tool motivated the development of the catkin_make_isolated tool. In contrast to catkin_make, the catkin_make_isolated command uses an isolated build process, wherein each package is independently configured, built, and loaded into the environment.

This way, each package is built in isolation and the next packages are built on the atomic result of the current one. This resolves the issues with target collisions, target dependency management, and other undesirable cross-talk between projects. This also allows for the homogeneous automation of other buildtools like the plain CMake or autotools.

The isolated workflow also enabled the following features:

• Allowing building of part of a workspace
• Building Catkin and non-Catkin projects into a single devel space
• Building packages without re-configuring or re-building their dependencies
• Removing the requirement that all packages in the workspace are free of CMake errors before any packages can be built

There are, however, still some problems with catkin_make_isolated. First, it is dramatically slower than catkin_make since it cannot parallelize the building of targets or even packages which do not depend on each other. It also lacks robustness to changes in the list of packages in the workspace. Since it is a “released” tool, it also has strict API stability requirements.

Parallel Isolated Catkin Workflow and catkin build¶

The limitations of catkin_make_isolated and the need for additional high-level build tools lead to the development of a parallel version of catkin make isolated, or pcmi, as part of Project Tango. pcmi later became the build verb of the catkin command included in this project.

As such, the principle behavior of the build verb is to build each package in isolation and in topological order while parallelizing the building of packages which do not depend on each other.

Other functional improvements over catkin_make and catkin_make_isolated include the following:

• The use of sub-command “verbs” for better organization of build options and build-related functions
• Robustly adapting a build when packages are added to or removed from the source space
• Context-aware building of a given package based on the working directory
• Utilization of persistent build metadata which catches common errors
• Support for different build “profiles” in a single workspace
• Explicit control of workspace chaining
• Additional error-checking for common environment configuration errors
• Numerous other command-line user-interface improvements

TL;DR¶

The following is an example workflow and sequence of commands using default settings:

source /opt/ros/indigo/setup.bash          # Source ROS indigo to use Catkin
mkdir -p /tmp/quickstart_ws/src            # Make a new workspace and source space
cd /tmp/quickstart_ws                      # Navigate to the workspace root
catkin init                                # Initialize it with a hidden marker file
cd /tmp/quickstart_ws/src                  # Navigate to the source space
catkin create pkg pkg_a                    # Populate the source space with packages...
catkin create pkg pkg_b
catkin create pkg pkg_c --catkin-deps pkg_a
catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
catkin list                                # List the packages in the workspace
catkin build                               # Build all packages in the workspace
source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
catkin clean --all                         # Clean all the build products

Initializing a New Workspace¶

While initialization of a workspace can be done automatically with catkin build, it’s good practice to initialize a catkin workspace explicitly. This is done by simply creating a new workspace with an empty source space (named src by default) and calling catkin init from the workspace root:

source /opt/ros/indigo/setup.bash          # Source ROS indigo to use Catkin
mkdir -p /tmp/quickstart_ws/src            # Make a new workspace and source space
cd /tmp/quickstart_ws                      # Navigate to the workspace root
catkin init                                # Initialize it with a hidden marker file

Now the directory /tmp/quickstart-init has been initialized and catkin init has printed the standard configuration summary to the console with the default values. This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior.

Once a workspace has been initialized, the configuration summary can be displayed by calling catkin config without arguments from anywhere under the root of the workspace. Doing so will not modify your workspace. The catkin command is context-sensitive, so it will determine which workspace contains the current working directory.

An important property which deserves attention is the summary value labeled Extending. This describes other collections of libraries and packages which will be visible to your workspace. This is process called “workspace chaining.” The value can be come from a few different sources, and can be classified in one of the three following ways:

• No chaining
• Implicit chaining via CMAKE_PREFIX_PATH environment or cache variable
• Explicit chaining via catkin config --extend

For more information on the configuration summary and workspace chaining, see Configuration Summary. For information on manipulating these options, see the config verb.

Adding Packages to the Workspace¶

In order to build software with Catkin, it needs to be added to the workspace’s source space. You can either download some existing packages, or create one or more empty ones. As shown above, the default path for a Catkin source space is ./src relative to the workspace root. A standard Catkin package is simply a directory with a CMakeLists.txt file and a package.xml file. For more information on Catkin packages see workspace mechanics. The shell interaction below shows the creation of four empty packages: pkg_a, pkg_b, pkg_c, and pkg_d:

cd /tmp/quickstart_ws/src                  # Navigate to the source space
catkin create pkg pkg_a                    # Populate the source space with packages...
catkin create pkg pkg_b
catkin create pkg pkg_c --catkin-deps pkg_a
catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
catkin list                                # List the packages in the workspace

After these operations, your workspace’s local directory structure would look like the followng (to two levels deep):

cd /tmp/quickstart_ws # Navigate to the workspace root
tree -aL 2            # Show prebuild directory tree

.
├── .catkin_tools
│   ├── default
│   └── README
└── src
    ├── pkg_a
    ├── pkg_b
    ├── pkg_c
    └── pkg_d

7 directories, 1 file

Now that there are some packages in the workspace, Catkin has something to build.

Building the Workspace¶

Since the catkin workspace has already been initialized, you can call catkin build from any directory contained within it. If it had not been initialized, then catkin build would need to be called from the workspace root. Based on the default configuration, it will locate the packages in the source space and build each of them.

catkin build                               # Build all packages in the workspace

Calling catkin build will generate build and devel directories (as described in the config summary above) and result in a directory structure like the following (to one level deep):

cd /tmp/quickstart_ws # Navigate to the workspace root
tree -aL 2            # Show postbuild directory tree

.
├── build
│   ├── .built_by
│   ├── .catkin_tools.yaml
│   ├── _logs
│   ├── pkg_a
│   ├── pkg_b
│   ├── pkg_c
│   └── pkg_d
├── .catkin_tools
│   ├── default
│   └── README
├── devel
│   ├── .built_by
│   ├── .catkin
│   ├── env.sh
│   ├── etc
│   ├── lib
│   ├── .rosinstall
│   ├── setup.bash
│   ├── setup.sh
│   ├── _setup_util.py
│   ├── setup.zsh
│   └── share
└── src
    ├── pkg_a
    ├── pkg_b
    ├── pkg_c
    └── pkg_d

17 directories, 11 files

Intermediate build products (CMake cache files, Makefiles, object files, etc.) are generated in the build directory, or build space and final build products (libraries, executables, config files) are generated in the devel directory, or devel space. For more information on building and customizing the build configuration see the build verb and config verb documentation.

Loading the Workspace Environment¶

In order to properly “use” the products of the workspace, it’s environment needs to be loaded. Among other environment variables, sourcing a Catkin setup file modifies the CMAKE_PREFIX_PATH environment variable, which will affect workspace chaining as described in the earlier section.

Setup files are located in one of the result spaces generated by your workspace. Both the devel space or the install space are valid result spaces. In the default build configuration, only the devel space is generated. You can load the environment for your respective shell like so:

source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment

At this point you should be able to use products built by any of the packages in your workspace.

Loading the environment from a Catkin workspace can set arbitrarily many environment variables, depending on which “environment hooks” the member packages define. As such, it’s important to know which workspace environment is loaded in a given shell.

It’s not unreasonable to automatically source a given setup file in each shell for convenience, but if you do so, it’s good practice to pay attention to the Extending value in the Catkin config summary. Any Catkin setup file will modify the CMAKE_PREFIX_PATH environment variable, and the config summary should catch common inconsistencies in the environment.

Cleaning Workspace Products¶

Instead of using dangerous commands like rm -rf build devel in your workspace when cleaning build products, you can use the catkin clean --all command. Just like the other verbs, catkin clean is context-aware, so it only needs to be called from a directory under the workspace root.

In order to clean the build space and devel space for the workspace, you can use the following command:

catkin clean --all                         # Clean all the build products

For more information on less aggressive cleaning options see the clean verb documentation.

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

Important Distinctions between catkin_make and catkin build¶

Unlike catkin_make, the catkin command-line tool is not just a thin wrapper around a CMake use pattern. The catkin build command builds each package in a workspace’s source space in isolation in order to prevent buildtime cross-talk. As such, in its simplest use, catkin build is like a parallelized version of catkin_make_isolated. While there are many more features in catkin_tools described in the rest of the documentation, this chapter provides details on how to switch from using catkin_make or catkin_make_isolated.

Operational Differences¶

• catkin_tools has no “top-level” CMakeLists.txt file. The source space simply contains a collection of packages. If you have been modifying this CMakeLists.txt file, those modifications will be ignored.
• Each package in a catkin_tools workspace has its own isolated build space.
• catkin build can be run from any directory under the workspace root
• catkin config stores many workspace configuration options which needed to be passed to each call of catkin_make
• catkin build can build plain CMake packages if they have package.xml files
• Packages built with catkin build can not access variables defined in other Catkin packages in the same workspace.
• Packages no longer need to define target dependencies on ROS messages built in other packages. All targets in a dependency are guaranteed to have been built before the current package.
• catkin_tools and catkin_make can use the same source space, but they must use different build, devel, and install spaces.
• catkin build generates .catkin files and subsequently ROS_PACKAGE_PATH variables where each source package is listed, individually, instead of just listing the source space for the workspace.
• catkin build passes CMake command line arguments to multiple packages. Since not all packages accept the same CMake arguments, the cmake command is invoked with --no-warn-unused-cli. This means there will be no warnings for unused variables passed to cmake.

IDE Integration¶

Since all packages are built in isolation with catkin build, you can’t rely on CMake’s IDE integration to generate a single project for your entire workspace.

Migration Troubleshooting¶

When migrating from catkin_make to catkin build, the most common problems come from Catkin packages taking advantge of package cross-talk in the CMake configuration stage.

Many Catkin packages implicitly rely on other packages in a workspace to declare and find dependencies. When switcing from catkin_make, users will often discover these bugs.

set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}")

# generated from stdr_common/cmake/stdr_common-extras.cmake.em

@[if DEVELSPACE]@
# set path to source space
set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
@[else]@
# set path to installspace
set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
@[end if]@

catkin_package(
  ...
  LIBRARIES # NOTE: Not specified here, but in extras file
  CFG_EXTRAS my-extras.cmake
)

set_target_properties(
  ${PROJECT_NAME} PROPERTIES
  PREFIX ""
  LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
)

find_library(@PROJECT_NAME@_LIBRARY
            NAMES @PROJECT_NAME@
            PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
            NO_DEFAULT_PATH)

if(@PROJECT_NAME@_LIBRARY)
  # Multiple CMake projects case (i.e. 'catkin build'):
  # - The target has already been built when its dependencies require it
  # - Specify full path to found library
  list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
else()
  # Single CMake project case (i.e. 'catkin_make'):
  # - The target has not been built when its dependencies require it
  # - Specify target name only
  list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
endif()

build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7

CLI Comparison with catkin_make and catkin_make_isolated¶

Below are tables mapping catkin_make and catkin_make_isolated arguments into catkin arguments. Note that some catkin_make options can only be achived with the catkin config verb.

Anatomy of a Catkin Workspace¶

A standard catkin workspace, as defined by REP-0128, is a directory with a prescribed set of “spaces”, each of which is contained within a directory under the workspace root. The spaces that comprise the workspace are described in the following sections.

In addition to these user-facing directories, catkin_tools also creates a hidden .catkin_tools directory, which stores persistent build configuration.

Additional Files Generated by catkin_tools¶

{VERB}.{STAGE}.log

{VERB}.{STAGE}.{INDEX}.log

Environment Setup Files¶

The FHS trees of the devel space and install space also contain several environemnt “setup” scripts. These setup scripts are intended to make it easier to use the resulting FHS tree for building other source code or for running programs built by the packages in the workspace.

The setup script can be used like this in bash:

$ source /path/to/workspace/devel/setup.bash

Or like this in zsh:

% source /path/to/workspace/devel/setup.zsh

Sourcing these setup scripts adds this workspace and any “underlaid” workspaces to your environment, prefixing several environment variables with the appropriate local workspace folders.

The setup scripts will also execute any Catkin “env-hooks” exported by packages in the workspace. For example, this is how roslib sets the ROS_PACKAGE_PATH environment variable.

Source Packages and Dependencies¶

A package is any folder which contains a package.xml as defined by the ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.

The catkin build command builds packages in the topological order determined by the dependencies listed in the package’s package.xml file. For more information on which dependencies contribute to the build order, see the build verb documentation.

Additionally, the build_type tag is used to determine which build stages to use on the package. Supported build types are listed in Build Types. Packages without a build_type tag are assumed to be catkin packages.

For example, plain CMake packages can be built by adding a package.xml file to the root of their source tree with the build_type flag set to cmake and appropriate build_depend and run_depend tags set, as described in REP-0136. This can been done to build packages like opencv, pcl, and flann.

Workspace Configuration¶

Most catkin commands which modify a workspace’s configuration will display the standard configuration summary, as shown below:

$ cd /tmp/path/to/my_catkin_ws
$ catkin config
--------------------------------------------------------------
Profile:                     default
Extending:                   None
Workspace:                   /tmp/path/to/my_catkin_ws
Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
Install Space:     [missing] /tmp/path/to/my_catkin_ws/install
DESTDIR:                     None
--------------------------------------------------------------
Devel Space Layout:          merged
Install Packages:            False
Isolate Installs:            False
--------------------------------------------------------------
Additional CMake Args:       None
Additional Make Args:        None
Additional catkin Make Args: None
Internal Make Job Server:    True
Cache Job Environments:      False
--------------------------------------------------------------
Whitelisted Packages:        None
Blacklisted Packages:        None
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------

This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior. Each of these options can be modified either with the config verb’s options described in the full command-line usage or by changing environment variables. The summary is composed of the following sections:

Workspace Chaining / Extending¶

An important property listed in the configuration configuration which deserves attention is the summary value of the Extending property. This affects which other collections of libraries and packages which will be visible to your workspace. This is process called “workspace chaining.”

Above, it’s mentioned that the Catkin setup files export numerous environment variables, including CMAKE_PREFIX_PATH. Since CMake 2.6.0, the CMAKE_PREFIX_PATH is used when searching for include files, binaries, or libraries using the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or FIND_LIBRARY() CMake commands.

As such, this is also the primary way that Catkin “chains” workspaces together. When you build a Catkin workspace for the first time, it will automatically use CMAKE_PREFIX_PATH to find dependencies. After that compilation, the value will be cached internally by each project as well as the Catkin setup files and they will ignore any changes to your CMAKE_PREFIX_PATH environment variable until they are cleaned.

Similarly, when you source a Catkin workspace’s setup file from a workspace’s devel space or install space, it prepends the path containing that setup file to the CMAKE_PREFIX_PATH environment variable. The next time you initialize a workspace, it will extend the workspace that you previously sourced.

On one hand, this makes it easy and automatic to chain workspaces. At the same time, however, previous tools like catkin_make and catkin_make_isolated had no easy mechanism for either making it obvious which workspace was being extended, nor did they provide features to explicitly extend a given workspace. This means that for users unaware of Catkin’s use of CMAKE_PREFIX_PATH

Since it’s not expected that 100% of users will read this section of the documentation, the catkin program adds both configuration consistency checking for the value of CMAKE_PREFIX_PATH and makes it obvious on each invocation which workspace is being extended. Furthermore, the catkin command adds an explicit extension interface to override the value of $CMAKE_PREFIX_PATH with the catkin config --extend command.

The information about which workspace to extend can come from a few different sources, and can be classified in one of three ways:

Extending:                   None

Extending:             [env] /opt/ros/hydro

Extending:          [cached] /opt/ros/hydro

Extending:        [explicit] /tmp/path/to/other_ws

Catkin¶

Catkin packages are CMake packages which utilize the Catkin CMake macros for finding packages and defining configuration files.

CMake¶

Configuration Summary Warnings¶

The catkin tool is capable of detecting some issues or inconsistencies with the build configuration automatically. In these cases, it will often describe the problem as well as how to resolve it. The catkin tool will detect the following issues automatically.

Dependency Resolution¶

Migration Problems¶

For troubleshooting problems when migrating from catkin_make or catkin_make_isolated, see Migration Troubleshooting.

Basic Usage¶

cd /tmp/ros_tutorials_ws  # Navigate to workspace
catkin build --dry-run    # Show the package build order

cd /tmp/ros_tutorials_ws  # Navigate to workspace
catkin build              # Build all the packages in the workspace
ls build                  # Show the resulting build space
ls devel                  # Show the resulting devel space

[build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...

...
Starting  >>> {JOB}
...
Finished  <<< {JOB}   [ {TIME} seconds ]
...

____________________________________________________________________________
Warnings   << {JOB}:{STAGE} {LOGFILE PATH}
{WARNINGS}
{REPRODUCTION COMMAND}
............................................................................
Finished   << {JOB}            [ {TIME} seconds ]

____________________________________________________________________________
Errors     << {JOB}:{STAGE} {LOGFILE PATH}
{ERRORS}
{REPRODUCTION COMMAND}
............................................................................
Failed     << {JOB}:{STAGE}    [ Exited with code {EXIT CODE} ]
Failed     << {JOB}            [ {TIME} seconds ]

[build] Runtime: 1.9 seconds total.
[build] Summary: 4 of 7 jobs completed.
[build]   Warnings:  None.
[build]   Abandoned: 1 jobs were abandoned.
[build]   Failed:    2 jobs failed.

Building Subsets of Packages¶

Consider a Catkin workspace with a source space populated with the following Catkin packages which have yet to be built:

$ pwd
/tmp/path/to/my_catkin_ws

$ ls ./*
./src:
catkin             console_bridge     genlisp            genpy
message_runtime    ros_comm           roscpp_core        std_msgs
common_msgs        gencpp             genmsg             message_generation
ros                ros_tutorials      rospack

cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build roslib      # Build roslib and its dependencies

cd /tmp/ros_tutorials_ws # Navigate to workspace
cd src/ros/roslib        # Navigate to roslib source directory
ls                       # Show source directory contents
catkin build --this      # Build roslib and its dependencies

cd /tmp/ros_tutorials_ws         # Navigate to workspace
catkin build --start-with roslib # Build roslib and its dependants

cd /tmp/ros_tutorials_ws      # Navigate to workspace
catkin build roslib --no-deps # Build roslib only

Building and Running Tests¶

Running tests for a given package typically is done by invoking a special make target like test or run_tests. catkin packages all define the run_tests target which aggregates all types of tests and runs them together. So in order to get tests to build and run for your packages you need to pass them this additional run_tests or test target as a command line option to make.

To run catkin tests for all catkin packages in the workspace, use the following:

$ catkin run_tests

Or the longer version:

$ catkin build [...] --catkin-make-args run_tests

To run a catkin test for a specific catkin package, from a directory within that package:

$ catkin run_tests --no-deps --this

For non-catkin packages which define a test target, you can do this:

$ catkin build [...] --make-args test

If you want to run tests for just one package, then you should build that package and this narrow down the build to just that package with the additional make argument:

$ # First build the package
$ catkin build package
...
$ # Then run its tests
$ catkin build package --no-deps --catkin-make-args run_tests
$ # Or for non-catkin packages
$ catkin build package --no-deps --make-args test

For catkin packages and the run_tests target, failing tests will not result in an non-zero exit code. So if you want to check for failing tests, use the catkin_test_results command like this:

$ catkin_test_results build/<package name>

The result code will be non-zero unless all tests passed.

Advanced Options¶

$ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"

$ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"

$ catkin build --mem-limit 50%

$ catkin build --mem-limit 4G

Full Command-Line Interface¶

usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
                    [--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
                    [--unbuilt] [--start-with PKGNAME | --start-with-this]
                    [--continue-on-failure] [--force-cmake] [--pre-clean]
                    [--no-install-lock] [--save-config] [-j JOBS]
                    [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
                    [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
                    | --no-cmake-args] [--make-args ARG [ARG ...] |
                    --no-make-args] [--catkin-make-args ARG [ARG ...] |
                    --no-catkin-make-args] [--verbose] [--interleave-output]
                    [--no-status] [--summarize] [--no-summarize]
                    [--override-build-tool-check]
                    [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
                    [PKGNAME [PKGNAME ...]]

Build one or more packages in a catkin workspace. This invokes `CMake`,
`make`, and optionally `make install` for either all or the specified packages
in a catkin workspace. Arguments passed to this verb can temporarily override
persistent options stored in the catkin profile config. If you want to save
these options, use the --save-config argument. To see the current config, use
the `catkin config` command.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --profile PROFILE     The name of a config profile to use (default: active
                        profile)
  --dry-run, -n         List the packages which will be built with the given
                        arguments without building them.
  --get-env PKGNAME     Print the environment in which PKGNAME is built to
                        stdout.

Packages:
  Control which packages get built.

  PKGNAME               Workspace packages to build, package dependencies are
                        built as well unless --no-deps is used. If no packages
                        are given, then all the packages are built.
  --this                Build the package containing the current working
                        directory.
  --no-deps             Only build specified packages, not their dependencies.
  --unbuilt             Build packages which have yet to be built.
  --start-with PKGNAME  Build a given package and those which depend on it,
                        skipping any before it.
  --start-with-this     Similar to --start-with, starting with the package
                        containing the current directory.
  --continue-on-failure, -c
                        Try to continue building packages whose dependencies
                        built successfully even if some other requested
                        packages fail to build.

Build:
  Control the build behavior.

  --force-cmake         Runs cmake explicitly for each catkin package.
  --pre-clean           Runs `make clean` before building each package.
  --no-install-lock     Prevents serialization of the install steps, which is
                        on by default to prevent file install collisions

Config:
  Parameters for the underlying build system.

  --save-config         Save any configuration options in this section for the
                        next build invocation.
  -j JOBS, --jobs JOBS  Maximum number of build jobs to be distributed across
                        active packages. (default is cpu count)
  -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
                        Maximum number of packages allowed to be built in
                        parallel (default is cpu count)
  --jobserver           Use the internal GNU Make job server which will limit
                        the number of Make jobs across all active packages.
  --no-jobserver        Disable the internal GNU Make job server, and use an
                        external one (like distcc, for example).
  --env-cache           Re-use cached environment variables when re-sourcing a
                        resultspace that has been loaded at a different stage
                        in the task.
  --no-env-cache        Don't cache environment variables when re-sourcing the
                        same resultspace.
  --cmake-args ARG [ARG ...]
                        Arbitrary arguments which are passes to CMake. It
                        collects all of following arguments until a "--" is
                        read.
  --no-cmake-args       Pass no additional arguments to CMake.
  --make-args ARG [ARG ...]
                        Arbitrary arguments which are passes to make.It
                        collects all of following arguments until a "--" is
                        read.
  --no-make-args        Pass no additional arguments to make (does not affect
                        --catkin-make-args).
  --catkin-make-args ARG [ARG ...]
                        Arbitrary arguments which are passes to make but only
                        for catkin packages.It collects all of following
                        arguments until a "--" is read.
  --no-catkin-make-args
                        Pass no additional arguments to make for catkin
                        packages (does not affect --make-args).

Interface:
  The behavior of the command-line interface.

  --verbose, -v         Print output from commands in ordered blocks once the
                        command finishes.
  --interleave-output, -i
                        Prevents ordering of command output when multiple
                        commands are running at the same time.
  --no-status           Suppresses status line, useful in situations where
                        carriage return is not properly supported.
  --summarize, --summary, -s
                        Adds a build summary to the end of a build; defaults
                        to on with --continue-on-failure, off otherwise
  --no-summarize, --no-summary
                        Explicitly disable the end of build summary
  --override-build-tool-check
                        use to override failure due to using differnt build
                        tools on the same workspace.
  --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
                        Limit the update rate of the status bar to this
                        frequency. Zero means unlimited. Must be positive,
                        default is 10 Hz.
  --no-notify           Suppresses system pop-up notification.

Full Command-Line Interface¶

usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE] [-a] [-b]
                    [-d] [-i] [-c] [-s] [-o]

Deletes various products of the build verb.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --profile PROFILE     The name of a config profile to use (default: active
                        profile)

Basic:
  Clean workspace subdirectories.

  -a, --all             Remove all of the *spaces associated with the given or
                        active profile. This will remove everything but the
                        source space and the hidden .catkin_tools directory.
  -b, --build           Remove the buildspace.
  -d, --devel           Remove the develspace.
  -i, --install         Remove the installspace.

Advanced:
  Clean only specific parts of the workspace. These options will
  automatically enable the --force-cmake option for the next build
  invocation.

  -c, --cmake-cache     Clear the CMakeCache for each package, but leave build
                        and devel spaces.
  -s, --setup-files     Clear the catkin-generated files in order to rebase
                        onto another workspace.
  -o, --orphans         Remove only build directories whose source packages
                        are no longer enabled or in the source space. This
                        might require --force-cmake on the next build.

Viewing the Configuration Summary¶

Once a workspace has been initialized, the configuration summary can be displayed by calling catkin config without arguments from anywhere under the root of the workspace. Doing so will not modify your workspace. The catkin command is context-sensitive, so it will determine which workspace contains the current working directory.

Appending or Removing List-Type Arguments¶

Several configuration options are actually lists of values. Normally for these options, the given values will replace the current values in the configuration.

If you would only like to modify, but not replace the value of a list-type option, you can use the -a / --append-args and -r / --remove-args options to append or remove elements from these lists, respectively.

List-type options include:

• --cmake-args
• --make-args
• --catkin-make-args
• --whitelist
• --blacklist

Installing Packages¶

Without any additional arguments, packages are not “installed” using the standard CMake install() targets. Addition of the --install option will configure a workspace so that it creates an install space and write the products of all install targets to that FHS tree. The contents of the install space, which, by default, is located in a directory named install will look like the following:

$ ls ./install
_setup_util.py bin            env.sh         etc            include
lib            setup.bash     setup.sh       setup.zsh      share

Explicitly Specifying Workspace Chaining¶

Normally, a catkin workspace automatically “extends” the other workspaces that have previously been sourced in your environment. Each time you source a catkin setup file from a result-space (devel-space or install-space), it sets the $CMAKE_PREFIX_PATH in your environment, and this is used to build the next workspace. This is also sometimes referred to as “workspace chaining” and sometimes the extended workspace is referred to as a “parent” workspace.

With catkin config, you can explicitly set the workspace you want to extend, using the --extend argument. This is equivalent to sourcing a setup file, building, and then reverting to the environment before sourcing the setup file.

Note that in case the desired parent workspace is different from one already being used, using the --extend argument also necessitates cleaning the setup files from your workspace with catkin clean.

For example, regardless of your current environment variable settings (like $CMAKE_PREFIX_PATH), this will build your workspace against the /opt/ros/hydro install space.

First start with an empty CMAKE_PREFIX_PATH and initialize, build, and source a workspace:

$ echo $CMAKE_PREFIX_PATH

$ mkdir -p /tmp/path/to/my_catkin_ws/src
$ cd /tmp/path/to/my_catkin_ws
$ catkin init
--------------------------------------------------------------
Profile:                     default
Extending:                   None
Workspace:                   /tmp/path/to/my_catkin_ws
...
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------

$ cd /tmp/path/to/my_catkin_ws
$ catkin create pkg aaa
$ catkin create pkg bbb
$ catkin create pkg ccc
$ catkin build
...

$ source devel/setup.bash
$ echo $CMAKE_PREFIX_PATH
/tmp/path/to/my_catkin_ws/devel

$ catkin config
--------------------------------------------------------------
Profile:                     default
Extending:                   None
Workspace:                   /tmp/path/to/my_catkin_ws
...
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------

At this point you have a workspace which doesn’t extend anything. If you realize this after the fact, you can explicitly tell it to extend another workspace. Suppose you wanted to extend a standard ROS system install like /opt/ros/hydro. This can be done with the --extend option:

$ catkin config --extend /opt/ros/hydro
--------------------------------------------------------------
Profile:                     default
Extending:        [explicit] /opt/ros/hydro
Workspace:                   /tmp/path/to/my_catkin_ws
Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
Install Space:     [missing] /tmp/path/to/my_catkin_ws/install
DESTDIR:                     None
--------------------------------------------------------------
Isolate Develspaces:         False
Install Packages:            False
Isolate Installs:            False
--------------------------------------------------------------
Additional CMake Args:       None
Additional Make Args:        None
Additional catkin Make Args: None
--------------------------------------------------------------
Whitelisted Packages:        None
Blacklisted Packages:        None
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------

$ catkin clean --setup-files
$ catkin build
...

$ source devel/setup.bash
$ echo $CMAKE_PREFIX_PATH
/tmp/path/to/my_catkin_ws:/opt/ros/hydro

Whitelisting and Blacklisting Packages¶

Packages can be added to a package whitelist or blacklist in order to change which packages get built. If the whitelist is non-empty, then a call to catkin build with no specific package names will only build the packages on the whitelist. This means that you can still build packages not on the whitelist, but only if they are named explicitly or are dependencies of other whitelisted packages.

To set the whitelist, you can call the following command:

catkin config --whitelist foo bar

To clear the whitelist, you can use the --no-whitelist option:

catkin config --no-whitelist

If the blacklist is non-empty, it will filter the packages to be built in all cases except where a given package is named explicitly. This means that blacklisted packages will not be built even if another package in the workspace depends on them.

To set the blacklist, you can call the following command:

catkin config --blacklist baz

To clear the blacklist, you can use the --no-blacklist option:

catkin config --no-blacklist

Note that you can still build packages on the blacklist and whitelist by passing their names to catkin build explicitly.

Accelerated Building with Environment Caching¶

Each package is built in a special environment which is loaded from the current workspace and any workspaces that the current workspace is extending. If you are confident that your workspace’s environment is not changing during a build, you can tell catkin build to cache these environments with the --cache-env option. This has the effect of dramatically reducing build times for workspaces where many packages are already built.

Full Command-Line Interface¶

usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
                     [--append-args | --remove-args] [--init]
                     [--extend EXTEND_PATH | --no-extend] [--mkdirs]
                     [--whitelist PKG [PKG ...] | --no-whitelist]
                     [--blacklist PKG [PKG ...] | --no-blacklist]
                     [-s SOURCE_SPACE | --default-source-space]
                     [-b BUILD_SPACE | --default-build-space]
                     [-d DEVEL_SPACE | --default-devel-space]
                     [-i INSTALL_SPACE | --default-install-space]
                     [-x SPACE_SUFFIX]
                     [--merge-devel | --link-devel | --isolate-devel]
                     [--install | --no-install]
                     [--isolate-install | --merge-install] [-j JOBS]
                     [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
                     [--env-cache | --no-env-cache]
                     [--cmake-args ARG [ARG ...] | --no-cmake-args]
                     [--make-args ARG [ARG ...] | --no-make-args]
                     [--catkin-make-args ARG [ARG ...] |
                     --no-catkin-make-args]

This verb is used to configure a catkin workspace's configuration and layout.
Calling `catkin config` with no arguments will display the current config and
affect no changes if a config already exists for the current workspace and
profile.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --profile PROFILE     The name of a config profile to use (default: active
                        profile)

Behavior:
  Options affecting argument handling.

  --append-args, -a     For list-type arguments, append elements.
  --remove-args, -r     For list-type arguments, remove elements.

Workspace Context:
  Options affecting the context of the workspace.

  --init                Initialize a workspace if it does not yet exist.
  --extend EXTEND_PATH, -e EXTEND_PATH
                        Explicitly extend the result-space of another catkin
                        workspace, overriding the value of $CMAKE_PREFIX_PATH.
  --no-extend           Un-set the explicit extension of another workspace as
                        set by --extend.
  --mkdirs              Create directories required by the configuration (e.g.
                        source space) if they do not already exist.

Package Build Defaults:
  Packages to include or exclude from default build behavior.

  --whitelist PKG [PKG ...]
                        Set the packages on the whitelist. If the whitelist is
                        non-empty, only the packages on the whitelist are
                        built with a bare call to `catkin build`.
  --no-whitelist        Clear all packages from the whitelist.
  --blacklist PKG [PKG ...]
                        Set the packages on the blacklist. Packages on the
                        blacklist are not built with a bare call to `catkin
                        build`.
  --no-blacklist        Clear all packages from the blacklist.

Spaces:
  Location of parts of the catkin workspace.

  -s SOURCE_SPACE, --source-space SOURCE_SPACE
                        The path to the source space.
  --default-source-space
                        Use the default path to the source space ("src")
  -b BUILD_SPACE, --build-space BUILD_SPACE
                        The path to the build space.
  --default-build-space
                        Use the default path to the build space ("build")
  -d DEVEL_SPACE, --devel-space DEVEL_SPACE
                        Sets the target devel space
  --default-devel-space
                        Sets the default target devel space ("devel")
  -i INSTALL_SPACE, --install-space INSTALL_SPACE
                        Sets the target install space
  --default-install-space
                        Sets the default target install space ("install")
  -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
                        Suffix for build, devel, and install space if they are
                        not otherwise explicitly set.

Devel Space:
  Options for configuring the structure of the devel space.

  --merge-devel         Build products from each catkin package into a single
                        merged devel spaces.
  --link-devel          Build products from each catkin package into isolated
                        spaces, then symbolically link them into a merged
                        devel space.
  --isolate-devel       Build products from each catkin package into isolated
                        devel spaces.

Install Space:
  Options for configuring the structure of the install space.

  --install             Causes each package to be installed to the install
                        space.
  --no-install          Disables installing each package into the install
                        space.
  --isolate-install     Install each catkin package into a separate install
                        space.
  --merge-install       Install each catkin package into a single merged
                        install space.

Build Options:
  Options for configuring the way packages are built.

  -j JOBS, --jobs JOBS  Maximum number of build jobs to be distributed across
                        active packages. (default is cpu count)
  -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
                        Maximum number of packages allowed to be built in
                        parallel (default is cpu count)
  --jobserver           Use the internal GNU Make job server which will limit
                        the number of Make jobs across all active packages.
  --no-jobserver        Disable the internal GNU Make job server, and use an
                        external one (like distcc, for example).
  --env-cache           Re-use cached environment variables when re-sourcing a
                        resultspace that has been loaded at a different stage
                        in the task.
  --no-env-cache        Don't cache environment variables when re-sourcing the
                        same resultspace.
  --cmake-args ARG [ARG ...]
                        Arbitrary arguments which are passes to CMake. It
                        collects all of following arguments until a "--" is
                        read.
  --no-cmake-args       Pass no additional arguments to CMake.
  --make-args ARG [ARG ...]
                        Arbitrary arguments which are passes to make.It
                        collects all of following arguments until a "--" is
                        read.
  --no-make-args        Pass no additional arguments to make (does not affect
                        --catkin-make-args).
  --catkin-make-args ARG [ARG ...]
                        Arbitrary arguments which are passes to make but only
                        for catkin packages.It collects all of following
                        arguments until a "--" is read.
  --no-catkin-make-args
                        Pass no additional arguments to make for catkin
                        packages (does not affect --make-args).

Full Command-Line Interface¶

usage: catkin create [-h] {pkg} ...

Creates catkin workspace resources like packages.

positional arguments:
  {pkg}       sub-command help
    pkg       Create a new catkin package.

optional arguments:
  -h, --help  show this help message and exit

usage: catkin create pkg [-h] [-p PATH] [--rosdistro ROSDISTRO]
                         [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL]
                         [-a NAME EMAIL] [-d DESCRIPTION]
                         [--catkin-deps [DEP [DEP ...]]]
                         [--system-deps [DEP [DEP ...]]]
                         [--boost-components [COMP [COMP ...]]]
                         PKG_NAME [PKG_NAME ...]

Create a new Catkin package. Note that while the default options used by this
command are sufficient for prototyping and local usage, it is important that
any publically-available packages have a valid license and a valid maintainer
e-mail address.

positional arguments:
  PKG_NAME              The name of one or more packages to create. This name
                        should be completely lower-case with individual words
                        separated by undercores.

optional arguments:
  -h, --help            show this help message and exit
  -p PATH, --path PATH  The path into which the package should be generated.
  --rosdistro ROSDISTRO
                        The ROS distro (default: environment variable
                        ROS_DISTRO if defined)

Package Metadata:
  -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH
                        Initial package version. (default 0.0.0)
  -l LICENSE, --license LICENSE
                        The software license under which the code is
                        distributed, such as BSD, MIT, GPLv3, or others.
                        (default: "TODO")
  -m NAME EMAIL, --maintainer NAME EMAIL
                        A maintainer who is responsible for the package.
                        (default: [username, username@todo.todo]) (multiple
                        allowed)
  -a NAME EMAIL, --author NAME EMAIL
                        An author who contributed to the package. (default: no
                        additional authors) (multiple allowed)
  -d DESCRIPTION, --description DESCRIPTION
                        Description of the package. (default: empty)

Package Dependencies:
  --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]]
                        The names of one or more Catkin dependencies. These
                        are Catkin-based packages which are either built as
                        source or installed by your system's package manager.
  --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]]
                        The names of one or more system dependencies. These
                        are other packages installed by your operating
                        system's package manager.

C++ Options:
  --boost-components [COMP [COMP ...]]
                        One or more boost components used by the package.

Full Command-Line Interface¶

usage: catkin env [-h] [-i] [-s]
                  [NAME=VALUE [NAME=VALUE ...]] [COMMAND] [ARG [ARG ...]]

Run an arbitrary command in a modified environment.

positional arguments:
  NAME=VALUE            Explicitly set environment variables for the
                        subcommand. These override variables given to stdin.

optional arguments:
  -h, --help            show this help message and exit
  -i, --ignore-environment
                        Start with an empty environment.
  -s, --stdin           Read environment variable definitions from stdin.
                        Variables should be given in NAME=VALUE format.

command:
  COMMAND               Command to run. If omitted, the environment is printed
                        to stdout.
  ARG                   Arguments to the command.

Full Command-Line Interface¶

usage: catkin init [-h] [--workspace WORKSPACE] [--reset]

Initializes a given folder as a catkin workspace.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --reset               Reset (delete) all of the metadata for the given
                        workspace.

Checking for Catkin Package Warnings¶

In addition to the names of the packages in your workspace, running catkin list will output any warnings about catkin packages in your workspace. To suppress these warnings, you can use the --quiet option.

Using Unformatted Output in Shell Scripts¶

catkin list --unformatted is useful for automating shell scripts in UNIX pipe-based programs.

Full Command-Line Interface¶

usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE] [--deps]
                   [--depends-on [DEPENDS_ON [DEPENDS_ON ...]]] [--quiet]
                   [--unformatted]
                   [folders [folders ...]]

Lists catkin packages in the workspace or other arbitray folders.

positional arguments:
  folders               Folders in which to find packages. (default: workspace
                        source space)

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --profile PROFILE     The name of a config profile to use (default: active
                        profile)
  --deps, --dependencies
                        List dependencies of each package.
  --depends-on [DEPENDS_ON [DEPENDS_ON ...]]
                        List all packages that depend on supplied argument
                        package(s).
  --quiet               Don't print out detected package warnings.
  --unformatted, -u     Print list without punctuation and additional details.

Full Command-Line Interface¶

usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
                     [-r] [-s | -b | -d | -i]
                     [PACKAGE]

Get the paths to various locations in a workspace.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --profile PROFILE     The name of a config profile to use (default: active
                        profile)

Behavior:
  -e, --existing-only   Only print paths to existing directories.
  -r, --relative        Print relative paths instead of the absolute paths.

Sub-Space Options:
  Get the absolute path to one of the following locations in the given
  workspace with the given profile.

  -s, --src             Get the path to the source space.
  -b, --build           Get the path to the build space.
  -d, --devel           Get the path to the devel space.
  -i, --install         Get the path to the install space.

Package Directories:
  Get the absolute path to package directories in the given workspace and
  sub-space. By default this will output paths in the workspace's source
  space. If the -b (--build) flag is given, it will output the path to the
  package's build directory. If the -d or -i (--devel or --install) flags
  are given, it will output the path to the package's share directory in
  that space. If no package is provided, the base space paths are printed,
  e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
  -s foo` might return `/path/to/ws/src/foo`.

  PACKAGE               The name of a package to locate.

Creating Profiles Automatically¶

After initializing a workspace, you can start querying information about profiles. Until you execute a verb which actually writes a profile configuration, however, there will be no profiles listed:

$ mkdir -p /tmp/path/to/my_catkin_ws/src
$ cd /tmp/path/to/my_catkin_ws
$ catkin init
$ catkin profile list
[profile] This workspace has no metadata profiles. Any configuration
settings will automatically by applied to a new profile called `default`.

To see these effects, you can run catkin config to write a default configuration to the workspace:

$ cd /tmp/path/to/my_catkin_ws
$ catkin config
--------------------------------------------------------------
Profile:                     default
Extending:                   None
Workspace:                   /tmp/path/to/my_catkin_ws
Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
Install Space:     [missing] /tmp/path/to/my_catkin_ws/install
DESTDIR:                     None
--------------------------------------------------------------
Isolate Develspaces:         False
Install Packages:            False
Isolate Installs:            False
--------------------------------------------------------------
Additional CMake Args:       None
Additional Make Args:        None
Additional catkin Make Args: None
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
$ catkin profile list
[profile] Available profiles:
- default (active)

The profile verb now shows that the profile named “default” is avialable and is active. Calling catkin config with the --profile argument will automatically create a profile based on the given configuration options:

$ catkin config --profile alternate -x _alt
------------------------------------------------------------------
Profile:                     alternate
Extending:                   None
Workspace:                   /tmp/path/to/my_catkin_ws
Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
Build Space:       [missing] /tmp/path/to/my_catkin_ws/build_alt
Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel_alt
Install Space:     [missing] /tmp/path/to/my_catkin_ws/install_alt
DESTDIR:                     None
------------------------------------------------------------------
Isolate Develspaces:         False
Install Packages:            False
Isolate Installs:            False
------------------------------------------------------------------
Additional CMake Args:       None
Additional Make Args:        None
Additional catkin Make Args: None
------------------------------------------------------------------
Workspace configuration appears valid.
------------------------------------------------------------------
$ catkin profile list
[profile] Available profiles:
- alternate
- default (active)

Note that while the profile named alternate has been configured, it is still not active, so any calls to catkin-verbs without an explicit --profile alternate option will still use the profile named default.

Explicitly Creating Profiles¶

Profiles can also be added explicitly with the add command. This profile can be initialized with configuration information from either the default settings or another profile.

$ catkin profile list
[profile] Available profiles:
- alternate
- default (active)
$ catkin profile add alternate_2 --copy alternate
[profile] Created a new profile named alternate_2 based on profile alternate
[profile] Available profiles:
- alternate
- alternate_2
- default (active)

Setting the Active Profile¶

The active profile can be easily set with the set sub-command. Suppose a workspace has the following profiles:

$ catkin profile list
[profile] Available profiles:
- alternate
- alternate_2
- default (active)
$ catkin profile set alternate_2
[profile] Activated catkin metadata profile: alternate_2
[profile] Available profiles:
- alternate
- alternate_2 (active)
- default

Renaming and Removing Profiles¶

The profile verb can also be used for renaming and removing profiles:

$ catkin profile list
[profile] Available profiles:
- alternate
- alternate_2 (active)
- default
$ catkin profile rename alternate_2 alternate2
[profile] Renamed profile alternate_2 to alternate2
[profile] Available profiles:
- alternate
- alternate2 (active)
- default
$ catkin profile remove alterate
[profile] Removed profile: alternate
[profile] Available profiles:
- alternate2 (active)
- default

Full Command-Line Interface¶

usage: catkin profile [-h] [--workspace WORKSPACE]
                      {list,set,add,rename,remove} ...

Manage config profiles for a catkin workspace.

positional arguments:
  {list,set,add,rename,remove}
                        sub-command help
    list                List the available profiles.
    set                 Set the active profile by name.
    add                 Add a new profile by name.
    rename              Rename a given profile.
    remove              Remove a profile by name.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin workspace. Default: current
                        working directory

usage: catkin profile list [-h] [--unformatted]

optional arguments:
  -h, --help         show this help message and exit
  --unformatted, -u  Print profile list without punctuation and additional
                     details.

usage: catkin profile set [-h] name

positional arguments:
  name        The profile to activate.

optional arguments:
  -h, --help  show this help message and exit

usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name

positional arguments:
  name                 The new profile name.

optional arguments:
  -h, --help           show this help message and exit
  -f, --force          Overwrite an existing profile.
  --copy BASE_PROFILE  Copy the settings from an existing profile. (default:
                       None)
  --copy-active        Copy the settings from the active profile.

usage: catkin profile rename [-h] [-f] current_name new_name

positional arguments:
  current_name  The current name of the profile to be renamed.
  new_name      The new name for the profile.

optional arguments:
  -h, --help    show this help message and exit
  -f, --force   Overwrite an existing profile.

usage: catkin profile remove [-h] [name [name ...]]

positional arguments:
  name        One or more profile names to remove.

optional arguments:
  -h, --help  show this help message and exit

Full Command-Line Interface¶

Change to package directory in source space with cd verb.

usage: catkin cd [ARGS...]

ARGS are any valid catkin locate arguments

The source verb sources the develspace or installspace of the containing workspace.

usage: catkin source [-w /path/to/ws]

Sources setup.sh in the workspace.

optional arguments:
  -w [/path/to/ws] Source setup.sh from given workspace.

The Built-In Aliases¶

You can list the available aliases using the --list-aliases option to the catkin command. Below are the built-in aliases as displayed by this command:

$ catkin --list-aliases
b: build
bt: b --this
ls: list
install: config --install

Defining Additional Aliases¶

Verb aliases are defined in the verb_aliases subdirectory of the catkin config folder, ~/.config/catkin/verb_aliases. Any YAML files in that folder (files with a .yaml extension) will be processed as definition files.

These files are formatted as simple YAML dictionaries which map aliases to expanded expressions, which must be composed of other catkin verbs, options, or aliases:

<ALIAS>: <EXPRESSION>

For example, aliases which configure a workspace profile so that it ignores the value of the CMAKE_PREFIX_PATH environment variable, and instead extends one or another ROS install spaces could be defined as follows:

# ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
extend-sys: config --profile sys --extend /opt/ros/hydro -x _sys
extend-overlay: config --profile overlay --extend ~/ros/hydro/install -x _overlay

After defining these aliases, one could use them with optional additional options and build a given configuration profile.

$ catkin extend-overlay
$ catkin profile set overlay
$ catkin build some_package

Alias Precedence and Overriding Aliases¶

Verb alias files in the verb_aliases directory are processed in alphabetical order, so files which start with larger numbers will override files with smaller numbers. In this way you can override the built-in aliases using a file which starts with a number higher than 00-.

For example, the bt: build --this alias exists in the default alias file, 00-default-aliases.yaml, but you can create a file to override it with an alternate definition defined in a file named 01-my-aliases.yaml.

# ~/.config/catkin/verb_aliases/01-my-aliases.yaml
# Override `bt` to build with no deps
bt: build --this --no-deps

You can also disable or unset an alias by setting its value to null. For example, the ls: list alias is defined in the default aliases, but you can override it with this entry in a custom file named something like 02-unset.yaml:

# ~/.config/catkin/verb_aliases/02-unset.yaml
# Disable `ls` alias
ls: null

Recursive Alias Expansion¶

Additionally, verb aliases can be recursive, for instance in the bt alias, the b alias expands to build so that b --this expands to build --this. The catkin command shows the expansion of aliases when they are invoked so that their behavior is more transparent:

$ catkin bt
==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
...

Execution Model¶

The execution model is fairly simple. The executor executes a single task for a given command (i.e. build, clean, etc.). A task is a set of jobs which are related by an acyclic dependency graph. Each job is given a unique identifier and is composed of a set of dependencies and a sequence of executable stages, which are arbitrary functions or subprocess calls which utilize one or more workers to be executed. The allocation of workers is managed by the job server. Throughout execution, synchronization with the user-facing interface and output formatting are mediated by a simple event queue.

The executor is single-threaded and uses an asynchronous loop to execute jobs as futures. If a job contains blocking stages it can utilize a normal thread pool for execution, but is still only guaranteed one worker by the main loop of the executor. See the following section for more information on workers and the job server.

The input to the executor is a list of topologically-sorted jobs with no circular dependencies and some parameters which control the jobserver behavior. These behavior parameters are explained in detail in the following section.

Each job is in one of the following lifecycle states at any time:

• PENDING Not ready to be executed (dependencies not yet completed)
• QUEUED Ready to be executed once workers are available
• ACTIVE Being executed by one or more workers
• FINISHED Has been executed and either succeded or failed (terminal)
• ABANDONED Was not built because a prerequisite was not met (terminal)

Executor Job lifecycle

All jobs begin in the PENDING state, and any jobs with unsatisfiable dependencies are immediately set to ABANDONED, and any jobs without dependencies are immediately set to QUEUED. After the state initialization, the executor processes jobs in a main loop until they are in one of the two terminal states (FINISHED or ABANDONED).

Each main loop iteration does the following:

• While job server tokens are available, create futures for QUEUED jobs and make them ACTIVE
• Report status of all jobs to the event queue
• Retrieve ACTIVE job futures which have completed and set them FINISHED
• Check for any PENDING jobs which need to be ABANDONED due to failed jobs
• Change all PENDING jobs whose dependencies are satisifed to QUEUED

Once each job is in one of terminal states, the executor pushes a final status event and returns.

Job Server Resource Model¶

As mentioned in the previous section, each task includes a set of jobs which are activated by the job server. In order to start a queued job, at least one worker needs to be available. Once a job is started, it is assigned a single worker from the job server. These are considered top-level jobs since they are managed directly by the catkin executor. The number of top-level jobs can be configured for a given task.

Additionally to top-level paralellism, some job stages are capable of running in parallel, themselves. In such cases, the job server can interface directly with the underlying stage’s low-level job allocation. This enables multi-level parallelism without allocating more than a fixed number of jobs.

Executor Job Flow and Resource Utilization – In this snapshot of the job pipeline, the executor is executing four of six possible top-level jobs, each with three stages, and using sevel of eight total workers. Two jobs are executing subprocesses, which have side-channel communication with the job server.

One such parallel-capable stage is the GNU Make build stage. In this case, the job server implements a GNU Make job server interface, which involves reading and writing tokens from file handles passed as build flags to the Make command.

For top-level jobs, additional resources are monitored in addition to the number of workers. Both system load and memory utilization checks can be enabled to prevent overloading a system.

Executor Job Failure Behavior¶

The executor’s behavior when a job fails can be modified with the following two parameters:

• continue_on_failure Continue executing jobs even if one job fails. If this is set to false (the default), it will cause the executor to abandon all pending and queued jobs and stop after the first failure. Note that active jobs will still be allowed to complete before the executor returns.
• continue_without_deps Continue executing jobs even if one or more of their dependencies have failed. If this is set to false (the default), it will cause the executor to abandon only the jobs which depend on the failed job. If it is set to true, then it will build dependent jobs regardless.

Jobs and Job Stages¶

As mentioned above, a job is a set of dependencies and a sequence of job stages. Jobs and stages are constructed before a given task starts executing, and hold only specificaitons of what needs to be done to complete them. All stages are given a label for user introspection, a logger interface, and can either require or not require allocation of a worker from the job server.

Stage execution is performed asynchronously by Python’s asyncio module. This means that exceptions thrown in job stages are handled directly by the executor. It also means job stages can be interrupted easily through Python’s normal signal handling mechanism.

Stages can either be command stages (subprocess commands) or function stages (python functions). In either case, loggers used by stages support segmentation of stdout and stderr from job stages for both real-time introspection and logging.

Introspection via Executor Events¶

Introspection into the different asynchronously-executed components of a task is performed by a simple event queue. Events are created by the executor, loggers, and stages, and they are consumed by an output controller. Events are defined by an event identifier and a data payload, which is an arbitrary dictionary.

There are numerous events which correspond to changes in job states, but events are also used for transporting captured I/O from job stages.

Executor Event Pipeline – Above, the executor writes events to the event queue, and the I/O loggers used by function and command stages write output events as well. All of these events are handled by the output controller, which writes to the real stdout and stderr.

The modeled events include the following:

• JOB_STATUS A report of running job states,
• QUEUED_JOB A job has been queued to be executed,
• STARTED_JOB A job has started to be executed,
• FINISHED_JOB A job has finished executing (succeeded or failed),
• ABANDONED_JOB A job has been abandoned for some reason,
• STARTED_STAGE A job stage has started to be executed,
• FINISHED_STAGE A job stage has finished executing (succeeded or failed),
• STAGE_PROGRESS A job stage has executed partially,
• STDOUT A status message from a job,
• STDERR A warning or error message from a job,
• SUBPROCESS A subprocess has been created,
• MESSAGE Arbitrary string message