ROS 2 Cheats Sheet Global options: Test two packages including dependencies, and print on ter-

◦ --log-base <path> The base path for all log directories minal:
(default: log). $ colcon test --packages-up-to demo nodes cpp \
colcon - collective construction ◦ --log-level <level> Set log level for the console output, demo nodes py --event-handlers console direct+
colcon is a command line tool to improve the workflow of either by numeric or string value (default: warn) Pass arguments to pytest (e.g. to print a coverage report):
building, testing and using multiple software packages. It $ colcon test --packages-select demo nodes cpp \
automates the process, handles the ordering and sets up build Build a set of packages. --event-handlers console direct+ \
the environment to use the packages. Examples: --pytest-args --cov=sros2
All colcon tools start with the prefix ‘colcon’ followed by a Build the whole workspace:
command and (likely) positional/optional arguments. $ colcon build test-result Show the test results generated when testing
For any tool, the documentation is accessible with, Build a single package excluding dependencies: a set of packages.
$ colcon command --help $ colcon build --packages-selected demo nodes cpp Example:
Moreover, colcon offers auto-completion for all verbs and Build two packages including dependencies, use symlinks Show all test results generated, including successful tests:
most positional/optional arguments. E.g., instead of copying files where possible and print immedi- $ colcon test-result --all
$ colcon command [tab][tab] ately on terminal:
Find out how to enable auto-completion at colcon’s online $ colcon build --packages-up-to demo nodes cpp \ version-check Compare local package versions with PyPI.
documentation. action tutorials --symlink-install \ Examples:
--event-handlers console direct+ $ todo
Environment variables:
◦ CMAKE COMMAND The full path to the CMake exe- extension-points List extension points. Must know colcon flags.
cutable. ◦ --symlink-install Use ‘symlinks’ instead of installing
◦ COLCON ALL SHELLS Flag to enable all shell exten- extensions Package information. (copying) files where possible.
sions. ◦ --continue-on-error Continue other packages when a
◦ COLCON COMPLETION LOGFILE Set the logfile for info List extension points. package fails to build. Packages recursively depending on
completion time. the failed package are skipped.
◦ COLCON DEFAULTS FILE Set path to the yaml file con- list List packages, optionally in topological ordering. ◦ --event-handlers console direct+ Show output on console.
taining the default values for the command line arguments Example: ◦ --event-handlers console cohesion+ Show output on con-
(default:$COLCON HOME/defaults.yaml). List all packages in the workspace: sole after a package has finished.
◦ COLCON DEFAULT EXECUTOR Select the default ex- $ colcon list ◦ --packages-select Build only specific package(s).
ecutor extension. List all packages names in topological order up-to a given ◦ --packages-up-to Build specific package(s) and its/their
◦ COLCON EXTENSION BLACKLIST Blacklist exten- package: recursive dependencies.
sions which should not be used. $ colcon list --names-only --topological-order \ ◦ --packages-above Build specific package(s) and other
◦ COLCON HOME Set the configuration directory (de- --packages-up-to demo nodes cpp packages that recursively depending on it.
fault: /.colcon.) ◦ --packages-skip Skip package(s).
◦ COLCON LOG LEVEL Set the log level (debug—10, metadata Manage metadata of packages. ◦ --packages-skip-build-finished Skip a set of packages
info—20, warn—30, error—40, critical—50, or any other which have finished to build previously.
positive numeric value). test Test a set of packages. ◦ --cmake-args Pass arguments to CMake projects.
◦ COLCON LOG PATH Set the log directory (default: Example: ◦ --cmake-clean-cache Remove CMake cache before the
$COLCON HOME/log). Test the whole workspace: build (implicitly forcing CMake configure step).
◦ CTEST COMMAND The full path to the CTest exe- $ colcon test ◦ --cmake-clean-first Build target ‘clean’ first, then build
cutable. Test a single package excluding dependencies: (to only clean use ’–cmake-target clean’).
◦ POWERSHELL COMMAND The full path to the Pow- $ colcon test --packages-select demo nodes cpp ◦ --cmake-force-configure Force CMake configure step.
erShell executable. Test a package including packages that depend on it:
$ colcon test --packages-above demo nodes py

c 2019 Canonical