A build systems is a functional program or scripts developed to automate and simplify compiling and linking source code.  A meta-build system like CMake  generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is a powerful open-source cross-platform set of tools designed to build, test and package software. ROS build systems are built on top of CMake and have evolved over the years to simplify software development in robotics.

The motivation for this article is an error encountered while attempting to build a workspace containing both catkin and rosbuild packages. The figure below shows the orocos_kdl package is plain cmake (it contains a manifest.xml file) thus it cannot be built using catkin_make. The suggestion is to use catkin_make_isolated instead.

This article reviews build systems in the order they have been used within the ROS ecosystem, ending with colcon which is currently the latest ROS build system.

rosbuild (legacy)

rosbuild is a set of scripts for managing the CMake based build system for use with ROS. The CMake wrapper script (rosmake) is what builds ROS. Most commonly used ROS packages have been updated to use the recommended catkin build system. If a ROS package contains a manifest.xml file, then it uses the rosbuild system. This file contains useful information such as the cpp cflags and a list of dependencies.

To build packages using rosbuild, simply run rosmake <package1> <package2> <package3>.

catkin_make

Most ROS users are comfortable using catkin_make to build ROS workspaces since this is the command used in most tutorials. catkin_make is a convenient way to evoke calls to cmake and make in the standard CMake workflow. The entire workspace is treated as a single CMake project which makes incremental builds faster but it is slow if build files need to be regenerated.

Limitations of catkin_make include not being able to process plain CMake packages and requiring all targets (across all packages in a workspace) to be unique. An error in a leaf package (without dependencies) will also prevent all packages from configuring.

ROS packages that use the catkin build system will contain a package.xml file.

To build a workspace using catkin_make follow these steps:

1. Check that system dependencies are met by running rosdep update  to update the dependencies database and rosdep -y install --from-paths src --ignore-src to attempt to install missing dependencies.
2. Build the workspace using  catkin_make -j2 VERBOSE=1 which will go through all the catkin projects found in the workspace src folder. A build folder (where cmake and make are invoked; and the build files and intermediate build products are stored) and a devel folder (where generated files, targets and setup.*sh files are stored) will be created.
3. Optionally, the install targets can be invoked by running  catkin_make install and an install folder will be automatically created.

catkin_make_isolated

catkin_make_isolated improves on catkin_make by building isolated workspaces (each software package is independently configured, built and installed into its own directory) instead of a merged workspace (every software package is installed into the same directory). The install artifacts of a single package can therefore be removed by simply deleting its directory. Since each package is treated as a separate CMake project, catkin_make_isolated processes all packages in the workspace sequentially and installs each package separately according to the dependency order. This decoupling of dependencies allows catkin_make_isolated to build plain CMake packages, build packages without re-configuring dependencies, and to build part of a workspace.

The improvements made by catkin_make_isolated come at a cost of speed however. This is because the building of targets and packages without co-dependencies is not parallelised.

To build a workspace using catkin_make_isolated, follow these steps:

1. Create an isolated ROS catkin workspace and add the isolated package to the catkin workspace.
2. Compile the workspace using catkin_make_isolated  which will create a devel directory containing isolated subdirectories for each package.
3. To include the isolated package within another ROS package, simple update the ROS package’s CMakeLists.txt file by adding the lines  link_directories(. ~/path/to/isolated/include/headers) and include_directories(~/path/to/isolated/libraries/). 

catkin_tools

catkin_tools is similar to catkin_make_isolated with the exception that packages are built in topological order and in parallel where possible, resulting in improved build times. Each package is treated as a separate CMake project and built separately. Common build errors are caught by utilising persistent build metadata. When running catkin build, a status line is displayed for all packages and a build summary is shown at the end which also shows any abandoned jobs (due to failed dependencies). The supported catkin_tools command line verbs are:

• catkin build – build packages
• catkin clean – clean build products
• catkin config – configure workspace settings and layout
• catkin create – create packages
• catkin env – run commands with a modified environment
• catkin init – initialise a workspace
• catkin list – list package information
• catkin locate – get workspace directory paths
• catkin profile – manage named configuration profiles
• catkin test – test packages

catkin_tools is not included in the ROS full desktop installation. To install it run sudo apt-get install ros-noetic-catkin python3-catkin-tools in terminal.

Running the catkin build --dry-run command from the workspace described at the start of this article produces the output shown in the figure below (note how a workspace containing both cmake and catkin packages is supported).

To build a workspace using catkin build follow these steps:

1. Check that system dependencies are met by running rosdep update to update the dependencies database and rosdep -y install --from-paths src --ignore-src to attempt to install missing dependencies.
2. Initialise and configure the workspace:  catkin config --init. Use catkin config --init --install  instead to configure a workspace that also creates an install space (products of all install targets will be written to separate subdirectories).
3. Preview the build to see which order packages will be built : catkin build --dry-run.
4. Build the workspace using  catkin build --interleave which will build the entire workspace and create build (contains intermediate build products for each package) and devel (contains the final build products) directories.
5. To build a specific package with its dependencies just run catkin build <package> and to build a single package without its dependencies use catkin build <package> --no-deps instead.
6. It is possible to build a workspace from a specific point. This is useful in cases where a package fails to build and you want to speed things up by building from the failure point onward.  To build from <package5> onward use catkin build --start-with <package5>.

When using ROS 1, the recommended build system is catkin_tools (which was used to fix the error shown at the beginning of this article). A brief history of catkin provides a good overview of ROS build systems.

colcon

colcon is a command line tool for building, testing and using multiple software packages.  It is the latest ROS build tool which can build different types of packages (CMake, Python setuptools, cargo, gradle etc.) on different operating systems. It is under active development for ROS 2 and also supports building ROS 1 workspaces.

Building a workspace with colcon creates build (stores intermediate files of each package in a separate subdirectory), install (install location of each package in a separate subdirectory) and log (stores logging information) directories. The universal build tool design documentation outlines the thinking behind this new improved tool.

To install colcon, run sudo apt-get install python3-colcon-common-extensions in terminal.

To build a workspace using colcon follow these steps:

1. Source an underlay (the environment for a ROS installation which contains the necessary build dependencies).
2. Build the workspace using colcon build. To also install packages (in the install directory) use colcon build --symlink-install instead.
3. Source the install directory . install/setup.bash to use the installed libraries/executables.
4. Finally, run tests for the built packages using colcon test.

colcon extensions

Several extensions that enable colcon to support build systems other than CMake are available. One example is colcon-bazel which extends colcon-core to support Bazel projects.

A overview of implementing a Bazel workspace for ROS 2, without breaking colcon support, can be found in Funk’s ROSCon2022 talk and slides. The motivation for this application was building large scale ROS 2 safety critical applications.