How to release a ROS 2 binary package [Part 2/3]

What we are going to learn

How to create a ros/rosdistro source entry so that your package can be released with ROS. Something like: sudo apt-get install ros-humble-my-package-name

List of resources used in this post

Part 1 of this series: https://www.theconstruct.ai/how-to-release-a-ros-2-binary-package-part-1-2
Use the rosject: https://app.theconstructsim.com/l/50995c4e/
The Construct: https://app.theconstructsim.com/
ROS2 Courses –▸
1. ROS2 Basics in 5 Days (Python): https://app.theconstructsim.com/#/Course/73
2. ROS2 Basics in 5 Days (C++): https://app.theconstructsim.com/#/Course/61
3. ROS2 Navigation training: https://www.theconstruct.ai/ros2-navigation-training/

Overview

ROS2, the improved version of ROS (ROS1), is quickly becoming the standard for developing robotics applications.

In this post, we will learn the second part on how to release a ROS2 package as a binary file. Binary files are pre-built executables. They are easier to install because they do not require building from the source code. Binary files are perfect if you want to easily distribute a package to other people.

You can easily install them with apt-get install PKG_NAME, or sudo dpkg -i pkg-name.deb, for example.

It is highly recommended that you follow that Part 1, since it is a requirement for following this post:

https://www.theconstruct.ai/how-to-release-a-ros-2-binary-package-part-1-2

Also, the third part of this series can be found in the link below:

https://www.theconstruct.ai/how-to-release-a-ros-2-binary-package-part-3/

ROS Inside!

ROS Inside

Before anything else, in case you want to use the logo above on your own robot or laptop, feel free to download it for free and attach it to your robot. It is really free. Find it in the link below:

ROS Inside logo

Acknowledgment

This post is based on ROS2’s official documentation, check it out here:

https://docs.ros.org/en/humble/How-To-Guides/Releasing/Releasing-a-Package.html

Opening the rosject

In order to release a ROS 2 binary package, we need to have ROS2 installed in our system, and it is also useful to have some simulations. To make your life easier, we already prepared a rosject with a simulation for that: https://app.theconstructsim.com/l/50995c4e/.

You can download the rosject on your own computer if you want to work locally, but just by copying the rosject (clicking the link), you will have a setup already prepared for you.

After the rosject has been successfully copied to your own area, you should see a Run button. Just click that button to launch the rosject (below you have a rosject example).

How to release a ROS 2 binary package – Run rosject (example of the RUN button)

After pressing the Run button, you should have the rosject loaded. Let’s now head to the next section to really get some real practice.

Assumptions

Existing ROS2 Package, publicly available for everyone to use
Git and GitHub basics
You have completed the first part aforementioned:
- Created a release repository
- Started a new release team (pull request is pending)
- Installed the tools required on our machine
- Created a GIT access token to authenticate

Open a terminal

You will need to clone a repository soon, so, in order to do that, you will need a terminal. If you are new to the platform, you can easily open a terminal by clicking on the first button on the bottom left.

Open a new Terminal

Create a ros/rosdistro source entry

What is ros/rosdistro? https://github.com/ros/rosdistro is a GitHub repository that maintains information describing ROS packages and repositories. The build process accesses this information to build packages.

The rosdistro repository also stores the rules used by rosdep to install external dependencies.

To see all ROS Packages included in ROS Humble, for example, you can have a look at this file: https://github.com/ros/rosdistro/blob/master/humble/distribution.yaml

Validation process

When you create a ros/rosdistro source entry for a package that you release for the very first time, your repository will be reviewed to check whether it conforms to some basic rules.

Here is an example of some of the validations performed:

LICENSE file
Package Naming rules

To add create a ros/rosdistro source entry one can manually open a pull request to the corresponding GitHub repository:

Steps:

Fork the https://github.com/ros/rosdistro repository on GitHub by clicking https://github.com/ros/rosdistro/fork.
Clone the repo fork, so you can edit the contents locally. Something like:
```
cd ~/ros2_ws/src

git clone https://github.com/YOUR-USERNAME/rosdistro

cd rosdistro
```
Add your repository to the repository listing:
- Open the appropriate directory for the distribution that you would like to add a listing to through the IDE.
- Inside this directory, edit the distribution.yaml file.
- Add your repository information with a doc section as shown below.Considerations:
  - You should maintain the alphabetic order of the repositories
  - The repository URL should point to the upstream repository, not the release repository.

Example distro file: humble/distribution.yaml

wall_follower_ros2: 
  source:
    type: git 
    url: https://github.com/rfzeg/wall_follower_ros2.git 
    version: master 
  status: maintained

Now, go back to the rosdistro root directory and run the following command:

rosdistro_reformat file://"$(pwd)"/index.yaml

This will make the files comply with rosdistro’s special formatting rules.

Check the differences made by the script you just ran:

git diff distribution.yaml

which should show something like this:

git diff

If everything looks good, you are ready to commit your changes:

git commit -m "Add wall_follower_ros2 repo"

Push your changes to your remote GitHub repository:

git push origin master

Create and Submit a pull request on GitHub to the rosdistro project to add your source entry to the indexer.

To create a new request, go to your repository and click the Contribute -> Open pull request button:

Open a Pull Request for rosdistro

After that, git a title to the Pull Request. Title example:

Add wall_follower_ros2 repo to humble

Then the body of the Pull Request goes like this:

Adding new repository: https://github.com/rfzeg/wall_follower_ros2.git to humble 
as requested in https://github.com/ros2-gbp/ros2-gbp-github-org/issues/99 
for the purpose of releasing the package wall_follower_ros2

# Checks
[x] All packages have a declared license in the package.xml
[x] This repository a LICENSE file
[x] This package is expected to build on the submitted rosdistro

Remember that after submitting your pull request, some changes may be requested, and since the reviews are done asynchronously, it can sometimes take a few days until the review is completed.

Now, if they ask you to modify anything, you just go ahead and do the modifications.

You may now want to go ahead and check how to build a Debian file locally:

https://www.theconstruct.ai/how-to-build-a-local-debian-ros2-package/

Congratulations. We have finished the second part about the release of a ROS2 Binary package. We hope this post was really helpful to you. We soon may have an extra part related to this subject.

Please bear in mind that the third part of this series can be found in the link below:

https://www.theconstruct.ai/how-to-release-a-ros-2-binary-package-part-3/

Youtube video

So this is the post for today. Remember that we have the live version of this post on YouTube. If you liked the content, please consider subscribing to our youtube channel. We are publishing new content ~every day.

Keep pushing your ROS Learning.

Related Courses & Training

If you want to learn more about ROS and ROS2, we recommend the following courses:

ROS2 Basics in 5 Days (Python): https://app.theconstructsim.com/#/Course/73
ROS2 Basics in 5 Days (C++): https://app.theconstructsim.com/#/Course/61

How to release a ROS 2 binary package [Part 1/3]

What we are going to learn

How to create a new release repository
How to create a new release team
How to install the tools that you will use
How to create a Personal Access Token on GitHub

List of resources used in this post

Use the rosject: https://app.theconstructsim.com/l/4f2b155e/
The Construct: https://app.theconstructsim.com/
ROS 2 Documentation: https://docs.ros.org/en/humble/How-To-Guides/Releasing/Releasing-a-Package.html
ROS2 basic Courses –▸
1. ROS2 Basics in 5 Days (Python): https://app.theconstructsim.com/Course/73
2. ROS2 Basics in 5 Days (C++): https://app.theconstructsim.com/Course/61
3. ROS2 Basics in 5 Days Galactic (C++): https://app.theconstructsim.com/Course/117

Overview

ROS2, the improved version of ROS (ROS1), is quickly becoming the standard for developing robotics applications.

In this post, we will learn how to release a ROS2 package as a binary file. Binary files are pre-built executables. They are easier to install because they do not require building from the source code. Binary files are perfect if you want to easily distribute a package to other people.

You can easily install them with apt-get install PKG_NAME, or sudo dpkg -i pkg-name.deb, for example.

This is the first post in a series of two posts.

The second post can be found at:

https://www.theconstruct.ai/how-to-release-a-ros-2-binary-package-part-2-2/

ROS Inside!

ROS inside

Before anything else, in case you want to use the logo above on your own robot, feel free to download it for free and attach it to your robot. It is really free. Find it in the link below:

ROS Inside logo

Acknowledgment

This post is based on ROS2’s official documentation, check it out here:

https://docs.ros.org/en/humble/How-To-Guides/Releasing/Releasing-a-Package.html

Opening the rosject

You can download the rosject on your own computer if you want to work locally, but just by copying the rosject (clicking the link), you will have a setup already prepared for you.

After the rosject has been successfully copied to your own area, you should see a Run button. Just click that button to launch the rosject (below you have a rosject example).

How to release a ROS 2 binary package – Run rosject (example of the RUN button)

After pressing the Run button, you should have the rosject loaded. Let’s now head to the next section to really get some real practice.

Assumptions

We assume you have a GitHub account. If you don’t have it yet, you can easily create it by following this link: https://github.com/signup

Creating a ‘release repository’

When a release process runs, it outputs files for instance .md and .yaml files. This output is known as release artifacts. In ROS2, these artifacts need to be stored in a separate repository from the source code files. This repository is what we call the release repository.

So, if your repository name is wall_follower_ros2, you have to create a new repository that you can call, for instance, wall_follower_ros2-release to be used as a release repository for your package.

The ROS2 release process will use that repository to store artifacts as the automated release process runs.

I’m going to create a release repository for https://github.com/rfzeg/wall_follower_ros2

To make your life easier, assuming you may not have a repository with the same name, you can start by forking the repository aforementioned.

After that, please go to https://github.com/new and create a repository. The package name can be wall_follower_ros2-release.

You can leave the repository Public, and hit the “Create repository” button.

Creating a release package on GitHub

Start a new release team

A release team is a group of users within an organization who has permission to manage all release operations.

If a release team exists in your organization, you can join that team by completing the Update Release Team Membership issue template.

Here, we will assume that no release team exists for our package yet. To request a new release team to be created we must complete the New Release Team issue template.

This form will allow you to create a new release team and add the release repository to your new team in one go.

Below we have an example of the New Release Team issue filled:

Starting a new ros2 release team on GitHub

After creating the issue, you submit it and wait for the ROS2 team to take it into account.

Installing the tools required on your machine

In order to install the required tools, we need to have a terminal. If you are on The Construct, after having opened a rosject, let’s open a terminal:

Open a new Terminal

Let’s take the chance and also open the Code Editor to be easier to modify our files:

Open the IDE – Code Editor

Now, let’s go to the terminal and use apt to install bloom together with the python3-catkin-pkg modules.

sudo apt update

sudo apt install python3-bloom python3-catkin-pkg

The package should have been installed with no problems.

Let’s now move to the next step.

Creating a GIT access token to authenticate

Every time you interact with a remote Git repository on the command line (for example, doing a pull, or push operation), you are asked for your GitHub username and password. In this step, we create a Git Access Token to prevent Git from repeatedly prompting for your username and password during the release operation.

You can create an Access Token by clicking the “Generate new token” button in the link below:

https://github.com/settings/tokens

When filling out the form, set Note to a descriptive name such as Bloom, set Expiration to No expiration, and select the public_repo and workflow checkboxes.

After clicking on Generate token the page will display a string like CTA2AK1UMAPKSJGSZDR8HWS3GVRAFIQYYETWELT4.

This string is the token, copy it to your clipboard. Make sure to store it safely since you can’t display the token again in the GitHub interface.

In case you need more information on personal access tokens, please follow the link below:

https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Use the GIT access token to authenticate

Now that we have the Access Token, using the terminal, let’s create a folder named .config:

mkdir -pv ~/.config

Inside that folder, let’s create a file named boom:

cd ~/.config

touch bloom

Using the code editor, insert your GitHub username and PAT into it with the format shown below:

{ 
    "github_user": "<your-github-username>", 
    "oauth_token": "<token-you-created-for-bloom>" 
}

Since hidden files do not appear by default in the Code Editor, you have to click File Open in order to find the .config folder.

Please remember to save your ~/config/boom file by pressing CTRL+S (or File -> Save)

Congratulations. We are halfway through the release of a ROS2 Binary package. We hope this post was really helpful to you. The second post is coming soon. If you want a live version of this post, please check the video in the next section.

Youtube video

Keep pushing your ROS Learning.

Related Courses & Training

If you want to learn more about ROS and ROS2, we recommend the following courses:

ROS2 Basics in 5 Days (Python): https://app.theconstructsim.com/#/Course/73
ROS2 Basics in 5 Days (C++): https://app.theconstructsim.com/#/Course/61
ROS2 Basics in 5 Days Galactic (C++): https://app.theconstructsim.com/Course/117

How to release a ROS 2 binary package [Part 2/3]

What we are going to learn

Overview

ROS Inside!

Acknowledgment

Opening the rosject

Assumptions

Open a terminal

Create a ros/rosdistro source entry

Validation process

Youtube video

Related Courses & Training

How to release a ROS 2 binary package [Part 1/3]

What we are going to learn

List of resources used in this post

Overview

ROS Inside!

Acknowledgment

Opening the rosject

Assumptions

Creating a ‘release repository’

Start a new release team

Installing the tools required on your machine

Creating a GIT access token to authenticate

Use the GIT access token to authenticate

Youtube video

Related Courses & Training

Search

RECENT POSTS

Categories

Pin It on Pinterest