## page was renamed from UsingPython3/build_using_python_3
## page was renamed from TransitionToPython3/build_using_python_3
## page was renamed from transition_to_python_3/build_using_python_3
## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= 
## descriptive title for the tutorial
## title = Build your package using Python 3
## multi-line description to be displayed in search 
## description = While not officially supported until Noetic, building and testing your package using Python 3 is essential to prepare for the upcoming release.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=[[UsingPython3/Contributing|Contribute Python 3 Fixes]]
## next.1.link=
## what level user is this tutorial for 
## level=IntermediateCategory
## keywords =
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

This tutorial is part of [[UsingPython3|a series about transitioning a ROS 1 package to Python 3]].

<<TableOfContents(4)>>

== 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/Tutorials/Docker|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

{{{#!bash
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.

{{{#!bash
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.

{{{#!bash
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 [[https://github.com/ros/rosdistro/blob/master/noetic/distribution.yaml|noetic/distribution.yaml]], then remove it from '''dependencies.rosinstall'''.

Use [[https://github.com/dirk-thomas/vcstool#how-to-install-vcstool|vcstool]] to download the packages

{{{#!bash
cd ~/underlay_ws
vcs import --input dependencies.rosinstall ./src
}}}

Use '''rosdep''' to install system dependencies

{{{#!bash
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.

{{{#!bash
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.

{{{#!bash
cd ~/underlay_ws
export ROS_PYTHON_VERSION=3
. install_isolated/setup.bash
}}}

Don't use the [[http://wiki.ros.org/catkin/workspaces#Development_.28Devel.29_Space|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.

{{{#!bash
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.

{{{#!bash
cd ~/overlay_ws
catkin_make_isolated --install -DCMAKE_BUILD_TYPE=Release --catkin-make-args all tests
}}}

Now that tests are built, run them.

{{{#!bash
cd ~/overlay_ws
catkin_make_isolated --force-cmake --catkin-make-args run_tests
}}}

Use '''catkin_test_results''' to get a summary.

{{{#!bash
cd ~/overlay_ws
catkin_test_results
}}}

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

<<IncludeCSTemplate(TutorialCSTemplateFooter)>>

## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE