This repository acts as an index for the ROS distributions. If you would like to add a package to the index you can either index it for just documentation, for binary builds or continuous integration tests. This repository also holds the rosdep rules.
If you would like to add a package for binary release please see the Bloom documentation. Bloom is a tool which will help you do the release as well as open a pull-request for you. It will also assist adding documentation and source entries. There are several helpful tutorials which provide instructions on how to do things like make a first release.
If you just want to submit for documentation indexing only this tutorial will get you going.
If you would like to index your package for continuous integration tests you can add a source entry in the same way as the documentation index.
The version field is required to be a branch name. This is due to the Jenkins Git Plugin that will always trigger if a repository has changed. After querying Cloudbees support they replied with:
The git plugin is configured to build for a tag / sha1 will always trigger a build.
As such the CI on this repository will enforce that the source version is a branch to not cause continuous triggering of builds. Also of note is that a tag has priority over a branch with the same name so a tag with the same name as the branch cannot exist either.
This repository also holds the rosdep keys. There is a guide for submitting rosdep keys here. Updates to rosdep rules require the review of two people. This will usually means that it needs a +1, and then it can be merged by a different person.
For convenience in reviewing, please comment in the PR with links to the web listings of packages such as on http://packages.ubuntu.com, http://packages.debian.org, and https://apps.fedoraproject.org/packages or if a pip package pypi.python.org.
Please also briefly describe the package being added and what use case you want to use it for. It's valuable to have a record of the packages as submitted and their intended purpose for clarity in the future so that if there's a conflict there's information to fall back on instead of speculation about the original use cases.
- Native packages are strongly preferred. (They are required for packaging and have upgrade and conflict tracking.)
- Please use the smallest notation possible. For example if an ubuntu package is the same for all versions only write the generic ubuntu rule, don't call out the same package name for every version of ubuntu. Similarly don't call out indirect dependencies or default options for packages.
- Python packages should go in the
python.yaml. - Homebrew into
osx-homebrew.yaml. - Supported Platforms
- Rules can be contributed for any platform. However to be released they must be at least cover the supported platforms in REP 3: http://www.ros.org/reps/rep-0003.html So:
- Ubuntu and Debian are top priority.
- Fedora and Gentoo have packaging jobs and should be filled in if they are available.
- OSX is also nice to have.
- If specific versions are called out, there should be coverage of all versions currently targeted by supported ROS distros.
- If there's a new distro in prerelease adding a rule for it is fine. However please don't target 'sid' as it's a rolling target and when the keys change our database gets out of date.
- Keep everything in alphabetical order for better merging.
- No trailing whitespace.
Keys in the rosdep database are required to come from packages contained in the following repositories only.
- Ubuntu Repositories: Main, Universe, or Multiverse
- ROS Sources: https://wiki.ros.org/Installation/Ubuntu/Sources
- Debian Repositories: Main, Universe, or Multiverse
- ROS Sources: https://wiki.ros.org/Installation/Ubuntu/Sources
- Fedora Project Repositories: release or updates
- CentOS Repositories: base, extras, centos-sclo-rh, or updates
- Additionally, for CentOS 8+: AppStream or PowerTools
- Fedora Project Repositories: epel
TODO
- Gentoo Portage Repository (e.g.
rsync://rsync.us.gentoo.org/gentoo-portage) - ROS-Overlay:
https://github.com/ros/ros-overlay
If the ebuild you are referencing is not in either of those locations, please file a PR into ROS-Overlay to add it and any needed dependencies to the tree.
Packages must be in the official Archlinux core, extra, or community repositories at the time they are contributed.
Packages in the AUR may not be added directly. Work has been proposed to add a separate installer for AUR packages ros-infrastructure/rosdep#560.
- FreeBSD project pkg repository: main or quarterly
- A database of FreeBSD packages is available at https://freshports.org
For pip installers they are expected to be in the main PyPI index https://pypi.org/.
When adding rules for python 3 packages, create a separate entry prefixed with python3- rather than python
For example:
python-foobar:
debian: [python-foobar]
fedora: [python2-foobar]
ubuntu: [python-foobar]
...
python3-foobar:
debian: [python3-foobar]
fedora: [python3-foobar]
ubuntu: [python3-foobar]You may see existing rules that use _python3-suffixed distribution codenames.
These were trialed as a possible style of Python 3 rules and should not be used.
The guidance above should be followed for new rules.
Additionally, if you rely on a dependency that uses _python3-suffixed codenames, add a new rule for it that follows the guidance above.
Python packages, which are only available on pip, should use the -pip extension. Also the python-/python3- prefix needs to be used.
For example:
python-foobar-pip:
ubuntu:
pip:
packages: [foobar]
...
python3-foobar-pip:
ubuntu:
pip:
packages: [foobar]When submitting pull requests it is expected that they pass the unit tests for formatting. The unit tests enforce alphabetization of elements and a consistant formatting to keep merging as clean as possible.
To run the tests run nosetests in the root of the repository.
These tests require several dependencies that can be installed either from the ROS repositories or via pip(list built based on the content of .travis.yaml:
| Dependency | Ubuntu package | Pip package |
|---|---|---|
| catkin_pkg | python-catkin-pkg | catkin-pkg |
| github | python-github | PyGithub |
| nose | python-nose | nose |
| rosdistro | python-rosdistro | rosdistro |
| ros_buildfarm | python-ros-buildfarm | ros-buildfarm |
| unidiff | python-unidiff (Zesty and higher) | unidiff |
| yamllint | yamllint | yamllint |
There is a tool rosdistro_reformat which will fix most formatting errors such as alphabetization and correct formatting.
Note: There's a known issue discovered here that most tests won't run if you have the python package nose-unitttest installed.