From 4f602145a9a7fe1983f0bb195fba6c016217cdc9 Mon Sep 17 00:00:00 2001 From: Shane Loretz Date: Mon, 14 Oct 2024 21:20:22 -0700 Subject: [PATCH 1/3] Start guide on determinine if dependencies are available in ROS 2 Signed-off-by: Shane Loretz --- source/How-To-Guides/Migrating-from-ROS1.rst | 1 + .../Migrating-Dependencies.rst | 135 ++++++++++++++++++ .../Migrating-Packages.rst | 4 +- 3 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst diff --git a/source/How-To-Guides/Migrating-from-ROS1.rst b/source/How-To-Guides/Migrating-from-ROS1.rst index 6b095ca63f8..6d14cffaa9f 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-Dependencies Migrating-from-ROS1/Migrating-Package-XML Migrating-from-ROS1/Migrating-Interfaces Migrating-from-ROS1/Migrating-CPP-Package-Example diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst new file mode 100644 index 00000000000..6c0abcdedf6 --- /dev/null +++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst @@ -0,0 +1,135 @@ +Migrating Dependencies +====================== + +This page shows you how to tell if all of your ROS 1 package's dependencies are available in ROS 2. + +.. contents:: Table of Contents + :depth: 2 + :local: + +Prerequisites +------------- + +This page assumes you have a Linux machine with :doc:`rosdep ` installed. + +Why do dependencies matter? +--------------------------- + +Virtually all ROS packages depend on something. +A package that needs the transform between two points probably depends on ``tf2``. +A package that installs URDF files probably needs ``xacro``. +No package can work without its dependencies, so when you want to migrate any package to ROS 2 you must make sure all of its dependencies are available first. + +What ROS distro are you targeting? +---------------------------------- + +TODO this guide assumes you're targeting ROS {DISTRO}. + +Determine your package's dependencies +------------------------------------- + +If you want to know what your package depends on, then read it's ``package.xml``. +Every package's ``package.xml`` file must list that package's dependencies. + +However, there are two kinds of dependencies in ROS, and the difference is important when deciding if your package is ready to be migrated to ROS 2. + +* a ROS package +* a rosdep key + +A ROS package is exactly what it sounds like; your ROS package may depend on one or more other ROS packages. +A rosdep key is different. +It describes a system dependency. +For example, `tf2 `__ is a ROS package, while `eigen `__ is a rosdep key. +Read :doc:`the tutorial on rosdep ` to learn more. + +Is it a rosdep key or a package? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO use the rosdep keys command followed by the rosdep resolve command + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + cd /tmp + git clone https://github.com/ros/geometry2.git + rosdep keys --from-paths /tmp/geometry2/tf2_kdl | xargs rosdep resolve --os=ubuntu:focal --rosdistro=noetic + + +TODO if the package to be installed starts with `ros-distro`, then it's a ROS package. Otherwise it's a ROSDep key + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + $ rosdep keys --from-paths /tmp/geometry2/tf2_kdl | xargs rosdep resolve --os=ubuntu:focal --rosdistro=noetic + #ROSDEP[eigen] + #apt + libeigen3-dev + #ROSDEP[cmake_modules] + #apt + ros-noetic-cmake-modules + #ROSDEP[tf2_ros] + #apt + ros-noetic-tf2-ros + #ROSDEP[catkin] + #apt + ros-noetic-catkin + #ROSDEP[rostest] + #apt + ros-noetic-rostest + #ROSDEP[liborocos-kdl-dev] + #apt + liborocos-kdl-dev + #ROSDEP[tf2] + #apt + ros-noetic-tf2 + #ROSDEP[ros_environment] + #apt + ros-noetic-ros-environment + + +Check if a rosdep key is available +---------------------------------- + +TODO It matters what OS you're using. We're deling with ssytem deps after all + +Check if a ROS package is available +----------------------------------- + +TODO Searching ROS Index for the given ROS distro + + +Has this ROS package been replaced? +----------------------------------- + +Some packages haven't been migrated to ROS 2 because they were replaced with something better. +If you can't find a package in the ROS Index, then check the table below to see if it has a replacement. + +TODO move_base -> nav2, ... what else? + +.. list-table:: Equivalent packages in ROS 1 and ROS 2 + :widths: 25 25 + :header-rows: 1 + + * - ROS 1 + - ROS 2 + * - catkin + - ament_cmake_ros + * - roscpp + - rclcpp + * - roslaunch + - launch_ros + * - rospy + - rclpy + +Conclusion +---------- + +You now know if all of your package's dependencies are available in ROS 2. +If any dependency is not available, you must migrate it first. +Head back to :doc:`Migrating Packages <./Migrating-Packages>` to learn how to migrate it. \ No newline at end of file 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 6c3f359732e..a12c09dd118 100644 --- a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst +++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst @@ -15,7 +15,9 @@ There are two different kinds of package migrations: Prerequisites ------------- -Before being able to migrate a ROS 1 package to ROS 2 all of its dependencies must be available in ROS 2. +Virtually all ROS packages depend on at least one other package, and no package can be migrated to ROS 2 until its dependencies are available. +Are all of your package's dependencies available in ROS 2? +Read the :doc:`Migrating Dependencies guide <./Migrating-Dependencies>` to learn how to figure that out. Package.xml format version -------------------------- From 77c7701dc80564719bbac14165c6ca9887edc09f Mon Sep 17 00:00:00 2001 From: Shane Loretz Date: Tue, 15 Oct 2024 17:39:37 -0700 Subject: [PATCH 2/3] Misc progresss Signed-off-by: Shane Loretz --- .../Migrating-Dependencies.rst | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst index 6c0abcdedf6..f7b2f57f3f2 100644 --- a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst +++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst @@ -67,6 +67,7 @@ TODO if the package to be installed starts with `ros-distro`, then it's a ROS pa .. code-block:: bash $ rosdep keys --from-paths /tmp/geometry2/tf2_kdl | xargs rosdep resolve --os=ubuntu:focal --rosdistro=noetic + WARNING: ROS_PYTHON_VERSION is unset. Defaulting to 3 #ROSDEP[eigen] #apt libeigen3-dev @@ -93,6 +94,48 @@ TODO if the package to be installed starts with `ros-distro`, then it's a ROS pa ros-noetic-ros-environment +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + cd /tmp + git clone https://github.com/ros/geometry2.git + rosdep keys --from-paths /tmp/geometry2/tf2_kdl | xargs rosdep resolve --os=ubuntu:noble --rosdistro=rolling + + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + $ rosdep keys --from-paths /tmp/geometry2/tf2_kdl | xargs rosdep resolve --os=ubuntu:noble --rosdistro=rolling + WARNING: ROS_PYTHON_VERSION is unset. Defaulting to 3 + #ROSDEP[tf2] + #apt + ros-rolling-tf2 + #ROSDEP[catkin] + #ROSDEP[rostest] + #ROSDEP[liborocos-kdl-dev] + #apt + liborocos-kdl-dev + #ROSDEP[ros_environment] + #apt + ros-rolling-ros-environment + #ROSDEP[cmake_modules] + #ROSDEP[eigen] + #apt + libeigen3-dev + #ROSDEP[tf2_ros] + #apt + ros-rolling-tf2-ros + ERROR: no rosdep rule for 'catkin' + ERROR: no rosdep rule for 'rostest' + ERROR: no rosdep rule for 'cmake_modules' + + Check if a rosdep key is available ---------------------------------- @@ -120,12 +163,16 @@ TODO move_base -> nav2, ... what else? - ROS 2 * - catkin - ament_cmake_ros + * - cmake_modules + - tinyxml_vendor, tinyxml2_vendor, eigen3_cmake_module * - roscpp - rclcpp * - roslaunch - launch_ros * - rospy - rclpy + * - rostest + - launch_testing_ros Conclusion ---------- From a97afc9f4563e585322572307000bb0f10bccfe1 Mon Sep 17 00:00:00 2001 From: Shane Loretz Date: Thu, 17 Oct 2024 21:45:10 -0700 Subject: [PATCH 3/3] A little more progress Signed-off-by: Shane Loretz --- .../Migrating-Dependencies.rst | 120 +++++++++++++++--- 1 file changed, 105 insertions(+), 15 deletions(-) diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst index f7b2f57f3f2..ef0d408e45f 100644 --- a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst +++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst @@ -10,7 +10,7 @@ This page shows you how to tell if all of your ROS 1 package's dependencies are Prerequisites ------------- -This page assumes you have a Linux machine with :doc:`rosdep ` installed. +This page assumes you have Linux machine with :doc:`rosdep ` installed. Why do dependencies matter? --------------------------- @@ -20,27 +20,117 @@ A package that needs the transform between two points probably depends on ``tf2` A package that installs URDF files probably needs ``xacro``. No package can work without its dependencies, so when you want to migrate any package to ROS 2 you must make sure all of its dependencies are available first. -What ROS distro are you targeting? ----------------------------------- +Ask ``rosdep`` if your dependencies are available +------------------------------------------------- + +Use :doc:`rosdep ` to determine if your ROS 1 package's dependencies are available in ROS 2. + +First, decide what ROS 2 distro you want your package to work on. +Next, look up the Ubuntu version supported by that ROS distro in `REP 2000 `__. +Finally run these two commands: + +1. Run ``rosdep keys --from-paths PATH_TO_YOUR_ROS1_PACKAGE`` to get a list of your package's dependencies. +2. Run ``rosdep resolve --os=ubuntu:LOWERCASE_UBUNTU_DISTRO --rosdistro=ROS_DISTRO DEPENDENCY1 DEPENDENCY2 ...`` to see which of those dependencies are available in ROS 2. + +Example +^^^^^^^ + +Create a folder called ``my_package`` and create a file ``package.xml`` inside it with the following content: + +.. code-block:: xml + + + my_package + 1.0.0 + + My ROS 1 package + + Brian Gerky + BSD + + catkin + + cmake_modules + eigen + + eigen + + liborocos-kdl-dev + tf2 + tf2_ros + + ros_environment + rostest + + +Run ``rosdep keys --from-paths my_package`` to get a list of its dependencies: + +.. code-block:: bash + + $ rosdep keys --from-paths my_package/ + WARNING: ROS_PYTHON_VERSION is unset. Defaulting to 3 + liborocos-kdl-dev + catkin + cmake_modules + ros_environment + eigen + tf2 + rostest + tf2_ros + +Pretend you've chosen ROS Jazzy. +Look it up in `REP 2000 to discover that it supports Ubuntu Noble `__. +Run ``rosdep resolve --os=ubuntu:noble --rosdistro=jazzy ...`` to check if this package's dependencies are available in ROS Jazzy. + +.. code-block:: bash + + $ rosdep resolve --os=ubuntu:noble --rosdistro=jazzy eigen liborocos-kdl-dev rostest cmake_modules ros_environment tf2_ros catkin tf2 + #ROSDEP[eigen] + #apt + libeigen3-dev + #ROSDEP[liborocos-kdl-dev] + #apt + liborocos-kdl-dev + #ROSDEP[rostest] + #ROSDEP[cmake_modules] + #ROSDEP[ros_environment] + #apt + ros-jazzy-ros-environment + #ROSDEP[tf2_ros] + #apt + ros-jazzy-tf2-ros + #ROSDEP[catkin] + #ROSDEP[tf2] + #apt + ros-jazzy-tf2 + ERROR: no rosdep rule for 'rostest' + ERROR: no rosdep rule for 'cmake_modules' + ERROR: no rosdep rule for 'catkin' + +Focus on the ``ERROR`` messages. +They say that these three dependencies are not available: + +* rostest +* cmake_modules +* catkin + +However, these packages might not be in ROS Jazzy because they have been replaced. +Read the next section to learn how to determine that. -TODO this guide assumes you're targeting ROS {DISTRO}. +Determine if a package has been replaced. -Determine your package's dependencies -------------------------------------- +There are three er -If you want to know what your package depends on, then read it's ``package.xml``. Every package's ``package.xml`` file must list that package's dependencies. +There are two kinds of dependencies in ROS: -However, there are two kinds of dependencies in ROS, and the difference is important when deciding if your package is ready to be migrated to ROS 2. +* a ROS package (`example: tf2 `__) +* a rosdep key (`example: eigen `__ ) -* a ROS package -* a rosdep key +The difference is important when deciding if your package is ready to be migrated. +If your ROS 1 package depends on another ROS package and that ROS package is not available in ROS 2, then you must migrate your dependency to ROS 2 before you can migrate yours. +If your ROS 1 package depends on a rosdep key, and that rosdep key is not available on the platforms that -A ROS package is exactly what it sounds like; your ROS package may depend on one or more other ROS packages. -A rosdep key is different. -It describes a system dependency. -For example, `tf2 `__ is a ROS package, while `eigen `__ is a rosdep key. -Read :doc:`the tutorial on rosdep ` to learn more. Is it a rosdep key or a package? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~