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..584a2077435 --- /dev/null +++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Dependencies.rst @@ -0,0 +1,289 @@ +Migrating Dependencies +====================== + +This page shows you how to check 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 machine with :doc:`rosdep ` installed. + +Why do dependencies matter? +--------------------------- + +Virtually all ROS packages depend on something. +If your package needs transform between two points, it probably depends on `tf2 `__. +If your package installs URDF files, it probably depends on `xacro `__. +No package can work without its dependencies, so a package can only be migrated to ROS 2 if all of its dependencies are also available in ROS 2. + +Check if your dependencies are available in ROS 2 +------------------------------------------------- + +Use :doc:`rosdep ` to check if your package's dependencies are available in ROS 2 by following this process: + +1. Decide which ROS distro you want to check. +2. Look up the Ubuntu version supported by that ROS distro. +3. Use ``rosdep keys`` to list your package's dependencies. +4. Use ``rosdep resolve`` to see which of those dependencies are available. +5. Check if any missing dependencies have replacements in ROS 2. + +Decide which ROS distro to check +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +New packages are being added to ROS 2 all the time. +Newer ROS distros might have your package's dependencies, while older ROS distros might not. +Using ``rosdep``, you can only check if your package's dependencies are available in one ROS distro at a time. + +Pick the ROS distro you want to check, and remember its codename. +For example, ``jazzy`` is the codename for `ROS Jazzy Jalisco `__. +Next, look up the Ubuntu version supported by that ROS distro in `REP 2000 `__. +For example, ROS Jazzy supports `upports Ubuntu Noble `__. +Use the ROS distro codename and Ubuntu version name to 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_VERSION --rosdistro=ROS_DISTRO_CODENAME 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. + +Determine if a package has been replaced. + +There are three er + +Every package's ``package.xml`` file must list that package's dependencies. +There are two kinds of dependencies in ROS: + +* a ROS package (`example: tf2 `__) +* a rosdep key (`example: eigen `__ ) + +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 + + +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 + WARNING: ROS_PYTHON_VERSION is unset. Defaulting to 3 + #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 + + +.. 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 +---------------------------------- + +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 + * - cmake_modules + - tinyxml_vendor, tinyxml2_vendor, eigen3_cmake_module + * - roscpp + - rclcpp + * - roslaunch + - launch_ros + * - roslint + - ament_lint_auto + * - rospy + - rclpy + * - rostest + - launch_testing_ros + +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. 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 --------------------------