ROS tutorials

First, you will need to do the basic ROS tutorials. We have a few twists on it for you to follow:

catkin_make vs. catkin

There are two tools for using catkin: catkin_make and catkin (aka catkin tools). The ROS tutorials assume you use catkin_make, but we recommend using catkin. With catkin, it is easier to visualize concurrent builds, and, best of all, you do not have to be in the root directory of your workspace to run catkin build (you do if you use catkin_make).

Instead of running this command:

- catkin_create_pkg beginner_tutorials std_msgs rospy roscpp

Run this:

+ catkin create pkg beginner_tutorials --catkin-deps roscpp rospy std_msgs

And from now on, never run this:

- catkin_make

Instead, whenever you see catkin_make, run this instead:

+ catkin build

Initializing a New Workspace

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

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 ~/catkin_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.

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 ~/catkin_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 -> ~/catkin_ws/devel/.private/catkin_tools_prebuild/env.sh
│   ├── etc
│   ├── lib
│   ├── .private
│   ├── setup.bash -> ~/catkin_ws/devel/.private/catkin_tools_prebuild/setup.bash
│   ├── setup.sh -> ~/catkin_ws/devel/.private/catkin_tools_prebuild/setup.sh
│   ├── _setup_util.py -> ~/catkin_ws/devel/.private/catkin_tools_prebuild/_setup_util.py
│   ├── setup.zsh -> ~/catkin_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

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 ~/catkin_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.

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

Cheat Sheet

• catkin tool cheat sheet