(!) 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.

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
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
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
. 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

You've now built and run your package's tests using Python 3.

Next Tutorial: Contribute Python 3 Fixes

Wiki: UsingPython3/BuildUsingPython3 (last edited 2019-08-23 20:08:35 by MaryaBelanger)