Skip to main content

​
Overview

Colcon is the build tool used in ROS2 to build packages. It handles dependencies, parallel builds, and workspace management.

​
Basic commands

​
Build workspace

colcon build
Default behavior:
  • Builds all packages in src/
  • Installs to install/
  • Creates build/ and log/ directories
  • Uses all available CPU cores
colcon build --symlink-install
Recommended for development:
  • Creates symlinks instead of copying files
  • Changes to Python scripts and launch files take effect immediately
  • No rebuild needed for non-compiled changes
  • Used by the cb alias

​
Clean and build

rm -rf build install log
colcon build --symlink-install
When to use:
  • After changing CMakeLists.txt
  • After changing package.xml
  • When build is corrupted
  • When switching branches with different dependencies

​
Build options

​
Build specific packages

colcon build --packages-select <package_name>
Example: 
colcon build --packages-select turtlebot3_gazebo
Multiple packages: 
colcon build --packages-select turtlebot3_gazebo turtlebot3_teleop

​
Build package and dependencies

colcon build --packages-up-to <package_name>
Example: 
colcon build --packages-up-to turtlebot3_navigation2
Builds the package and all its dependencies.

​
Skip packages

colcon build --packages-skip <package_name>
Example: 
colcon build --packages-skip turtlebot3_fake_node

​
Continue on error

colcon build --continue-on-error
Continues building other packages even if some fail.

​
Parallel build options

​
Limit parallel workers

colcon build --parallel-workers 2
When to use:
  • Limited RAM (reduce workers to avoid OOM)
  • Limited CPU cooling
  • To reduce system load
Default: Uses all available CPU cores

​
Single-threaded build

colcon build --parallel-workers 1
When to use:
  • Debugging build issues
  • Very limited resources

​
CMake options

​
Build type

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
Build types:
  • Release: Optimized, no debug symbols (recommended for production)
  • Debug: Debug symbols, no optimization (for debugging)
  • RelWithDebInfo: Optimized with debug symbols
  • MinSizeRel: Optimized for size
Default in post-start.sh: Release

​
Export compile commands

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
Use case: Enables better IDE integration (code completion, analysis)

​
Custom CMake arguments

colcon build --cmake-args -DBUILD_TESTING=OFF
Pass any CMake argument to all packages.

​
Output options

​
Verbose output

colcon build --event-handlers console_direct+
Shows all build output in real-time (useful for debugging).

​
Less verbose output

colcon build --event-handlers console_cohesion+
Groups output by package (default behavior).

​
Log to file only

colcon build --event-handlers log-
Suppresses console output, logs only to files.

​
Test commands

​
Build with tests

colcon build
Tests are built by default.

​
Build without tests

colcon build --cmake-args -DBUILD_TESTING=OFF

​
Run tests

colcon test
Runs all tests in the workspace.

​
Test specific package

colcon test --packages-select <package_name>

​
Show test results

colcon test-result --all
Displays summary of test results.

​
Verbose test results

colcon test-result --all --verbose
Shows detailed test output.

​
Workspace information

​
List packages

colcon list
Lists all packages in the workspace.

​
List with paths

colcon list -p
Example output: 
DynamixelSDK    /workspace/turtlebot3_ws/src/DynamixelSDK
turtlebot3      /workspace/turtlebot3_ws/src/turtlebot3/turtlebot3

​
List packages topologically

colcon list --topological-order
Shows packages in dependency order (dependencies first).

​
List packages by name pattern

colcon list --packages-select-regex "turtlebot3.*"

​
Advanced usage

​
Build with sanitizers

colcon build --cmake-args \
  -DCMAKE_CXX_FLAGS="-fsanitize=address -fsanitize=undefined" \
  -DCMAKE_BUILD_TYPE=Debug
Use case: Memory leak and undefined behavior detection

​
Custom install prefix

colcon build --install-base /custom/path/install
Default: ./install

​
Custom build directory

colcon build --build-base /custom/path/build
Default: ./build

​
Merge install

colcon build --merge-install
Installs all packages into a single directory instead of separate directories.

​
Common workflows

​
Full clean rebuild

rm -rf build install log
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
Used by post-start.sh on first build.

​
Quick incremental build

colcon build --symlink-install
Rebuild only changed packages.

​
Build single package for testing

colcon build --packages-select my_package
source install/setup.bash
ros2 run my_package my_node

​
Debug build with verbose output

colcon build \
  --packages-select my_package \
  --cmake-args -DCMAKE_BUILD_TYPE=Debug \
  --event-handlers console_direct+

​
Production release build

rm -rf build install log
colcon build \
  --cmake-args \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_TESTING=OFF

​
Environment sourcing

After building, source the workspace:

​
Source workspace

source install/setup.bash
Or use the alias: 
sb

​
Check sourced workspace

echo $AMENT_PREFIX_PATH
Should include /workspace/turtlebot3_ws/install.

​
Source in every terminal

Add to ~/.bashrc (already done by post-create.sh): 
if [ -f /workspace/turtlebot3_ws/install/setup.bash ]; then
    source /workspace/turtlebot3_ws/install/setup.bash
fi

​
Build logs

​
Log locations

log/
├── latest -> latest_build/
├── latest_build/
│   ├── events.log
│   ├── logger_all.log
│   └── <package_name>/
│       ├── stdout.log
│       ├── stderr.log
│       └── streams.log

​
View build logs

cat log/latest_build/logger_all.log

​
View package-specific logs

cat log/latest_build/turtlebot3_gazebo/stdout.log
cat log/latest_build/turtlebot3_gazebo/stderr.log

​
View test logs

cat log/latest_test/logger_all.log

​
Troubleshooting

​
Build fails with no clear error

Try verbose output: 
colcon build --event-handlers console_direct+

​
CMake cache issues

Clean build directory: 
rm -rf build
colcon build

​
Package not found after build

Source the workspace: 
source install/setup.bash

​
Dependency issues

Update dependencies: 
rosdep update
rosdep install --from-paths src --ignore-src -r -y

​
Out of memory during build

Limit parallel workers: 
colcon build --parallel-workers 1
Don’t use symlink install: 
colcon build
Note: Requires rebuild after any file changes.

​
Performance tips

​
Use ccache

Install ccache for faster rebuilds: 
sudo apt-get install ccache
Add to ~/.bashrc: 
export PATH="/usr/lib/ccache:$PATH"

​
Limit memory usage

colcon build --parallel-workers $(( $(nproc) / 2 ))
Uses half the available cores to reduce memory pressure.

​
Use mold linker

For faster linking: 
sudo apt-get install mold
colcon build --cmake-args -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=mold"

​
Integration with aliases

The cb alias is defined as: 
alias cb='cd /workspace/turtlebot3_ws && colcon build --symlink-install'
You can pass additional arguments: 
cb --packages-select turtlebot3_gazebo
cb --cmake-args -DCMAKE_BUILD_TYPE=Debug
cb --parallel-workers 2

​
Common colcon arguments

ArgumentDescription
--symlink-installUse symlinks instead of copying files
--packages-selectBuild only specified packages
--packages-up-toBuild package and dependencies
--packages-skipSkip specified packages
--parallel-workers NLimit parallel jobs to N
--cmake-argsPass arguments to CMake
--event-handlersControl output verbosity
--continue-on-errorDon’t stop on first error
--build-baseCustom build directory
--install-baseCustom install directory

​
References

Build docs developers (and LLMs) love

Get started for freeTalk to us