The following describes the mapping of some ament_tools
options and arguments to the colcon
command line interface.
[BASEPATH]
--base-paths BASEPATH
--build-space PATH
--build-base PATH
--install-space PATH
--install-base PATH
--build-tests
CMake configures tests by default. To skip configuring tests use
--cmake-args -DBUILD_TESTING=OFF
.-s
,--symlink-install
--symlink-install
--isolated
The colcon option
--merge-install
has the inverse logic.--start-with PKGNAME
--packages-start PKGNAME
--end-with PKGNAME
--packages-end PKGNAME
--only-packages PKGNAME1 ... PKGNAMEn
--packages-select PKGNAME1 ... PKGNAMEn
--skip-packages PKGNAME1 ... PKGNAMEn
--packages-skip PKGNAME1 ... PKGNAMEn
--parallel
colcon uses the parallel execution by default. To build packages sequentially use
--executor sequential
.
colcon build ...
--cmake-args -D... --
--cmake-args -D...
The closing double dash is not necessary anymore. Any CMake arguments which match colcon arguments need to be prefixed with a space. This can be done by quoting each argument with a leading space.--force-cmake-configure
--cmake-force-configure
--make-flags
When using this option to pass a target name the substitution is:
--cmake-target TARGET
. When using this option to control the parallel execution with arguments like-jN
the substitution is to use the environment variableMAKEFLAGS
.--use-ninja
--cmake-args -G Ninja
colcon test ...
--ctest-args ... --
--ctest-args ...
Any CTest arguments which start with a dash need to be prefixed with a space (see--cmake-args
).--retest-until-fail N
--retest-until-fail N
--retest-until-pass N
--retest-until-pass N
--abort-on-test-error
--abort-on-error
colcon test-result ...
[BASEPATH]
--build-base BASEPATH
--verbose
--all
The colcon test
verb performs only the action of running tests. It does not build any packages.
--retest-until-fail
with colcon
uses pytest-repeat which runs individual tests of a package N+1 times each (the first test N+1 times, then the second test N+1 times, etc). With ament_tools
the entire test suite of a package was run up to N+1 times. As a consequence colcon
provides a more accurate result since each test that passed has actually run N times. Note that with pytest-repeat
, pytest
tests are repeated N times regardless of the result of the previous runs; if a test fails it will be repeated N times anyway. This is different from the behavior of a CTest test that will stop being repeated as soon as it fails once.
The location of JUnit test results file for ament_python
packages tested with colcon
is in <pkg-build>/pytest.xml
, whereas with ament_tools
it is in <pkg-build>/test_results/<pkgname>/pytest.xunit.xml
.