= Releasing a Third Party Package =

<<TableOfContents(4)>>

{{{#!wiki solid/blue
By default, bloom releases packages to the public ROS build farm.
See [[build.ros.org]] for more information and for policies about released packages.
}}}

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 [[http://ros.org/reps/rep-0136.html|REP-0136]]. Basically the package must do these things:

 * Have a catkin [[catkin/package.xml|package.xml]]
  * Which `run_depend`'s on catkin
  * And which has a `<build_type>` tag in the `<export>` tag
 * Install a catkin [[catkin/package.xml|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 [[bloom/Tutorials/FirstTimeRelease#Creating_a_Release_Repository|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 [[bloom/Tutorials/FirstTimeRelease#Configure_a_Release_Track| 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`.

{{{#!wiki blue/solid
'''Note:''' Notice that the release template is based on the ''package'' name as opposed to the ''repository'' name. A repository can have multiple packages with in it, therefore there might be multiple `release/rosdistro/*` branches. You would need to make a similar install rule patch to each of them.
}}}

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 [[http://www.ros.org/wiki/bloom/Tutorials/FirstTimeRelease#Releasing_Your_Packages|Running bloom for the First Time]].

{{{#!wiki blue/solid
'''Note:''' If you are rereleasing a third party package to meet the new recommendation you should make sure there are no patches to the release/* or debian/* branches which need to be ported.
}}}

== Future Releases ==

After the first release, where you added a template package.xml and a release branch patch, you can just follow the [[bloom/Tutorials/ReleaseCatkinPackage|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.