From b78154fff0b33d567f289c411198c2652ed76ddd Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Tue, 1 Oct 2024 13:06:52 +0200 Subject: [PATCH] Move package.xml format 1 to 2 migration to its own page (#4778) (#4782) Signed-off-by: Shane Loretz (cherry picked from commit 12cc86aec018b63f3cfc7059a97480f14d95171d) Co-authored-by: Shane Loretz --- source/How-To-Guides/Migrating-from-ROS1.rst | 1 + .../Migrating-Package-XML.rst | 132 ++++++++++++++++++ .../Migrating-Packages.rst | 118 +--------------- 3 files changed, 137 insertions(+), 114 deletions(-) create mode 100644 source/How-To-Guides/Migrating-from-ROS1/Migrating-Package-XML.rst diff --git a/source/How-To-Guides/Migrating-from-ROS1.rst b/source/How-To-Guides/Migrating-from-ROS1.rst index 18d6756ac9..fb0adda96f 100644 --- a/source/How-To-Guides/Migrating-from-ROS1.rst +++ b/source/How-To-Guides/Migrating-from-ROS1.rst @@ -8,6 +8,7 @@ If you are new to porting between ROS 1 and ROS 2, it is recommended to read thr :maxdepth: 1 Migrating-from-ROS1/Migrating-Packages + Migrating-from-ROS1/Migrating-Package-XML Migrating-from-ROS1/Migrating-Interfaces Migrating-from-ROS1/Migrating-CPP-Packages Migrating-from-ROS1/Migrating-Python-Packages diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Package-XML.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Package-XML.rst new file mode 100644 index 0000000000..b2838744d0 --- /dev/null +++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Package-XML.rst @@ -0,0 +1,132 @@ +Migrating your package.xml to format 2 +====================================== + +.. contents:: Table of Contents + :depth: 2 + :local: + +ROS 2 requires ``package.xml`` files to use at least `format 2 `__. +This guide shows how to migrate a ``package.xml`` from format 1 to format 2. + +If the ```` tag at the start of your ``package.xml`` looks like either of the following, then it is using format 1 and you must migrate it. + +.. code-block:: xml + + + +.. code-block:: xml + + + + +Prerequisites +------------- + +You should have a working ROS 1 installation. +This enables you to check that the converted ``package.xml`` is valid by building and testing the package, since ROS 1 supports all ``package.xml`` format versions. + +Migrate from format 1 to 2 +-------------------------- + +Format 1 and format 2 differ in how they specify dependencies. +Read the `compatibility section in REP-0140 `__ for a summary of the differences. + +Add ``format`` attribute to ```` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add or set the ``format`` attribute to ``2`` to indicate that the ``package.xml`` uses format 2. + +.. code:: xml + + + +Replace ```` +~~~~~~~~~~~~~~~~~~~~~~~~ + +The ```` tag is no longer allowed. +If you have a dependency specified like this: + +.. code:: xml + + foo + +then replace it with one or both of these tags: + +.. code:: xml + + foo + foo + +If the dependency is needed when something in your package is executed, then use the ```` tag. +If packages that depend on your package need the dependency when they are built, then use the ```` tag. +Use both tags if you are unsure. + +Convert some ```` to ```` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In format 1 ```` declares dependencies that are needed when running your package's tests. +It still does that in format 2, but it additionally declares dependencies that are needed when building your package's tests. + +Because of the limitations of this tag in format 1, your package may have a test-only dependency specified as a ```` like this: + +.. code:: xml + + testfoo + +If so, change it to a ````. + +.. code:: xml + + testfoo + +.. note:: + + If you are using CMake, then make sure your test dependencies are only referenced within a ``if(BUILD_TESTING)`` block: + + .. code:: cmake + + if (BUILD_TESTING) + find_package(testfoo REQUIRED) + endif() + +Begin using ```` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the new ```` tag to declare dependencies needed for building your package's documentation. +For example, C++ packages might have this dependency: + +.. code:: xml + + doxygen + +while Python packages might have this one: + +.. code:: xml + + python3-sphinx + +See :doc:`the guide on documenting ROS 2 packages <../Documenting-a-ROS-2-Package>` for more information. + +Simplify dependencies with ```` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +```` is a new tag that makes ``package.xml`` files more concise. +If your ``package.xml`` has these three tags for the same dependency: + +.. code:: + + foo + foo + foo + +then replace them with a single ```` like this: + +.. code:: xml + + foo + +Test your new ``package.xml`` +----------------------------- + +Build and test your package as you normally do using ``catkin_make``, ``cakin_make_isolated``, or the ``catkin`` build tool. +If everything succeeds, then your ``package.xml`` is valid. diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst index 960de91f51..6c3f359732 100644 --- a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst +++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst @@ -17,121 +17,11 @@ Prerequisites Before being able to migrate a ROS 1 package to ROS 2 all of its dependencies must be available in ROS 2. -Package format version ----------------------- +Package.xml format version +-------------------------- -ROS 2 doesn't support format 1 of the package specification but only newer format versions (2 and higher). -Therefore the ``package.xml`` file must be updated to at least format 2 if it uses format 1. -Since ROS 1 supports all formats it is safe to perform that conversion in the ROS 1 package. - -Migrating from package format 1 to 2+ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The differences between format 1 and format 2 only affect the package.xml with its dependencies. -`REP-0140 `__ defines these differences and provides their rationale. - -See :doc:`the rosdep documentation <../../Tutorials/Intermediate/Rosdep>` for more information about the various tags. - -**** -~~~~~~~~~~~~~ - -The tag determines which format to use, change it like this: - -.. code:: xml - - - -**** -~~~~~~~~~~~~~ - -This is a new tag, intended to reduce unnecessary repetition. -If your format 1 package contained: - -.. code:: xml - - foo - foo - -It should be replaced with: - -.. code:: xml - - foo - -In format 2, that is equivalent to: - -.. code:: xml - - foo - foo - foo - - -**** -~~~~~~~~~~~~~~~~ - -This tag is no longer allowed. -Wherever found, it must be replaced: - -.. code:: xml - - foo - -In format 2, that is equivalent to these two new tags: - -.. code:: xml - - foo - foo - -If the dependency is only used at run-time, only the ```` is needed. -If it is only exported to satisfy the build dependencies of other packages, use ````. -If both are needed, this may be a better choice: - -.. code:: xml - - foo - - -**** -~~~~~~~~~~~~~~~~~ - -In format 2, this tag can satisfy build dependencies, not just those needed for executing your tests. -Unlike format 1, ```` may now refer to a package also declared as some other type of dependency. - -Some test-only dependencies that formerly required a ````, should now be expressed using ````. -For example: - -.. code:: xml - - testfoo - -becomes: - -.. code:: xml - - testfoo - -In your CMakeLists.txt make sure your test dependencies are only referenced within the conditional test block: - -.. code:: cmake - - if (BUILD_TESTING) - find_package(testfoo REQUIRED) - endif() - - -**** -~~~~~~~~~~~~~~~~ - -This tag defines dependencies needed for building your documentation: - -.. code:: xml - - doxygen - python3-sphinx - -This does not create binary package dependencies, unless they were also declared using some other dependency tag. +ROS 2 only supports ``package.xml`` format versions 2 and higher. +If your package's ``package.xml`` uses format 1, then update it using the :doc:`Package.xml format 1 to 2 migration guide <./Migrating-Package-XML>`. Dependency names ----------------