colcon
colcon – definition
colcon is a command-line build, test, and workspace management tool used primarily in ROS 2 development. It discovers software packages in a workspace, determines their dependency order, and invokes the build system declared by each package. In a standard ROS 2 workspace, colcon commonly builds ament_cmake C++ packages and ament_python Python packages.
colcon is not itself a compiler or a ROS middleware component. It orchestrates tools such as CMake, Python packaging utilities, and test frameworks. Its plugin architecture also allows support for package formats and build systems outside ROS 2. The ROS 2 documentation specifies colcon as the standard command-line workflow for building workspaces in current ROS 2 distributions.
For mobile robotics, colcon is used to compile and deploy packages that implement UGV control, sensor drivers, robot descriptions, navigation, SLAM, perception, and diagnostics. A Leo Rover project may use colcon to build a differential-drive controller, a LiDAR driver, a Nav2 configuration package, and a URDF description in one workspace. The same workflow applies to Raph Rover projects, where the workspace can additionally contain payload-specific drivers or perception nodes.
How colcon works in a ROS 2 workspace
A ROS 2 workspace normally separates source code, build artifacts, installed files, and logs. Developers place repositories in the src/ directory and run colcon from the workspace root. During a build, colcon reads package metadata from package.xml, resolves local dependency order, configures packages, builds them, installs their outputs, and writes logs.
The conventional workspace directories have distinct functions:
src/– source repositories and ROS package directories.build/– intermediate build-system output, including CMake cache files.install/– installed executables, launch files, libraries, Python modules, and environment setup scripts.log/– build, test, and event logs generated by colcon.
The install/setup.bash script is important in ROS 2. Sourcing it extends the shell environment so that ROS 2 can locate packages, executables, launch files, and interfaces built in the workspace. This makes the workspace an overlay on top of an underlay, such as an installed ROS 2 distribution.
mkdir -p ~/ugv_ws/src
cd ~/ugv_ws
colcon build --symlink-install
source install/setup.bash
ros2 pkg list | grep rover
ros2 launch rover_bringup bringup.launch.pyThe --symlink-install option is commonly used during development. It creates symbolic links for installable resources where supported, reducing the need to rebuild after edits to Python scripts, launch files, configuration files, or other non-compiled assets. C++ source changes still require compilation.
Package metadata and build types
colcon uses package metadata to identify packages and dependencies. ROS 2 packages normally declare metadata in package.xml. Package format 3 is defined by REP 149, published by the ROS community. A package also declares its build type through an export entry.
<export>
<build_type>ament_cmake</build_type>
</export>Two build types are especially relevant in UGV software stacks:
| Build type | Typical use in mobile robotics | Build mechanism |
|---|---|---|
ament_cmake |
C++ nodes, hardware interfaces, LiDAR processing, image processing, ROS 2 control components | CMake invoked through ament tooling |
ament_python |
Python nodes, experiment scripts, mission logic, data collection, prototyping | Python package installation through setuptools-compatible metadata |
A workspace may contain both types. For example, a Leo Rover navigation workspace can compile a C++ node that processes encoder and IMU data while installing Python scripts that start repeatable mapping experiments.
Useful colcon commands for UGV development
Large robotics workspaces may contain many packages. Selective builds reduce iteration time and isolate failures. The following commands are useful when integrating sensors or modifying one part of a navigation stack.
# Build one package and its dependencies
colcon build --packages-up-to rover_navigation
# Rebuild one modified package
colcon build --packages-select rover_sensor_bringup
# Show packages detected in src/
colcon list
# Run tests after a build
colcon test --packages-select rover_navigation
colcon test-result --verbose--packages-up-to selects a target package and the packages it depends on within the workspace. --packages-select targets named packages only. This distinction matters when a modified ROS 2 driver depends on locally developed message definitions or utility libraries.
Use on Leo Rover and Raph Rover
Leo Rover can run ROS 2 on its onboard Raspberry Pi compute unit, with the available ROS 2 distribution depending on the installed operating system image and software configuration. colcon can be used to build source-based ROS 2 packages directly on the robot or to prepare a compatible workspace in a deployment image. As Leo Rover is a four-wheel differential-drive platform, a typical workspace includes robot state publishing, velocity command handling, odometry, sensor integration, and navigation configuration.
For a LiDAR and IMU integration, a project can separate responsibilities into packages such as:
rover_description– URDF/Xacro files and static transforms.rover_sensors– LiDAR, IMU, camera, GPS, or RTK driver configuration.rover_localization– EKF configuration and coordinate-frame setup.rover_navigation– Nav2 parameters, maps, behavior trees, and launch files.
Raph Rover projects use the same ROS 2 and colcon model. Depending on the payload and compute configuration, they may require additional packages for sensor payloads, compute units, or field-specific inspection equipment. colcon does not impose a hardware limit. Build time and memory use depend on the selected compute platform, compiler, dependency graph, and enabled packages.
Limitations and practical considerations
colcon does not validate sensor calibration, TF frame correctness, real-time behavior, or navigation safety. A successful build only confirms that the selected build and test steps completed according to package configuration. Runtime verification remains necessary for UGV systems.
After changing ROS interface definitions, CMake configuration, dependencies, or generated-message packages, a clean rebuild may be required. Developers can remove affected build output or rebuild the whole workspace when dependency state is uncertain.
cd ~/ugv_ws
rm -rf build/ install/ log/
colcon build --symlink-installROS 1 and ROS 2 workflows differ. ROS 1 commonly uses catkin_make or catkin_tools, while ROS 2 documentation uses colcon with ament-based packages. ROS 2 distribution support and release status are maintained in REP 2000.