Releasing a Third Party Package

In this context a third party package is a non-catkin package, which you want to release into the ROS ecosystem. The requirements for a package to be released into the ROS ecosystem is detailed in REP-0136. Basically the package must do these things:

• Have a catkin package.xml

  • Which run_depend's on catkin

  • And which has a <build_type> tag in the <export> tag

• Install a catkin package.xml

The details relating to these requirements are in the REP.

A third party package can accomplish these requirements in two ways: in the upstream repository, or in the release repository.

Modifying the Upstream Repository

By adding a package.xml and a rule to install it in the upstream repository, the package looks just like a catkin package to the ROS ecosystem. This is a clean solution because it doesn't require any modifications to the normal release process and has almost no impact on the upstream repository. Additionally, if the package.xml and install rule is in the upstream source code, then the third party package can be built along side catkin packages even when checked out from source. If you choose this method, then simply create a package.xml using this as a reference: catkin/package.xml ensuring that is run_depend's on catkin, and add a rule to your build system to install the package.xml. Then, when you are ready to release jump to the normal bloom Release tutorials: bloom/Tutorials

Modifying the Release Repository

Often times, however, putting a package.xml in the upstream repository is not an option. In this case you can "inject" the package.xml into the release repository using bloom.

Setup a Release Repository

The first thing to do is to follow the Creating a Release Repository. Typically this requires creating a release repository on github and cloning it to your local machine.

Entering the Release Settings

After creating the release repository, you will need to create your release track. You can create a new one from scratch or copy and edit an old configuration. To create a new track:

$ cd /path/to/release/repository
$ git-bloom-config new hydro

Alternatively, to copy and edit from an old track:

$ cd /path/to/release/repository
$ git-bloom-config copy groovy hydro
$ git-bloom-config edit hydro

Where hydro is the name of the track you created (and is typically the name of the rosdistro you want to release to). Follow the instructions for configuring a release track to enter the configuration, barring the following differences.

The Version entry:

Version:
  :{ask}
    This means that the user will be prompted for the version each release.
    This also means that the upstream devel will be ignored.
  :{auto}
    This means the version will be guessed from the devel branch.
    This means that the devel branch must be set, the devel branch must exist,
    and there must be a valid package.xml in the upstream devel branch.
  <version>
    This will be the version used.
    It must be updated for each new upstream version.
  [':{auto}']: 

Since there is no package.xml upstream bloom cannot guess the version :{auto}, but we can make bloom prompt the releaser for the version each time by putting in :{ask}.

The "Patches Directory" entry. Set this to hydro or any name you like. This will be the folder in the master branch which contains you package.xml.

Adding a Package.xml to the master Branch

Now that we have informed bloom that there will be patches in the master branch under the hydro folder (or whatever you told it) we need to put a package.xml there for it to overlay onto the upstream have importing. First change to the master branch and create the patches folder you specified above:

$ git checkout master
$ mkdir hydro

Where hydro is the name you put in for the "Patches Directory".

Now create package.xml in the folder you just created using this: catkin/package.xml as a reference, making sure to run_depend on catkin.

Also, rather than putting an actual version in the <version> tag put :{version}. :{version} will be replaced by the version being released each time. For example:

<?xml version="1.0"?>
<package>
  <name>foo</name>
  <version>:{version}</version>
  <description>The foo package</description>

  <maintainer email="user@todo.todo">user</maintainer>
  <license>BSD</license>

  <run_depend>catkin</run_depend>
  <buildtool_depend>cmake</buildtool_depend>
  <build_depend>boost</build_depend>
  <run_depend>boost</run_depend>

  <export>
    <build_type>cmake</build_type>
  </export>
</package>

In the case described above, each time you run bloom on the release repository, the user will be prompted for the version being released, an archive of the upstream source code will be fetched based on the "release tag" configuration, imported into the release repository's upstream branch, the package.xml is overlaid onto the upstream branch, and the :{version} token in the package.xml is replaced by the version given by the user.

At this point you need to commit the package.xml template to the master branch:

• $ git add hydro/package.xml
  $ git commit -m "Added package.xml template"

Adding an Install Rule as a Patch

Before adding the install rule as a patch you need to run git-bloom-release once so that there is a release branch to patch:

• $ git-bloom-release hydro

Where hydro is the name of the track you created earlier.

After running once you can add your patch. Start by checking out the release branch:

• $ git checkout release/hydro/foo

Where the release tag is release/rosdistro/packagename.

Now on this branch edit your build system to install the package.xml. In CMake it should look something like this:

...
# Install catkin package.xml
install(FILES package.xml DESTINATION share/foo)
...

Where foo is the name of the package (the value in the <name> tag of the package.xml).

Once you have added this to your build system, commit and push back to the remote:

• $ git add .
  $ git commit -m "Added install rule for package.xml"
  $ git-bloom-patch export
  $ git push

Now simply run git-bloom-release again:

• $ git-bloom-release hydro

Where hydro is the name of the track you created and released previously.

Now your release repository has been setup, you will not need to do anything special for future releases.

Adding additional patches to the upstream repository

Follow the same process as patching in the package.xml installation from above. Remember to call git-bloom-patch export after you've made more commits into release/rosdistro/foo to export the patches.

Porting patches from one rosdistro to another

If you've setup a number of patches to the upstream repo for an older rosdistro release (for instance, groovy), and would like to port those patches to a newer rosdistro, then follow the instructions below:

First, perform a release for the newer rosdistro (hydro) to make sure there is a release branch to patch:

• $ git-bloom-release hydro

Then, checkout the patches from your older rosdistro (groovy), and import them to the newer rosdistro (hydro):

• $ git checkout patches/release/hydro/foo
  $ git ls-tree --name-only -r patches/release/groovy/foo | grep '\.patch' | xargs -I {} sh -c 'git show patches/release/groovy/foo:"$1" > "$1"' -- {}
  $ git add .
  $ git commit -m "Importing patches from groovy release branch"
  $ git checkout release/hydro/foo
  $ git-bloom-patch import
  $ git push --all
  $ git push --tags

Then perform a release as usual:

• $ git-bloom-release hydro

Finishing the Release

Now you can finish the first time release tutorial, starting with Running bloom for the First Time.

Future Releases

After the first release, where you added a template package.xml and a release branch patch, you can just follow the Releasing a catkin Package tutorial for successive releases.

Troubleshooting

There are a few more details which might be necessary for some releases and for converting previously released third party packages using the new recommendation.

Custom Build Commands

Some packages require more options than the standard cmake && make && make install to be built, and some other packages are not even CMake. In these cases the rules file in the debian folder needs to be modified. To do this run the git-bloom-release command at least once and then checkout to the debian branch:

• $ git checkout debian/hydro/foo

Where hydro is the ROS distro being released for and foo is the name of the package.

In this branch there should be a debian folder containing the template files, among them: rules.em. Edit this file to fit your needs and then commit the changes:

• $ git add debian/rules.em
  $ git commit -m "Customized debian rules file"
  $ git-bloom-patch export

Then rerun bloom:

• $ git-bloom-release hydro

Where hydro is the name of the track you wish to run.