Quickstart

This chapter gives a high-level overview of how to use catkin_tools and the catkin command. This shows how to use the different command verbs to create and manipulate a workspace. For a more in-depth explanation of the mechanics of catkin workspaces, see Workspace Mechanics, and for thorough usage details see the individual verb documentation.

TL;DR

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

source /opt/ros/noetic/setup.bash          # Source ROS noetic 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                               # 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/noetic/setup.bash          # Source ROS noetic 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 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 Workspace Configuration. For information on manipulating these options, see the config verb.

Note

Calling catkin init “marks” a directory path by creating a hidden directory called .catkin_tools. This hidden directory is used to designate the parent as the root of a Catkin workspace as well as store persistent information about the workspace configuration.

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 following (to two levels deep):

cd /tmp/quickstart_ws # Navigate to the workspace root
tree -aL 2            # Show prebuild directory tree
.
├── .catkin_tools
│   ├── CATKIN_IGNORE
│   ├── profiles
│   ├── README
│   └── VERSION
└── src
    ├── pkg_a
    ├── pkg_b
    ├── pkg_c
    └── pkg_d

7 directories, 3 files

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

Note

Catkin utilizes an “out-of-source” and “aggregated” build pattern. This means that temporary or final build products will never be placed in a package’s source directory (or anywhere in the source space. Instead all build directories are aggregated in the build space and all final build products like executables, libraries, etc., will be put in the devel space.

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 (up 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_prebuild
│   ├── .catkin_tools.yaml
│   ├── pkg_a
│   ├── pkg_b
│   ├── pkg_c
│   └── pkg_d
├── .catkin_tools
│   ├── CATKIN_IGNORE
│   ├── profiles
│   ├── README
│   └── VERSION
├── devel
│   ├── .built_by
│   ├── .catkin
│   ├── env.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/env.sh
│   ├── etc
│   ├── lib
│   ├── .private
│   ├── setup.bash -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.bash
│   ├── setup.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.sh
│   ├── _setup_util.py -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/_setup_util.py
│   ├── setup.zsh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.zsh
│   └── share
├── logs
│   ├── catkin_tools_prebuild
│   ├── pkg_a
│   ├── pkg_b
│   ├── pkg_c
│   └── pkg_d
└── src
    ├── pkg_a
    ├── pkg_b
    ├── pkg_c
    └── pkg_d

24 directories, 14 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, its 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.

Note

Any time the member packages change in your workspace, you will need to re-run the source command.

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 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                               # Clean all the build products

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