Skip to content

Latest commit

 

History

History
190 lines (128 loc) · 6.15 KB

custom_rosdistro.rst

File metadata and controls

190 lines (128 loc) · 6.15 KB
Raw

Use a custom rosdistro database

Instead of using the official rosdistro database you can fork the repository to maintain a custom state. This enables you to decide when changes from the official database are being merged in order to:

  • achieve a more conservative release strategy
  • lock the version number of specific repositories / packages
  • add additional distribution files containing custom packages / repositories

After the initial fork it is your responsibility to keep the fork in sync if you so desire.

Full fork vs. add-on fork

Full Fork

A full fork (which could even be a completely independent repository) is not related to the official rosdistro database or the official ROS package repositories. You can create arbitrary distributions and the custom build farm is responsible to build all packages on its own.

Note: we highly recommend to name these custom distributions differently than the official ROS distribution to avoid confusion and allow side-by-side installation.

While this approach gives you the maximum control about what is being built it also requires the most resources to rebuild the ROS packages already available from the official ROS repositories.

Add-on fork

The fork only adds an additional distribution files (beside the one defined in the official rosdistro repository). This approach keeps using the packages generated by the official ROS build farm and only processes the additional custom packages / repositories.

This additional distributions file can then list custom packages / repositories. Keeping the two sets in separate files eases merging in changes from the upstream repository avoiding any conflicts.

Add a tag to custom distribution files

For more flexible configuration options you should always add a tag to your custom distribution file:

release_platforms:
  ...
repositories:
  ...
tags:
- YOUR_TAG
type: distribution
version: ...

This allows the build files in the ROS build farm configuration to specify a tag_whitelist to operate only on the packages / repositories from your custom distribution file.

Releasing into a custom rosdistro

Bloom will choose the last distribution file listed in the rosdistro index. In the add-on fork case that will be the added distribution file which will contain all custom released packages.

Import ROS packages which are not built by the custom build farm

Whenever you merge changes from the the upstream rosdistro repository into your custom fork you must also import the current snapshot of available packages from the official repositories.

To do this you will need to create an import config file. Create a file like import_indigo.yaml on the repository machine and invoke the import_upstream job with the absolute path to this yaml file as the parameter:

name: backfill-ros
method: http://packages.ros.org/ros/ubuntu/
suites: [trusty]
component: main
architectures: [amd64, source]
filter_formula: Package (% ros-indigo-* )

Use the forked rosdep database or keep using the official one?

With the fork of the rosdistro repository you also have a custom set of rosdep files. By default rosdep keeps using the database from the official repository.

If you want to maintain and use your custom version of the rosdep database included in the forked rosdistro repository you have to perform the following changes:

  • Update all URLs in the rosdep list file rosdep/sources.list.d/20-default.list to point to your custom fork.
  • Update any of the .yaml files as you like

After that every user must perform the following tasks to use your forked rosdep database:

  • Remove the existing rosdep list files:

    sudo rm /etc/ros/rosdep/sources.list.d/20-default.list

  • Download the custom rosdep list file:

    cd /etc/ros/rosdep/sources.list.d
sudo wget https://raw.githubusercontent.com/YOUR_FORK/rosdistro/master/rosdep/sources.list.d/20-default.list

  • Update the local rosdep database:

    rosdep update

To make devel jobs use your custom rosdep database, update the targets dict in the <distribution>/source_build.yaml file in your forked ros_buildfarm_config repository with the custom_rosdep_urls option:

targets:
  _config:
    custom_rosdep_urls:
      - https://raw.githubusercontent.com/YOUR_FORK/rosdistro/master/rosdep/sources.list.d/20-default.list

rosdep always uses the ROS packages defined by the ROSDISTRO_INDEX_URL variable when updating the rosdep database.

Mandatory changes when using a custom rosdistro database

Update reference to custom cache

The rosdistro entry point yaml file contains references to the rosdistro cache files.

After forking the repository you must update the URLs to your custom locations for each distribution:

distributions:
  ROS_DISTRO_NAME:
    distribution_cache: http://repo_hostname.example.com/rosdistro_cache/ROS_DISTRO_NAME-cache.yaml.gz

Update build farm configuration

You must change the URL pointing to the rosdistro index in the ROS build farm configuration:

rosdistro_index_url: https://raw.githubusercontent.com/YOUR_FORK/rosdistro/master/index.yaml

After changing the configuration of an existing build farm you have to redeploy all jobs.

Everybody must set ROSDISTRO_INDEX_URL

Every user must set an environment variable on the machine to use the custom rosdistro database:

ROSDISTRO_INDEX_URL=https://raw.githubusercontent.com/YOUR_FORK/rosdistro/master/index.yaml

Note if you're overlaying you need to add a rodep file for the underlayed rosdistro if using one: https://github.com/mikepurvis/rosdep-generator

After that they must also update the rosdep database to use the ROS packages from the custom rosdistro database:

rosdep update