Skip to content

Commit 12cc86a

Browse files
sloretzsloretz
authored
Move package.xml format 1 to 2 migration to its own page (ros2#4778)
Signed-off-by: Shane Loretz <[email protected]>
1 parent 9d6552c commit 12cc86a

File tree

3 files changed

+137
-114
lines changed

3 files changed

+137
-114
lines changed

‎source/How-To-Guides/Migrating-from-ROS1.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ If you are new to porting between ROS 1 and ROS 2, it is recommended to read thr
88
:maxdepth: 1
99

1010
Migrating-from-ROS1/Migrating-Packages
11+
Migrating-from-ROS1/Migrating-Package-XML
1112
Migrating-from-ROS1/Migrating-Interfaces
1213
Migrating-from-ROS1/Migrating-CPP-Packages
1314
Migrating-from-ROS1/Migrating-Python-Packages

‎source/How-To-Guides/Migrating-from-ROS1/Migrating-Package-XML.rst‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
Migrating your package.xml to format 2
2+
======================================
3+
4+
.. contents:: Table of Contents
5+
:depth: 2
6+
:local:
7+
8+
ROS 2 requires ``package.xml`` files to use at least `format 2 <https://ros.org/reps/rep-0140.html>`__.
9+
This guide shows how to migrate a ``package.xml`` from format 1 to format 2.
10+
11+
If the ``<package>`` 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.
12+
13+
.. code-block:: xml
14+
15+
<package>
16+
17+
.. code-block:: xml
18+
19+
<package format="1">
20+
21+
22+
Prerequisites
23+
-------------
24+
25+
You should have a working ROS 1 installation.
26+
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.
27+
28+
Migrate from format 1 to 2
29+
--------------------------
30+
31+
Format 1 and format 2 differ in how they specify dependencies.
32+
Read the `compatibility section in REP-0140 <https://www.ros.org/reps/rep-0140.html#compatibility>`__ for a summary of the differences.
33+
34+
Add ``format`` attribute to ``<package>``
35+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36+
37+
Add or set the ``format`` attribute to ``2`` to indicate that the ``package.xml`` uses format 2.
38+
39+
.. code:: xml
40+
41+
<package format="2">
42+
43+
Replace ``<run_depend>``
44+
~~~~~~~~~~~~~~~~~~~~~~~~
45+
46+
The ``<run_depend>`` tag is no longer allowed.
47+
If you have a dependency specified like this:
48+
49+
.. code:: xml
50+
51+
<run_depend>foo</run_depend>
52+
53+
then replace it with one or both of these tags:
54+
55+
.. code:: xml
56+
57+
<build_export_depend>foo</build_export_depend>
58+
<exec_depend>foo</exec_depend>
59+
60+
If the dependency is needed when something in your package is executed, then use the ``<exec_depend>`` tag.
61+
If packages that depend on your package need the dependency when they are built, then use the ``<build_export_depend>`` tag.
62+
Use both tags if you are unsure.
63+
64+
Convert some ``<build_depend>`` to ``<test_depend>``
65+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66+
67+
In format 1 ``<test_depend>`` declares dependencies that are needed when running your package's tests.
68+
It still does that in format 2, but it additionally declares dependencies that are needed when building your package's tests.
69+
70+
Because of the limitations of this tag in format 1, your package may have a test-only dependency specified as a ``<build_depend>`` like this:
71+
72+
.. code:: xml
73+
74+
<build_depend>testfoo</build_depend>
75+
76+
If so, change it to a ``<test_depend>``.
77+
78+
.. code:: xml
79+
80+
<test_depend>testfoo</test_depend>
81+
82+
.. note::
83+
84+
If you are using CMake, then make sure your test dependencies are only referenced within a ``if(BUILD_TESTING)`` block:
85+
86+
.. code:: cmake
87+
88+
if (BUILD_TESTING)
89+
find_package(testfoo REQUIRED)
90+
endif()
91+
92+
Begin using ``<doc_depend>``
93+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94+
95+
Use the new ``<doc_depend>`` tag to declare dependencies needed for building your package's documentation.
96+
For example, C++ packages might have this dependency:
97+
98+
.. code:: xml
99+
100+
<doc_depend>doxygen</doc_depend>
101+
102+
while Python packages might have this one:
103+
104+
.. code:: xml
105+
106+
<doc_depend>python3-sphinx</doc_depend>
107+
108+
See :doc:`the guide on documenting ROS 2 packages <../Documenting-a-ROS-2-Package>` for more information.
109+
110+
Simplify dependencies with ``<depend>``
111+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112+
113+
``<depend>`` is a new tag that makes ``package.xml`` files more concise.
114+
If your ``package.xml`` has these three tags for the same dependency:
115+
116+
.. code::
117+
118+
<build_depend>foo</build_depend>
119+
<build_export_depend>foo</build_export_depend>
120+
<exec_depend>foo</exec_depend>
121+
122+
then replace them with a single ``<depend>`` like this:
123+
124+
.. code:: xml
125+
126+
<depend>foo</depend>
127+
128+
Test your new ``package.xml``
129+
-----------------------------
130+
131+
Build and test your package as you normally do using ``catkin_make``, ``cakin_make_isolated``, or the ``catkin`` build tool.
132+
If everything succeeds, then your ``package.xml`` is valid.

‎source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst‎

Lines changed: 4 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -17,121 +17,11 @@ Prerequisites
1717

1818
Before being able to migrate a ROS 1 package to ROS 2 all of its dependencies must be available in ROS 2.
1919

20-
Package format version
21-
----------------------
20+
Package.xml format version
21+
--------------------------
2222

23-
ROS 2 doesn't support format 1 of the package specification but only newer format versions (2 and higher).
24-
Therefore the ``package.xml`` file must be updated to at least format 2 if it uses format 1.
25-
Since ROS 1 supports all formats it is safe to perform that conversion in the ROS 1 package.
26-
27-
Migrating from package format 1 to 2+
28-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
29-
30-
The differences between format 1 and format 2 only affect the package.xml with its dependencies.
31-
`REP-0140 <https://www.ros.org/reps/rep-0140.html>`__ defines these differences and provides their rationale.
32-
33-
See :doc:`the rosdep documentation <../../Tutorials/Intermediate/Rosdep>` for more information about the various tags.
34-
35-
**<package>**
36-
~~~~~~~~~~~~~
37-
38-
The <package> tag determines which format to use, change it like this:
39-
40-
.. code:: xml
41-
42-
<package format="2">
43-
44-
**<depend>**
45-
~~~~~~~~~~~~~
46-
47-
This is a new tag, intended to reduce unnecessary repetition.
48-
If your format 1 package contained:
49-
50-
.. code:: xml
51-
52-
<build_depend>foo</build_depend>
53-
<run_depend>foo</run_depend>
54-
55-
It should be replaced with:
56-
57-
.. code:: xml
58-
59-
<depend>foo</depend>
60-
61-
In format 2, that is equivalent to:
62-
63-
.. code:: xml
64-
65-
<build_depend>foo</build_depend>
66-
<build_export_depend>foo</build_export_depend>
67-
<exec_depend>foo</exec_depend>
68-
69-
70-
**<run_depend>**
71-
~~~~~~~~~~~~~~~~
72-
73-
This tag is no longer allowed.
74-
Wherever found, it must be replaced:
75-
76-
.. code:: xml
77-
78-
<run_depend>foo</run_depend>
79-
80-
In format 2, that is equivalent to these two new tags:
81-
82-
.. code:: xml
83-
84-
<build_export_depend>foo</build_export_depend>
85-
<exec_depend>foo</exec_depend>
86-
87-
If the dependency is only used at run-time, only the ``<exec_depend>`` is needed.
88-
If it is only exported to satisfy the build dependencies of other packages, use ``<build_export_depend>``.
89-
If both are needed, this may be a better choice:
90-
91-
.. code:: xml
92-
93-
<depend>foo</depend>
94-
95-
96-
**<test_depend>**
97-
~~~~~~~~~~~~~~~~~
98-
99-
In format 2, this tag can satisfy build dependencies, not just those needed for executing your tests.
100-
Unlike format 1, ``<test_depend>`` may now refer to a package also declared as some other type of dependency.
101-
102-
Some test-only dependencies that formerly required a ``<build_depend>``, should now be expressed using ``<test_depend>``.
103-
For example:
104-
105-
.. code:: xml
106-
107-
<build_depend>testfoo</build_depend>
108-
109-
becomes:
110-
111-
.. code:: xml
112-
113-
<test_depend>testfoo</test_depend>
114-
115-
In your CMakeLists.txt make sure your test dependencies are only referenced within the conditional test block:
116-
117-
.. code:: cmake
118-
119-
if (BUILD_TESTING)
120-
find_package(testfoo REQUIRED)
121-
endif()
122-
123-
124-
**<doc_depend>**
125-
~~~~~~~~~~~~~~~~
126-
127-
This tag defines dependencies needed for building your documentation:
128-
129-
.. code:: xml
130-
131-
<doc_depend>doxygen</doc_depend>
132-
<doc_depend>python3-sphinx</doc_depend>
133-
134-
This does not create binary package dependencies, unless they were also declared using some other dependency tag.
23+
ROS 2 only supports ``package.xml`` format versions 2 and higher.
24+
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>`.
13525

13626
Dependency names
13727
----------------

0 commit comments

Comments
 (0)