From 4f602145a9a7fe1983f0bb195fba6c016217cdc9 Mon Sep 17 00:00:00 2001 From: Shane Loretz Date: Mon, 14 Oct 2024 21:20:22 -0700 Subject: [PATCH] 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 6b095ca63f..6d14cffaa9 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 0000000000..6c0abcdedf --- /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 6c3f359732..a12c09dd11 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 --------------------------