# 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](<https://colcon.readthedocs.io/>).

## 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](<https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace.html#source-the-overlay>).

## Cleaning up the build artifacts

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

```bash
rm -rf build/ install/
```

In case you know what packages to remove:

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

## Selecting packages to build

To just build specified packages:

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

To build specified packages and their dependencies recursively:

```bash
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.

```bash
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug
```

```bash
colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo
```

```bash
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
```

## Changing the default configuration of colcon

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

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

For more details, see [the `defaults.yaml` section of the colcon documentation](<https://colcon.readthedocs.io/en/released/user/configuration.html#defaults-yaml>).

## Generating compile\_commands.json

[compile\_commands.json](<https://colcon.readthedocs.io/en/released/user/how-to.html#cmake-packages-generating-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`:

```bash
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+`:

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

For other options, see [the event handler arguments of colcon](<https://colcon.readthedocs.io/en/released/reference/event-handler-arguments.html>).

## Using Ccache to speed up recompilation

[Ccache](<https://ccache.dev/>) 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

```bash
sudo apt update && sudo apt install ccache
```

### Step 2: Configure Ccache

1. **Create the Ccache configuration folder and file:**

   ```bash
   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`:

   ```bash
   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.

```bash
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:

```bash
ccache -s
```

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