Using Colcon to build packages¶
Table of Contents
This a brief tutorial of how to create and build a ROS workspace with
It is a practical tutorial and not designed to replace the core documentation.
ROS 2 releases before Bouncy were using
ament_tools described in the ament tutorial.
colcon is an iteration on the ROS build tools
For more information on the design of colcon see this document.
The source code can be found in the colcon GitHub organization.
sudo apt install python3-colcon-common-extensions
python3 -m pip install colcon-common-extensions
pip install -U colcon-common-extensions
A ROS workspace is a directory with a particular structure.
Commonly there is a
Inside that subdirectory is where the source code of ROS packages will be located.
Typically the directory starts otherwise empty.
colcon does out of source builds.
By default it will create the following directories as peers of the
builddirectory will be where intermediate files are stored. For each package a subfolder will be created in which e.g. CMake is being invoked.
installdirectory is where each package will be installed to. By default each package will be installed into a separate subdirectory.
logdirectory contains various logging information about each colcon invocation.
Compared to catkin there is no
First, create a directory (
ros2_example_ws) to contain our workspace:
mkdir -p ~/ros2_example_ws/src cd ~/ros2_example_ws
md \dev\ros2_example_ws\src cd \dev\ros2_example_ws
At this point the workspace contains a single empty directory
. └── src 1 directory, 0 files
Let’s clone the examples repository into the
src directory of the workspace:
git clone https://github.com/ros2/examples src/examples
It is recommended to checkout a branch that is compatible with the version of ROS that was installed (e.g.
cd ~/ros2_example_ws/src/examples/ git checkout $ROS_DISTRO cd ~/ros2_example_ws
Now the workspace should have the source code to the ROS 2 examples:
. └── src └── examples ├── CONTRIBUTING.md ├── LICENSE ├── rclcpp ├── rclpy └── README.md 4 directories, 3 files
It is important that we have sourced the environment for an existing ROS 2 installation that will provide our workspace with the necessary build dependencies for the example packages. This is achieved by sourcing the setup script provided by a binary installation or a source installation, ie. another colcon workspace (see Installation). We call this environment an underlay.
ros2_examples_ws, will be an overlay on top of the existing ROS 2 installation.
In general, it is recommended to use an overlay when you plan to iterate on a small number of packages, rather than putting all of your packages into the same workspace.
To build packages on Windows you need to be in a Visual Studio environment, see Building the ROS 2 Code for more details.
In the root of the workspace, run
Since build types such as
ament_cmake do not support the concept of the
devel space and require the package to be installed, colcon supports the option
This allows the installed files to be changed by changing the files in the
source space (e.g. Python files or other not compiled resourced) for faster iteration.
colcon build --symlink-install
After the build is finished, we should see the
. ├── build ├── install ├── log └── src 4 directories, 0 files
When colcon has completed building successfully the output will be in the
To use the executables and libraries you need to e.g. add the
install/bin directory to your path.
colcon will have generated bash/bat files in the
install directory to help setup the environment.
These files will both add the required elements to your path and library paths as well as provide any exported bash or shell commands exported by packages.
With the environment sourced we can run executables built by colcon. Let’s run a subscriber node from the examples:
ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function
In another terminal, let’s run a publisher node (don’t forget to source the setup script):
ros2 run examples_rclcpp_minimal_publisher publisher_member_function
You should see messages from the publisher and subscriber with numbers incrementing.
colcon supports multiple build types.
The recommended build types are
Also supported are pure
An example of an
ament_python build is the ament_index_python package , where the setup.py is the primary entry point for building.
A package such as demo_nodes_cpp uses the
ament_cmake build type, and uses CMake as the build tool.
For convenience, you can use the tool
ros2 pkg create to create a new package based on a template.
catkin users, this is the equivalent of
If you do not want to build a specific package place an empty file named
COLCON_IGNOREin the directory and it will not be indexed.
If you want to avoid configuring and building tests in CMake packages you can pass:
If you want to run a single particular test from a package:
colcon test --packages-select YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG