Skip to content

Advanced usage of colcon#

This page shows some advanced and useful usage of colcon. If you need more detailed information, refer to the colcon documentation.

Common mistakes#

Do not run from other than the workspace root#

It is important that you always run colcon build from the workspace root because colcon builds only under the current directory. If you have mistakenly built in a wrong directory, run rm -rf build/ install/ log/ to clean the generated files.

Do not unnecessarily overlay workspaces#

colcon overlays workspaces if you have sourced the setup.bash of other workspaces before building a workspace. You should take care of this especially when you have multiple workspaces.

Run echo $COLCON_PREFIX_PATH to check whether workspaces are overlaid. If you find some workspaces are unnecessarily overlaid, remove all built files, restart the terminal to clean environment variables, and re-build the workspace.

For more details about workspace overlaying, refer to the ROS 2 documentation.

Cleaning up the build artifacts#

colcon sometimes causes errors of because of the old cache. To remove the cache and rebuild the workspace, run the following command:

rm -rf build/ install/

In case you know what packages to remove:

rm -rf {build,install}/{package_a,package_b}

Selecting packages to build#

To just build specified packages:

colcon build --packages-select <package_name1> <package_name2> ...

To build specified packages and their dependencies recursively:

colcon build --packages-up-to <package_name1> <package_name2> ...

You can also use these options for colcon test.

Changing the optimization level#

Set DCMAKE_BUILD_TYPE to change the optimization level.

Warning

If you specify DCMAKE_BUILD_TYPE=Debug or no DCMAKE_BUILD_TYPE is given for building the entire Autoware, it may be too slow to use.

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug

colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

Changing the default configuration of colcon#

Create $COLCON_HOME/defaults.yaml to change the default configuration.

mkdir -p ~/.colcon
cat << EOS > ~/.colcon/defaults.yaml
{
    "build": {
        "symlink-install": true
    }
}

For more details, see here.

Generating compile_commands.json#

compile_commands.json is used by IDEs/tools to analyze the build dependencies and symbol relationships.

You can generate it with the flag DCMAKE_EXPORT_COMPILE_COMMANDS=1:

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1

Seeing compiler commands#

To see the compiler and linker invocations for a package, use VERBOSE=1 and --event-handlers console_cohesion+:

VERBOSE=1 colcon build --packages-up-to <package_name> --event-handlers console_cohesion+

For other options, see here.

Using Ccache to speed up recompilation#

Ccache is a compiler cache that can significantly speed up recompilation by caching previous compilations and reusing them when the same compilation is being done again. It's highly recommended for developers looking to optimize their build times, unless there's a specific reason to avoid it.

Step 1: Install Ccache#

sudo apt update && sudo apt install ccache

Step 2: Configure Ccache#

  1. Create the Ccache configuration folder and file:

    mkdir -p ~/.cache/ccache
touch ~/.cache/ccache/ccache.conf

  2. Set the maximum cache size. The default size is 5GB, but you can increase it depending on your needs. Here, we're setting it to 60GB:

    echo "max_size = 60G" >> ~/.cache/ccache/ccache.conf

Step 3: Integrate Ccache with Your Environment#

To ensure Ccache is used for compilation, add the following lines to your .bashrc file. This will redirect GCC and G++ calls through Ccache.

export CC="/usr/lib/ccache/gcc"
export CXX="/usr/lib/ccache/g++"
export CCACHE_DIR="$HOME/.cache/ccache/"

After adding these lines, reload your .bashrc or restart your terminal session to apply the changes.

Step 4: Verify Ccache is Working#

To confirm Ccache is correctly set up and being used, you can check the statistics of cache usage:

ccache -s

This command displays the cache hit rate and other relevant statistics, helping you gauge the effectiveness of Ccache in your development workflow.