 Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags. |
Build your package using Python 3
Description: While not officially supported until Noetic, building and testing your package using Python 3 is essential to prepare for the upcoming release.Tutorial Level: INTERMEDIATE
Next Tutorial: Contribute Python 3 Fixes
This tutorial is part of a series about transitioning a ROS 1 package to Python 3.
Contents
Choose your operating system
If you are using the same branch for Noetic and Melodic, then use Ubuntu Bionic. That will make sure your changes continue to work on Melodic's target platform. If you are using a separate branch for Noetic, then consider using Debian Buster as that will likely be one of Noetic's target platforms.
If you don't have either of those operating systems installed, then use a container engine like Docker or a virtual machine.
Create an underlay workspace for dependencies
Until the buildfarm becomes available, everything must be built from source.
Start by making an empty workspace
mkdir -p ~/underlay_ws/src
Download source code of dependencies
If your package has been released, and all of your dependencies are using the same branch for Melodic and Noetic, then rosinstall_generator can fetch just the upstream sources you need.
cd ~/underlay_ws rosinstall_generator <your_package_name> --rosdistro melodic --deps-only --upstream-devel > dependencies.rosinstall
If your package has not been released, or if some of your dependencies branched for Noetic, then you'll need to fetch ALL Noetic sources.
cd ~/underlay_ws rosinstall_generator --repos ALL --rosdistro noetic --upstream-devel > dependencies.rosinstall
Note: rosinstall_generator >= 0.1.17 is required for --repos ALL
If your package already has a source entry in the noetic/distribution.yaml, then remove it from dependencies.rosinstall.
Use vcstool to download the packages
cd ~/underlay_ws vcs import --input dependencies.rosinstall ./src
Use rosdep to install system dependencies
cd ~/underlay_ws export ROS_PYTHON_VERSION=3 rosdep install --from-paths ./src --ignore-src
Build the underlay
Your underlay workspace includes everything in ROS beneath your package, including catkin. To build it, invoke catkin_make_isolated from the workspace.
cd ~/underlay_ws export ROS_PYTHON_VERSION=3 python3 ./src/catkin/bin/catkin_make_isolated --install -DCMAKE_BUILD_TYPE=Release --catkin-make-args all
This may take a while depending on how many packages your package recursively depends on. All of your dependencies must successfully build before your package can begin to build. If a dependency does not build, then you'll need to try fixing it before continuing.
Assuming everything built, source the install space any time you want to use the underlay workspace.
cd ~/underlay_ws export ROS_PYTHON_VERSION=3 . install_isolated/setup.bash
Don't use the Devel space. Python scripts used from devel_isolated may have shebang's that invoke python2. Those same scripts should work from the install space assuming your dependencies correctly installed them using a tool like catkin_install_python().
Create an overlay workspace
Now that all your package's dependencies have been built, it's time to build your package using Python 3. Make a workspace and add your package's source code to it.
mkdir -p ~/overlay_ws/src # Now checkout your package's source code to ./src
If you haven't already, set ROS_PYTHON_VERSION and source the underlay workspace as described above.
There are two differences between building the overlay and the underlay. First catkin_make_isolated can be used without providing a path, and second in the overlay you should build your package's tests.
cd ~/overlay_ws catkin_make_isolated --install -DCMAKE_BUILD_TYPE=Release --catkin-make-args all tests
Now that tests are built, run them.
cd ~/overlay_ws catkin_make_isolated --force-cmake --catkin-make-args run_tests
Use catkin_test_results to get a summary.
cd ~/overlay_ws catkin_test_results
You've now built and run your package's tests using Python 3.
Next Tutorial: Contribute Python 3 Fixes
