How to¶

This section describe how to perform common tasks.

Show all output immediately on the console¶

$ colcon <verb> --event-handlers console_direct+

Note

If you use the parallel executor (which is the default when that extension is installed) the output of packages processed in parallel will be interleaved.

Show all output on the console after a package has finished¶

$ colcon <verb> --event-handlers console_cohesion+

Note

While this delays the output until a package has finished, it avoids interleaving the output when using the parallel executor.

Build only a single package (or selected packages)¶

$ colcon build --packages-select <name-of-pkg>
$ colcon build --packages-select <name-of-pkg> <name-of-another-pkg>

Note

This assumes that you have built dependencies of the selected packages within the workspace before.

Build selected packages including their dependencies¶

$ colcon build --packages-up-to <name-of-pkg>

Rebuild packages which depend on a specific package¶

Assuming you have built the whole workspace before and then made changes to one package. In order to rebuild this package as well as all packages which (recursively) depend on this package invoke:

$ colcon build --packages-above <name-of-pkg>

Build packages that create a Python C/C++ Extension¶

To be able to build a C/C++ extension when using the option --symlink-install, you must include the following lines in your package’s setup.py:

sources = ['one.cpp', 'two.cpp']  # This will contain all C/C++ source files
headers = ['a.h', 'b.hpp', 'c.h']  # Any included header files must be listed here

setup(
    ...,
    data_files=[('.', sources + headers)]  # Assuming that your source and header files are
                                           # on the same level as setup.py, this will copy
                                           # all required files to the colcon build folder
)

Finally, run colcon build --symlink-install as usual.

Test selected packages as well as their dependents¶

If you have built the relevant packages before you can run the tests the same way as described in the previous section:

$ colcon test --packages-above <name-of-pkg>

If you haven’t built the relevant packages before you can build the to-be-tested packages as well as their recursive dependencies with:

$ colcon build --packages-above-and-dependencies <name-of-pkg>

Run specific tests¶

Depending on the type of the package a different tool is being used to run tests.

Python packages using pytest¶

$ colcon test --packages-select <name-of-pkg> --pytest-args ...

Pytest provides multiple ways to select individual tests:

Tests can be identified by their name:

$ ... --pytest-args -k name_of_the_test_function

Tests can be identified using markers if the tests have been decorated with markers before:
```
$ ... --pytest-args -m marker_name
```

Both approaches also support logical expressions like or and not. For more information see the pytest documentation.

CMake packages using CTest¶

$ colcon test --packages-select <name-of-pkg> --ctest-args ...

CTest provides multiple ways to select individual tests:

Tests can be selected / excluded using a regular expression matching their name:
```
$ ... --ctest-args -R regex
$ ... --ctest-args -E regex
```
Tests can be selected / excluded using a regular expression matching their label (which have to be assigned to each test when adding the test in the CMake code):
```
$ ... --ctest-args -L regex
$ ... --ctest-args -LE regex
```

For more information see the CTest documentation.

Build CMake packages without configuring tests¶

For CMake packages which use the CMake option BUILD_TESTING (which is the standard in the CTest module) you can skip configuring and building tests to improve the build time:

$ colcon build --cmake-args -DBUILD_TESTING=OFF

CMake packages generating compile_commands.json¶

When the CMake option CMAKE_EXPORT_COMPILE_COMMANDS is enabled a compile_commands.json file is generated in the package specific build directory containing the exact compiler calls for all translation units of the project in machine-readable form:

$ colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

colcon-cmake will additionally generate a workspace-level compile_commands.json in the build directory which aggregates the information from all package specific json files.

Enable additional output for debugging¶

Beside the output of the actually invoked commands to build or test packages the tool by default only outputs warning or error messages. For debugging purposes you can enable logging messages with other levels (e.g. info, debug).

$ colcon --log-level info <verb> ...