You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Even though binary versions are avilable, given the fast development and frequent updates to Open-RMF,
22
-
it is heavily recommended to follow instructions bellow and **install from
23
-
source**.
24
-
25
-
### Install ROS 2 Humble
26
-
27
-
First, please follow the installation instructions for ROS 2 Humble.
28
-
If you are on an Ubuntu 22.04 LTS machine (as recommended), [here is the binary install page for ROS 2 Humble on Ubuntu 22.04](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html).
14
+
Open-RMF is a collection of packages, some of which have ROS 2 dependencies.
15
+
For convenience, we distribute and install Open-RMF along with ROS 2 and is currently supported for the following ROS 2 distributions:
We primarily support Debian packages on `Ubuntu Linux - Jammy Jellyfish (22.04)` and select RPM packages for `RHEL/Fedora` for both `amd64` and `aarch64` architectures.
31
21
32
-
Setup your computer to accept Gazebo packages from packages.osrfoundation.org.
If you want to try Open-RMF we recommend installing the binaries. Building from source is better suited for developers who wish to add new features or fix bugs.
40
27
41
-
### Building from sources (Recommended)
28
+
### Setup
29
+
Instruction below are aimed at `Ubuntu 22.04`.
42
30
43
-
In order to get the latest developments we recommend you to install from sources and compile Open-RMF yourself.
31
+
First please follow the installation instructions to install ROS 2 for the `distro` of choice from supported versions listed above.
32
+
It is recommended to install ROS 2 via binary debians.
44
33
45
-
#### Additional Dependencies
34
+
> Note: In order to install Open-RMF binaries, it is important to setup your computer to install ROS packages. This is a [prerequisite step](https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html#enable-required-repositories) when installing ROS 2 debian binaries.
46
35
47
36
Install all non-ROS dependencies of Open-RMF packages,
`rosdep` helps install dependencies for ROS packages across various distros. It can be installed with:
52
+
`rosdep` helps install dependencies for ROS packages across various distros and will be installed along with `ros-dev-tools`.
53
+
However, it is important to update it.
60
54
61
55
```bash
62
-
sudo apt install python3-rosdep
63
-
sudo rosdep init
56
+
sudo rosdep init # run if first time using rosdep.
64
57
rosdep update
65
58
```
66
59
67
-
#### Download the source code
60
+
Update `colcon mixin` if you have not done so previously.
68
61
69
-
> Note all repositories now have a `galactic-devel` branch. New changes will be targeted for `ROS2 Humble`. If any change is compatible with `ROS2 galactic` they will be backported to the `galactic-devel` branch.
**Note:** This will install all necessary debian packages to run Open-RMF except for those in [rmf_demos](https://github.com/open-rmf/rmf_demos) for reasons described in this [issue](https://github.com/open-rmf/rmf_demos/issues/166).
81
76
82
-
you can subsutitute your distro name for `<your ros distro>`
77
+
To build `rmf_demos` from source, first determine the version of `rmf_demos` that corresponds to the latest binary release for your distro.
78
+
For example, if you installed the `humble` binaries of Open-RMF, the version of `rmf_demos` for this release can be found in the `rmf.repos` file in the `humble-release` branch of this repository, for example [here](https://github.com/open-rmf/rmf/blob/591b0b9f34a021d81522a0af6f42ffcb5fc70293/rmf.repos#L5).
83
79
84
-
Example:
85
-
for `humble`
80
+
Next create a ROS 2 workspace and build `rmf_demos` from source.
81
+
Replace the `2.0.3` tag below with the version of `rmf_demos` for your distribution.
To run some demonstrations of Open-RMF in simulation, see [README in rmf_demos](https://github.com/open-rmf/rmf_demos).
93
92
94
-
> NOTE: Due to newer changes in the source build, there might be conflicts and compilation errors with older header files installed by the binaries. Please remove the binary installations before building from source, using `sudo apt remove ros-humble-rmf*`.
95
-
96
-
Compiling on `Ubuntu 22.04`:
97
-
98
-
##### Install clang
93
+
### Building from source
94
+
First follow the instruction in the [Setup section](#setup).
99
95
96
+
Due to newer changes in the source code, there might be conflicts and compilation errors with older header files installed by the binaries. Hence before proceeding, make sure to uninstall all Open-RMF binaries for the ROS 2 distro that will be sourced for the build.
**NOTE: We strongly recommend compiling Open-RMF packages with `clang` as compiler and `lld` as linker.**
101
+
#### Download the source code
102
+
Open-RMF is a collection of several repositories/packages.
103
+
The [rmf.repos](https://github.com/open-rmf/rmf/blob/main/rmf.repos) provides a snapshot of these packages.
104
+
This repository stores different versions of this file depending on the ROS 2 distribution and version of the release.
105
+
Depending on the use case, you may choose to download this file from one of the following branches in this repository:
106
+
*`main` : Latest version of all packages which may or may not have a binary release yet. This is recommended for development and bug fixes.
107
+
*`<distro>`: The latest version of the packages for a specific ROS 2 distro. This may be different from `main` as new API/ABI breaking features merged into `main` will not be backported into `<distro>` branches. The packages downloaded from `<distro>` may have changes that are not yet available in binaries.
108
+
*`<distro>-release` : Where `<distro>` is a supported ROS 2 distribution (eg. `humble`). The version of packages here will correspond to those of the latest binaries available for this distro.
109
+
*`release-<distro>-YYMMDD` : A tag for a specific `<distro>` where the version of packages correspond to those of the binaries available on `YYMMDD`. See [Releases](https://github.com/open-rmf/rmf/releases) for additional information for each release. This is useful if users would like to build packages from an older release.
106
110
107
-
##### Compile using clang
108
111
109
-
Update colcon mixin which is a one time step:
112
+
Setup a new ROS 2 workspace and pull in the demo repositories using `vcs`.
> NOTE: The first time the build occurs, many simulation models will be downloaded from Ignition Fuel to populate the scene when the simulation is run.
128
-
> As a result, the first build can take a very long time depending on the server load and your Internet connection (for example, 60 minutes).
129
-
130
-
### Binary install
131
-
132
-
Latest Open-RMF binary packages are available for Ubuntu Jammy 22.04 for the `Humble` and `Rolling` releases of ROS 2. Older releases are also available on Ubuntu Focal 20.04 for `Foxy` and `Galactic`. Most Open-RMF packages have the prefix `rmf` on their name, therefore, you can find them by searching for the pattern `ros-<ro2distro>-rmf`, e.g., for humble it would be:
130
+
**NOTE: We strongly recommend compiling Open-RMF packages with `clang` as compiler and `lld` as linker.**
Compile the workspace after sourcing the ROS 2 distro of choice.
139
138
140
-
**Note:** RMF Demos package cannot be installed on Humble distro because of an underlying [issue](https://github.com/open-rmf/rmf_demos/issues/166) with the release of a bad version of fastapi in jammy. You can install the package from [source](https://github.com/open-rmf/rmf/discussions/267).
141
-
It is important to have `fastapi` installed via `pip` and not as an Ubuntu system package (ie, via `apt install`) for the reasons documented above.
142
-
Please follow the instructions in the [Additional Dependencies](#additional-dependencies) section to install `fastapi` along with other dependencies needed to run Open-RMF demos.
139
+
```bash
140
+
cd~/rmf_ws
141
+
source /opt/ros/humble/setup.bash # replace humble with ROS 2 distro of choice.
143
142
144
-
[//]: #(A good way to install the `rmf` set of packages in one go is to install the one of the main [RMF Demos](https://github.com/open-rmf/rmf_demos) packages. This will pull all the rest of the Open-RMF packages as a dependency. The core of Open-RMF demos is contained on the `rmf_demos` package. However, if you want to install it with simulation support, you should install the `rmf_demos_gz` or `rmf_demos_gz_classic` package which come with Gazebo or Gazebo Classic support respectively. As an example, to install the ROS 2 Humble release with Gazebo support package, you would run:)
143
+
export CXX=clang++
144
+
export CC=clang
145
+
colcon build --mixin release lld
146
+
```
145
147
146
-
[//]: #()
147
-
[//]: #(```bash)
148
+
> NOTE: The first time the build occurs, many simulation models will be downloaded from Gazebo Fuel to populate the scene when the simulation is run. As a result, the first build can take a very long time depending on the server load and your internet connection (may be up to an hour). To build without downloading models append `--cmake-args -DNO_DOWNLOAD_MODELS=On` to the `colcon build`
To run some demonstrations of Open-RMF in simulation, see [README in rmf_demos](https://github.com/open-rmf/rmf_demos).
151
151
152
152
### Docker Containers
153
153
154
-
Alternatively, you can run RMF Demos by using [docker](https://docs.docker.com/engine/install/ubuntu/).
154
+
We also provide a [docker](https://docs.docker.com/engine/install/ubuntu/) image for Open-RMF.
155
155
156
-
Pull docker image from `open-rmf/rmf` github registry (setup refer [here](https://docs.github.com/en/free-pro-team@latest/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-with-a-personal-access-token)).
156
+
Pull the docker image from `open-rmf/rmf` github registry (setup refer [here](https://docs.github.com/en/free-pro-team@latest/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-with-a-personal-access-token)).
157
157
158
158
```bash
159
159
docker pull ghcr.io/open-rmf/rmf/rmf_demos:latest
@@ -190,3 +190,7 @@ A number of commercial robots, infrastructure systems, workcells and devices hav
190
190
Help us add to this list!
191
191
192
192
A helpful starting point for integrating your fleet with RMF is the [fleet_adapter_template](https://github.com/open-rmf/free_fleet) package.
193
+
194
+
## Development and Release
195
+
196
+
More information for on the development and release process may be found [here](docs/Development-and-Release.md)
The development, versioning and release of Open-RMF follows that of the [ROS 2 project](https://docs.ros.org/en/rolling/).
4
+
5
+
### Development and versioning
6
+
* The primary development branch is `main` on all repositories. This is the equivalent to `rolling` in ROS 2. Any `rolling` branches in Open-RMF repos should be ignored as they exist purely for legacy reasons.
7
+
* Repositories also have ROS 2 distro branches, eg., `humble`, containing versions of the packages distributed as a binary for that distro.
8
+
* All new features and bug fixes must target `main`. The changes may be backported via cherry-picks to one or more distro branches provided there are no API/ABI breaks.
9
+
* The version of packages on `main` must always be higher than on distro branches (at least 1 minor version higher) and newer distro versions must be higher than older ones (again, 1 minor version higher).
10
+
* Only patch version bumps are allowed on distro branches. This is to ensure distro branch versions do not increase higher than newer distros or `main`.
11
+
* Do not update any changelogs.
12
+
13
+
### Release
14
+
* Open-RMF binaries for new ROS 2 distributions will be available along with the new release of ROS 2.
15
+
* Roughly monthly, patch releases for packages with changes will be available in source and binary forms. All releases will be announced [here](https://github.com/open-rmf/rmf/releases)
16
+
* Source releases are in the form of a [tagged rmf.repos](https://github.com/open-rmf/rmf/blob/release-humble-230606/rmf.repos) file. The least `rmf.repos` file in `<distro>-release` branches contain the latest tags for all the repos for that `<distro>`. The `release-<distro>-YYMMDD` tags are useful for checking out packages to particular release versions.
17
+
* Binary packages may be updated by running `sudo apt update && sudo apt upgrade -y`.
18
+
19
+
20
+
### Additional information for maintainers
21
+
* We release into ROS 2 Rolling from the `main` source branch and from `<distro>` branches into supported ROS 2 distributions.
22
+
* Reference this [dashboard](https://osrf.github.io/osr_dashboard/?distribution=rmf-rolling) to get an overview of Open-RMF repositories with any new commits since the last release.
23
+
* Git `tags` are the most important thing to get right about making a release. A `tag` is associated with a commit and `bloom` will look for new tags in the source branch when making a release. If a commit in a PR was tagged and that PR was squash merged in, the `tag` will not be present in the source branch after the merge.
24
+
* The release repositories for Open-RMF are found in the [ros2-gbp](https://github.com/ros2-gbp) Github organization.
25
+
* Follow [these](https://docs.ros.org/en/rolling/How-To-Guides/Releasing/Releasing-a-Package.html) instructions to release a package and use `catkin_generate_changelogs` to update the changelog files, `catkin_prepare_release` to bump package versions, and `bloom-release` to perform the release for a specified distro. If you do not have access to push the changes directly to the branch, please open a PR. But if the push failed, please ensure to delete any `tags` that were created both locally and upstream before opening the PR.
26
+
* Please be mindful of the following when making a release for a repository:
27
+
* Ensure that the [tracks.yaml](https://github.com/ros2-gbp/rmf_task-release/blob/master/tracks.yaml) for a repository has a track configured for the ROS 2 distro for which you are making the release.
28
+
* Ensure that the `devel_branch` for the track matches the source branch to release from. Tracks for ROS 2 distributions should have `<distro>` as the `devel_branch`.
29
+
* If anything goes wrong during the release, bump the patch version, create a new tag, and make another release (numbers are cheap).
30
+
* Once the packages bloom successfully and changes are accepted upstream in `rosdistro`, open a PR to update the `rmf.repos` file in `<distro>-release` with the latest tags. Once merged, create and push a new tag `<release-<distro>-YYMMDD>` and publish a new Github release in this repository.
31
+
* Closer to the next ROS 2 release, do another round of releases into Rolling from `main`. Branch from main to create the new `<distro>` branch and do a minor bump on `main` to keep it ahead of the newly created `<distro>` branch. Then create a new track in the `tracks.yaml` for this repository to bloom from this `<distro>` branch into the next ROS 2 distribution.
32
+
* Make an announcements regarding new releases on the `openrmf-general` Discord channel and on [ROS Discourse](https://discourse.ros.org/).
0 commit comments