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

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

TL;DR¶

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

$ mkdir -p /tmp/path/to/my_catkin_ws/src      # Make a new workspace and source space
$ cd /tmp/path/to/my_catkin_ws                # Navigate to the workspace root
$ catkin init                                 # Initialize it with a hidden marker file
$ cd /tmp/path/to/my_catkin_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 build                                # Build all packages in the workspace
$ source ../devel/setup.bash                  # Load the workspace's environment
$ catkin clean --all                          # Clean the build products
$ catkin build pkg_d                          # Build `pkg_d` and its deps
$ cd /tmp/path/to/my_catkin_ws/src/pkg_c      # Navigate to `pkg_c`'s source directory
$ catkin build --this                         # Build `pkg_c` and its deps
$ catkin build --this --no-deps               # Rebuild only `pkg_c`

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:

$ 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
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.
--------------------------------------------------------------

Now the directory /tmp/path/to/my_catkin_ws 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 three trivial packages: pkg_a, pkg_b, and another_one:

$ cd /tmp/path/to/my_catkin_ws/src
$ catkin_create_pkg pkg_a
Created file pkg_a/CMakeLists.txt
Created file pkg_a/package.xml
Successfully created files in /tmp/path/to/my_catkin_ws/src/pkg_a. Please adjust the values in package.xml.
$ catkin_create_pkg pkg_b
Created file pkg_b/CMakeLists.txt
Created file pkg_b/package.xml
Successfully created files in /tmp/path/to/my_catkin_ws/src/pkg_b. Please adjust the values in package.xml.
$ catkin_create_pkg another_one
Created file another_one/CMakeLists.txt
Created file another_one/package.xml
Successfully created files in /tmp/path/to/my_catkin_ws/src/another_one. Please adjust the values in package.xml.

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

$ cd /tmp/path/to/my_catkin_ws
$ tree -aL 2
.
├── .catkin_tools
│   └── README
└── src
    ├── another_one
    ├── pkg_a
    └── pkg_b

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
--------------------------------------------------------------
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.
--------------------------------------------------------------
Found '3' packages in 0.0 seconds.
Starting ==> another_one
Starting ==> pkg_a
Starting ==> pkg_b
Finished <== pkg_b       [ 2.0 seconds ]
Finished <== another_one [ 2.0 seconds ]
Finished <== pkg_a       [ 3.4 seconds ]
[build] Finished.
[build] Runtime: 3.4 seconds

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/path/to/my_catkin_ws
$ tree -aL 1
.
├── build
├── .catkin_tools
├── devel
└── src

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/path/to/my_catkin_ws/devel/setup.bash

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 any following command:

$ catkin clean --build --devel
Removing buildspace: /tmp/path/to/my_catkin_ws/build
Removing develspace: /tmp/path/to/my_catkin_ws/devel

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

Anatomy of a Catkin Workspace¶

A standard catkin workspace, as defined by REP-0128, is a folder with a prescribed set “spaces”, each of which is normally a folder within the workspace:

• source space – default: ./src
• build space – default: ./build
• devel space – default: ./devel
• install space – default: ./install

Though there are standard conventions for the layout and names of the workspace’s various spaces, they can be renamed for a given build using the catkin config verb.

Additional Workspace Directories with catkin_tools¶

Environment Setup Files¶

In addition to the FHS folders, some setup scripts are generated in the devel space, e.g. setup.bash or setup.zsh. These setup scripts are intended to make it easier to use the resulting devel space for building on top of the packages that were just built or for running programs built by those packages. 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 the CMAKE_PREFIX_PATH, PKG_CONFIG_PATH, PATH, LD_LIBRARY_PATH, CPATH, and PYTHONPATH with local workspace folders.

The setup scripts will also execute any shell hooks exported by packages in the workspace, which is how roslib, for example, sets the ROS_PACKAGE_PATH environment variable.

Workspace Packages and Dependencies¶

A workspace’s packages consist of any packages found in the source space. A package is any folder which contains a package.xml as defined in REP-0127.

The catkin build command determines the order in which packages are built based on the depend, build_depend, run_depend, and build_type tags in a package’s package.xml file.

• The *_depend tags are used to determine the topological build order of the packages.
• The build_type tag is used to determine which build work flow to use on the package.

Packages without an explicitly defined build_type tag are assumed to be catkin packages, but 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 has been done in the past for building packages like opencv, pcl, and flann.

Understanding the Build Process¶

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

$ 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]

Workspace Chaining and the Importance of CMAKE_PREFIX_PATH¶

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.

Contents of the Config Summary¶

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
--------------------------------------------------------------
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.
--------------------------------------------------------------

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 Mode¶

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.” For more details on this see the details about workspace chaining and CMAKE_PREFIX_PATH in Workspace Mechanics.

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

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

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¶

Basic Usage¶

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

$ catkin build --dry-run
--------------------------------------------------------------
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
--------------------------------------------------------------
Whitelisted Packages:        None
Blacklisted Packages:        None
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
Found '36' packages in 0.0 seconds.
Packages to be built:
- catkin               (catkin)
- genmsg               (catkin)
- gencpp               (catkin)
- genlisp              (catkin)
- genpy                (catkin)
- console_bridge       (cmake)
- cpp_common           (catkin)
- message_generation   (catkin)
- message_runtime      (catkin)
- ros_tutorials        (metapackage)
- rosbuild             (catkin)
- rosclean             (catkin)
- roscpp_traits        (catkin)
- rosgraph             (catkin)
- roslang              (catkin)
- roslaunch            (catkin)
- rosmaster            (catkin)
- rospack              (catkin)
- roslib               (catkin)
- rosparam             (catkin)
- rospy                (catkin)
- rostime              (catkin)
- roscpp_serialization (catkin)
- rosunit              (catkin)
- rosconsole           (catkin)
- rostest              (catkin)
- std_msgs             (catkin)
- geometry_msgs        (catkin)
- rosgraph_msgs        (catkin)
- std_srvs             (catkin)
- xmlrpcpp             (catkin)
- roscpp               (catkin)
- roscpp_tutorials     (catkin)
- rosout               (catkin)
- rospy_tutorials      (catkin)
- turtlesim            (catkin)
Total packages: 36

$ catkin build roscpp_tutorials --dry-run
....
Found '36' packages in 0.1 seconds.
Packages to be built:
- catkin               (catkin)
- genmsg               (catkin)
- gencpp               (catkin)
- genlisp              (catkin)
- genpy                (catkin)
- console_bridge       (cmake)
- cpp_common           (catkin)
- message_generation   (catkin)
- message_runtime      (catkin)
- rosbuild             (catkin)
- roscpp_traits        (catkin)
- roslang              (catkin)
- rospack              (catkin)
- roslib               (catkin)
- rostime              (catkin)
- roscpp_serialization (catkin)
- rosunit              (catkin)
- rosconsole           (catkin)
- std_msgs             (catkin)
- rosgraph_msgs        (catkin)
- xmlrpcpp             (catkin)
- roscpp               (catkin)
- roscpp_tutorials     (catkin)
Total packages: 23

$ catkin build roscpp_tutorials --start-with roscpp_tutorials --dry-run
....
Found '36' packages in 0.0 seconds.
Packages to be built:
(skip) catkin               (catkin)
(skip) genmsg               (catkin)
(skip) gencpp               (catkin)
(skip) genlisp              (catkin)
(skip) genpy                (catkin)
(skip) console_bridge       (cmake)
(skip) cpp_common           (catkin)
(skip) message_generation   (catkin)
(skip) message_runtime      (catkin)
(skip) rosbuild             (catkin)
(skip) roscpp_traits        (catkin)
(skip) roslang              (catkin)
(skip) rospack              (catkin)
(skip) roslib               (catkin)
(skip) rostime              (catkin)
(skip) roscpp_serialization (catkin)
(skip) rosunit              (catkin)
(skip) rosconsole           (catkin)
(skip) std_msgs             (catkin)
(skip) rosgraph_msgs        (catkin)
(skip) xmlrpcpp             (catkin)
(skip) roscpp               (catkin)
------ roscpp_tutorials     (catkin)
Total packages: 23

$ catkin build roscpp_tutorials --no-deps roscpp_tutorials --dry-run
....
Found '36' packages in 0.0 seconds.
Packages to be built:
- roscpp_tutorials     (catkin)
Total packages: 1

$ catkin build
Creating buildspace directory, '/tmp/path/to/my_catkin_ws/build'
--------------------------------------------------------------
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
--------------------------------------------------------------
Whitelisted Packages:        None
Blacklisted Packages:        None
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
Found '36' packages in 0.0 seconds.
Starting ==> catkin
Starting ==> console_bridge
Finished <== catkin [ 2.4 seconds ]

....

[build] Finished.
[build] Runtime: 3 minutes and 54.6 seconds

$ ls ./*
./build:
catkin               genlisp              message_runtime      roscpp
rosgraph_msgs        rosout               rostest              turtlesim
build_logs           genmsg               ros_tutorials
roscpp_serialization roslang              rospack              rostime
xmlrpcpp             console_bridge       genpy                rosbuild
roscpp_traits        roslaunch            rosparam             rosunit
cpp_common           geometry_msgs        rosclean
roscpp_tutorials     roslib               rospy                std_msgs
gencpp               message_generation   rosconsole           rosgraph
rosmaster            rospy_tutorials      std_srvs

./devel:
_setup_util.py bin            env.sh         etc            include
lib            setup.bash     setup.sh       setup.zsh      share

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

Context-Aware Building¶

In addition to building all packages or specified packages with various dependency requirements, catkin build can also determine the package containing the current working directory. This is equivalent to specifying the name of the package on the command line, and is done by passing the --this option to catkin build like the following:

$ cd /tmp/path/to/my_catkin_ws/src/roscpp_tutorials
$ catkin build --this --dry-run
....
Found '36' packages in 0.0 seconds.
Packages to be built:
- roscpp_tutorials     (catkin)
Total packages: 1

Controlling the Number of Build Jobs¶

By default catkin build on a computer with N cores will build up to N packages in parallel and will distribute N make jobs among them using an internal jobserver. If your platform doesn’t support jobserver scheduling, catkin build will pass -jN -lN to make for each package.

You can control the maximum number of packages allowed to build in parallel by using the -p or --parallel-packages option and you can change the number of make jobs available with the -j or --jobs option.

By default, these jobs options aren’t passed to the underlying make command. To disable the jobserver, you can use the --no-jobserver option, and you can pass flags directly to make with the --make-args option.

Controlling Command-Line Output¶

[build - 5.9] [genmsg - 1.3] [message_runtime - 0.7] ...        [4/4 Active | 3/36 Completed]

Starting ==> genmsg
Finished <== genmsg [ 2.4 seconds ]

Starting ==> catkin

[catkin]: ==> '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/local/bin/cmake /path/to/my_catkin_ws/src/catkin -DCATKIN_DEVEL_PREFIX=/path/to/my_catkin_ws/devel/catkin -DCMAKE_INSTALL_PREFIX=/path/to/my_catkin_ws/install' in '/path/to/my_catkin_ws/build/catkin'
-- The C compiler identification is Clang 5.0.0
-- The CXX compiler identification is Clang 5.0.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Using CATKIN_DEVEL_PREFIX: /path/to/my_catkin_ws/devel/catkin
-- Using CMAKE_PREFIX_PATH: /path/to/my_catkin_ws/install
-- This workspace overlays: /path/to/my_catkin_ws/install
-- Found PythonInterp: /usr/bin/python (found version "2.7.5")
-- Using PYTHON_EXECUTABLE: /usr/bin/python
-- Python version: 2.7
-- Using default Python package layout
-- Found PY_em: /Library/Python/2.7/site-packages/em.pyc
-- Using CATKIN_ENABLE_TESTING: ON
-- Call enable_testing()
-- Using CATKIN_TEST_RESULTS_DIR: /path/to/my_catkin_ws/build/catkin/test_results
-- Found gtest: gtests will be built
-- catkin 0.5.86
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/my_catkin_ws/build/catkin
[catkin]: <== '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/local/bin/cmake /path/to/my_catkin_ws/src/catkin -DCATKIN_DEVEL_PREFIX=/path/to/my_catkin_ws/devel/catkin -DCMAKE_INSTALL_PREFIX=/path/to/my_catkin_ws/install' finished with return code '0'

[catkin]: ==> '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make -j4 -l4' in '/path/to/my_catkin_ws/build/catkin'
[catkin]: <== '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make -j4 -l4' finished with return code '0'

[catkin]: ==> '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make install' in '/path/to/my_catkin_ws/build/catkin'
Install the project...
-- Install configuration: ""
... truncated for brevity
[catkin]: <== '/path/to/my_catkin_ws/build/catkin/build_env.sh /usr/bin/make install' finished with return code '0'

Finished <== catkin [ 3.4 seconds ]

[roscpp_traits]: ==> '/Users/william/my_catkin_ws/build/roscpp_traits/build_env.sh /usr/bin/make cmake_check_build_system' in '/Users/william/my_catkin_ws/build/roscpp_traits'
[ros_tutorials]: -- The CXX compiler identification is Clang 5.0.0
[ros_tutorials]: -- Check for working C compiler: /usr/bin/cc
[roscpp_traits]: ==> '/Users/william/my_catkin_ws/build/roscpp_traits/build_env.sh /usr/bin/make -j4 -l4' in '/Users/william/my_catkin_ws/build/roscpp_traits'
[rosbuild]: ==> '/Users/william/my_catkin_ws/build/rosbuild/build_env.sh /usr/bin/make -j4 -l4' in '/Users/william/my_catkin_ws/build/rosbuild'
[rosclean]: -- The C compiler identification is Clang 5.0.0
[ros_tutorials]: -- Check for working C compiler: /usr/bin/cc -- works
[ros_tutorials]: -- Detecting C compiler ABI info
[rosclean]: -- The CXX compiler identification is Clang 5.0.0
[rosclean]: -- Check for working C compiler: /usr/bin/cc

Running Tests Built in a Workspace¶

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.

Building With Warnings¶

It can sometimes be useful to compile with additional warnings enabled across your whole catkin workspace. To achieve this, use a command similar to this:

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

This command passes the -DCMAKE_C_FLAGS=... arugment to all invocations of cmake.

Debugging Build Errors¶

As mentioned above, by default the output from each build is optimistically hidden to give a clean overview of the workspace build, but when there is a problem with a build a few things happen.

First, the package with a failure prints the failing command’s output to the screen between some enclosing lines:

[rospack]: ==> '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' in '/path/to/my_catkin_ws/build/rospack'
[ 66%] Built target rospack
make[1]: *** [CMakeFiles/rosstackexe.dir/all] Interrupt: 2
make[1]: *** [CMakeFiles/rospackexe.dir/all] Interrupt: 2
make: *** [all] Interrupt: 2
[rospack]: <== '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' failed with return code '-2'

And the status line is updated to reflect that that package has run into an issue by placing a ! in front of it:

[build - 1.7] [!cpp_common] [!rospack] [genlisp - 0.3]        [1/1 Active | 10/23 Completed]

Then the catkin build command waits for the rest of the currently still building packages to finish (without starting new package builds) and then summarizes the errors for you:

[build] There were '2' errors:

Failed to build package 'cpp_common' because the following command:

    # Command run in directory: /path/to/my_catkin_ws/build/cpp_common
    /path/to/my_catkin_ws/build/cpp_common/build_env.sh /usr/bin/make -j4 -l4

Exited with return code: -2

Failed to build package 'rospack' because the following command:

    # Command run in directory: /path/to/my_catkin_ws/build/rospack
    /path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4

Exited with return code: -2
Build summary:
 Successful catkin
 Successful genmsg
 ...
 Failed     cpp_common
 Failed     rospack
 Not built  roscpp_serialization
 Not built  roscpp
 ...

Packages marked as Not built were requested, but not yet built because catkin stopped due to failed packages.

To try to build as many requested packages as possible (instead of stopping after the first package failed), you can pass the --continue-on-failure option. Then the catkin build command will then continue building packages whose dependencies built successfully

If you don’t want to scroll back up to find the error amongst the other output, you can cat the whole build log out of the build_logs folder in the build space:

$ cat build/build_logs/rospack.log
[rospack]: ==> '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make cmake_check_build_system' in '/path/to/my_catkin_ws/build/rospack'
[rospack]: <== '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make cmake_check_build_system' finished with return code '0'
[rospack]: ==> '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' in '/path/to/my_catkin_ws/build/rospack'
[ 66%] Built target rospack
make[1]: *** [CMakeFiles/rosstackexe.dir/all] Interrupt: 2
make[1]: *** [CMakeFiles/rospackexe.dir/all] Interrupt: 2
make: *** [all] Interrupt: 2
[rospack]: <== '/path/to/my_catkin_ws/build/rospack/build_env.sh /usr/bin/make -j4 -l4' failed with return code '-2'

Full Command-Line Interface¶

usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
                    [--dry-run] [--this] [--no-deps]
                    [--start-with PKGNAME | --start-with-this | --continue-on-failure]
                    [--force-cmake] [--no-install-lock] [--save-config]
                    [--parallel-jobs PARALLEL_JOBS]
                    [--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] [--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.

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.
  --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.
  --no-install-lock     Prevents serialization of the install steps, which is
                        on by default to prevent file install collisions

Config:
  Parameters for the underlying buildsystem.

  --save-config         Save any configuration options in this section for the
                        next build invocation.
  --parallel-jobs PARALLEL_JOBS, --parallel PARALLEL_JOBS, -p PARALLEL_JOBS
                        Maximum number of packages which could be built in
                        parallel (default is cpu count)
  --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.
  --no-notify           Suppresses system popup notification.

Full Command-Line Interface¶

usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE] [-a] [-b]
                    [-d] [-i] [-c] [-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.

  -c, --cmake-cache     Clear the CMakeCache for each package, but leave build
                        and devel spaces.
  -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:

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:

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.

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] [--isolate-devel | --merge-devel]
                     [--install | --no-install]
                     [--isolate-install | --merge-install]
                     [--parallel-jobs PARALLEL_JOBS]
                     [--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.

  --isolate-devel       Build products from each catkin package into isolated
                        devel spaces.
  --merge-devel         Build products from each catkin package into a single
                        merged 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.

  --parallel-jobs PARALLEL_JOBS, --parallel PARALLEL_JOBS, -p PARALLEL_JOBS
                        Maximum number of packages which could be built in
                        parallel (default is cpu count)
  --cmake-args ARG [ARG ...]
                        Arbitrary arguments which are passes to CMake. It must
                        be passed after other arguments since it collects all
                        following options.
  --no-cmake-args       Pass no additional arguments to CMake.
  --make-args ARG [ARG ...]
                        Arbitrary arguments which are passes to make.It must
                        be passed after other arguments since it collects all
                        following options.
  --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 must be passed after other
                        arguments since it collects all following options.
  --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 a catkin workspace

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

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

usage: catkin create pkg [-h] [--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 ...]]]
                         PKGNAME

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:
  PKGNAME               The name of the package 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
  --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 init [-h] [--workspace WORKSPACE] [--profile PROFILE] [--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] [--deps] [--depends-on [DEPENDS_ON [DEPENDS_ON ...]]]
                   [folders [folders ...]]

Lists catkin packages in the workspace or other arbitray folders.

positional arguments:
  folders               Folders in which to find packages. (default: cwd)

optional arguments:
  -h, --help            show this help message and exit
  --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.

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 metadata 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]

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

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

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'
...