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#

Ccache can speed up recompilation. It is recommended to use it to save your time unless you have a specific reason not to do so.

  1. Install Ccache:

    sudo apt update && sudo apt install ccache

  2. Write the following in your .bashrc:

    export CC="/usr/lib/ccache/gcc"
export CXX="/usr/lib/ccache/g++"