add instructions how to map argument of other build tools to colcon

index.rst

@@ -13,6 +13,7 @@ The code is open source, and `available on GitHub`_.
 The documentation is organized into a few sections:
 
 * :ref:`user-docs`
+* :ref:`migration-docs`
 
 Information about development is also available:
 
@@ -35,3 +36,13 @@ Information about development is also available:
 
    developer/design
    developer/bootstrap
+
+.. _migration-docs:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Migrate from other build tools
+
+   migration/ament_tools
+   migration/catkin_make_isolated
+   migration/catkin_tools

migration/ament_tools.rst

@@ -0,0 +1,87 @@
+ament_tools
+===========
+
+The following describes the mapping of some ``ament_tools`` options and arguments to the ``colcon`` command line interface.
+
+ament build | test
+------------------
+
+``[BASEPATH]``
+  ``--base-paths BASEPATH``
+
+``--build-space PATH``
+  ``--build-base PATH``
+
+``--install-space PATH``
+  ``--install-base PATH``
+
+``--build-tests``
+  ``--cmake-args \ -DBUILD_TESTING=1``
+
+``-s``, ``--symlink-install``
+  ``--symlink-install``
+
+``--isolated``
+  The colcon option ``--merge-install`` has the inverse logic.
+
+``--start-with PKGNAME``
+  ``--package-start PKGNAME``
+
+``--end-with PKGNAME``
+  ``--package-end PKGNAME``
+
+``--only-packages PKGNAME1 ... PKGNAMEn`
+  ``--package-whitelist PKGNAME1 ... PKGNAMEn``
+
+``--skip-packages PKGNAME1 ... PKGNAMEn``
+  ``--package-blacklist PKGNAME1 ... PKGNAMEn``
+
+``--parallel``
+  colcon uses the parallel execution by default.
+  To build packages sequentially use ``--executor sequential``.
+
+ament build
+-----------
+
+``colcon build ...``
+
+``--cmake-args -D... --``
+  --cmake-args \ -D...``, ``--cmake-args " -D..."``
+  Any CMake arguments which start with a dash need to be prefixed with a space.
+  This can either be done using an escaped space or by quoting the argument with a leading space.
+  The closing double dash is not necessary anymore.
+
+``--force-cmake-configure``
+  ``--cmake-force-configure``
+
+``--use-ninja``
+  ``--cmake-args \ -G Ninja``
+
+ament test
+----------
+
+``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``
+
+ament test_results
+------------------
+
+``colcon test-result ...``
+
+``[BASEPATH]``
+  ``--build-base BASEPATH``
+
+``--verbose``
+  ``--all``

migration/catkin_make_isolated.rst

@@ -0,0 +1,48 @@
+catkin_make_isolated
+====================
+
+The following describes the mapping of some ``catkin_make_isolated`` options and arguments to the ``colcon`` command line interface.
+
+``--source PATH``
+  ``--base-paths BASEPATH``
+
+``--build PATH``
+  ``--build-base PATH``
+
+``--devel PATH``
+  colcon doesn't support the concept of a "devel" space.
+  Instead you can choose the path of the devel space as the install base and perform an normal installation.
+
+``--install-space PATH``
+  ``--install-base PATH``
+
+``--merge``
+  ``--merge-install``
+
+``--use-ninja``
+  ``--cmake-args \ -G Ninja``
+
+``--use-nmake``
+  ``--cmake-args \ -G "NMake Makefiles"``
+
+``--install``
+  colcon always performs an installation.
+  It doesn't support the concept of a "devel" space.
+
+``--cmake-args ...``
+    --cmake-args \ -D...``, ``--cmake-args " -D..."``
+    Any CMake arguments which start with a dash need to be prefixed with a space.
+    This can either be done using an escaped space or by quoting the argument with a leading space.
+    The closing double dash is not necessary anymore.
+
+``--force-cmake``
+  ``--cmake-force-configure``
+
+``--pkg PKGNAME1 ... PKGNAMEn``
+  ``--package-whitelist PKGNAME1 ... PKGNAMEn``
+
+``--from-pkg PKGNAME``
+  ``--package-start PKGNAME``
+
+``--only-pkg-with-deps PKGNAME1 ... PKGNAMEn``
+  ``--packages-up-to PKGNAME1 ... PKGNAMEn``

migration/catkin_tools.rst

@@ -0,0 +1,40 @@
+catkin_tools
+============
+
+The following describes the mapping of some ``catkin_tools`` options and arguments to the ``colcon`` command line interface.
+
+catkin build
+------------
+
+``[PKGNAME1 ... PKGNAMEn]``
+  ``--packages-up-to PKGNAME1 ... PKGNAMEn``
+
+``--no-deps``
+  ``--package-whitelist PKGNAME1 ... PKGNAMEn``
+
+``--start-with PKGNAME``
+  ``--package-start PKGNAME``
+
+``--force-cmake``
+  ``--cmake-force-configure``
+
+``--cmake-args ... --``
+  --cmake-args \ -D...``, ``--cmake-args " -D..."``
+  Any CMake arguments which start with a dash need to be prefixed with a space.
+  This can either be done using an escaped space or by quoting the argument with a leading space.
+  The closing double dash is not necessary anymore.
+
+``-v``, ``--verbose``
+  ``--event-handler console_cohesion+``
+
+``-i``, ``--interleave-output``
+  ``--event-handler console_direct+``
+
+``--no-status``
+  ``--event-handler status-``
+
+``--no-summarize``, ``--no-summary``
+  ``--event-handler summary-``
+
+``--no-notify``
+  ``--event-handler desktop_notification-``

spelling_wordlist.txt

@@ -1,4 +1,9 @@
+ament
+args
+cmake
+CMake
 colcon
+CTest
 devel
 macOS
 metadata

user/quick-start.rst

@@ -49,6 +49,8 @@ Instead of invoking ``ament build`` you can invoke ``colcon``.
 
 In order to use the built packages you need to source the ``install/prefix.<ext>`` rather than the ``local_setup.<ext>`` script mentioned in the instructions.
 
+For detailed information how command line arguments of ``ament_tools`` are mapped to ``colcon`` please see the :doc:`ament_tools migration guide <../migration/ament_tools>`.
+
 Build ROS 1 packages
 --------------------
 
@@ -68,6 +70,9 @@ Instead of invoking ``catkin_make_isolated --install`` you can invoke ``colcon``
 
 In order to use the built packages you need to source the ``install/prefix.<ext>`` rather than the ``setup.<ext>`` script mentioned in the instructions.
 
+For detailed information how command line arguments of ``catkin_make_isolated`` are mapped to ``colcon`` please see the :doc:`catkin_make_isolated migration guide <../migration/catkin_make_isolated>`.
+For detailed information how command line arguments of ``catkin_tools`` are mapped to ``colcon`` please see the :doc:`catkin_tools migration guide <../migration/catkin_tools>`.
+
 Build Gazebo and the ignition packages
 --------------------------------------