Skip to content

Commit

Permalink
Update Installation instructions after latest releases (#360) (#366)
Browse files Browse the repository at this point in the history 
* WIP



* Update build



* Add doc for development and release



* Add distro source build



* Address feedback



* Update docs/Development-and-Release.md




* Update docs/Development-and-Release.md




* Update docs/Development-and-Release.md




* Update docs/Development-and-Release.md




* Update README.md




* Update README.md




* Update README.md




* Update docs/Development-and-Release.md




* Update README.md




---------

Signed-off-by: Yadunund <[email protected]>
Signed-off-by: Yadu <[email protected]>
Co-authored-by: Aaron Chong <[email protected]>
  • Loading branch information
@Yadunund @aaronchongth
Yadunund and aaronchongth authored Jun 15, 2023
1 parent eebc7f2 commit 3914da0
Show file tree
Hide file tree
Showing 3 changed files with 119 additions and 84 deletions.
3 changes: 1 addition & 2 deletions .github/workflows/nightly.yaml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
name: nightly
on:
pull_request:
on:
schedule:
- cron: '1 8 * * *'

Expand Down
168 changes: 86 additions & 82 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,151 +9,151 @@ The Open-RMF platform for multi-fleet robot management.

---

These are the current Open-RMF binary releases available:

| RMF Version | Installation Instructions | Supported distros | Supported ROS2 versions |
| ----------- | -------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------- |
| 22.09 |  [Install RMF 22.09](https://github.com/open-rmf/rmf/tree/release/22.09) | Ubuntu 22.04, RHEL 8 (deployment only) | Humble |
| ~~21.09~~ (EOL) |  ~~[Install RMF 21.09](https://github.com/open-rmf/rmf/tree/release/21.09)~~ | ~~Ubuntu 20.04, Ubuntu 21.09, RHEL 8 (deployment only)~~ | ~~Foxy, Galactic~~ |

## Installation Instructions

Even though binary versions are avilable, given the fast development and frequent updates to Open-RMF,
it is heavily recommended to follow instructions bellow and **install from
source**.

### Install ROS 2 Humble

First, please follow the installation instructions for ROS 2 Humble.
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).
Open-RMF is a collection of packages, some of which have ROS 2 dependencies.
For convenience, we distribute and install Open-RMF along with ROS 2 and is currently supported for the following ROS 2 distributions:
* [Iron Irwini](https://docs.ros.org/en/iron/index.html) (`iron`)
* [Humble Hawksbill](https://docs.ros.org/en/humble/index.html) (`humble`)
* [Rolling Ridley](https://docs.ros.org/en/rolling/index.html) (`rolling`)

### Setup Gazebo repositories
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.

Setup your computer to accept Gazebo packages from packages.osrfoundation.org.
Options for installing Open-RMF:
* [Binary installation (recommended)](#binary-installation)
* [Building from source](#building-from-source)

```bash
sudo apt update
sudo apt install -y wget
sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
wget https://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -
```
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.

### Building from sources (Recommended)
### Setup
Instruction below are aimed at `Ubuntu 22.04`.

In order to get the latest developments we recommend you to install from sources and compile Open-RMF yourself.
First please follow the installation instructions to install ROS 2 for the `distro` of choice from supported versions listed above.
It is recommended to install ROS 2 via binary debians.

#### Additional Dependencies
> 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.
Install all non-ROS dependencies of Open-RMF packages,

```bash
sudo apt update && sudo apt install \
git cmake python3-vcstool python3-pip curl \
python3-pip \
curl \
python3-colcon-mixin \
ros-dev-tools \
-y

sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
wget https://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -

python3 -m pip install flask-socketio fastapi uvicorn datamodel_code_generator
sudo apt-get install python3-colcon*
```

#### Install rosdep

`rosdep` helps install dependencies for ROS packages across various distros. It can be installed with:
`rosdep` helps install dependencies for ROS packages across various distros and will be installed along with `ros-dev-tools`.
However, it is important to update it.

```bash
sudo apt install python3-rosdep
sudo rosdep init
sudo rosdep init # run if first time using rosdep.
rosdep update
```

#### Download the source code
Update `colcon mixin` if you have not done so previously.

> 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.
```bash
colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
colcon mixin update default
```

Setup a new ROS 2 workspace and pull in the demo repositories using `vcs`,
### Binary installation
First follow the instruction in the [Setup section](#setup).
Finally install Open-RMF debian packages for the `distro` of choice.

```bash
mkdir -p ~/rmf_ws/src
cd ~/rmf_ws
wget https://raw.githubusercontent.com/open-rmf/rmf/main/rmf.repos
vcs import src < rmf.repos
sudo apt update && sudo apt install ros-<distro>-rmf-dev
```

Ensure all ROS 2 prerequisites are fulfilled,
**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).

you can subsutitute your distro name for `<your ros distro>`
To build `rmf_demos` from source, first determine the version of `rmf_demos` that corresponds to the latest binary release for your distro.
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).

Example:
for `humble`
Next create a ROS 2 workspace and build `rmf_demos` from source.
Replace the `2.0.3` tag below with the version of `rmf_demos` for your distribution.

```bash
mkdir ~/rmf_ws/src -p
cd ~/rmf_ws/src
git clone https://github.com/open-rmf/rmf_demos.git -b 2.0.3
cd ~/rmf_ws
rosdep install --from-paths src --ignore-src --rosdistro humble -y
colcon build
```

#### Compiling Instructions
To run some demonstrations of Open-RMF in simulation, see [README in rmf_demos](https://github.com/open-rmf/rmf_demos).

> 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*`.
Compiling on `Ubuntu 22.04`:

##### Install clang
### Building from source
First follow the instruction in the [Setup section](#setup).

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.
```bash
sudo apt update
sudo apt install clang clang-tools lldb lld libstdc++-12-dev
sudo apt purge ros-<distro>-rmf* && sudo apt autoremove
```

**NOTE: We strongly recommend compiling Open-RMF packages with `clang` as compiler and `lld` as linker.**
#### Download the source code
Open-RMF is a collection of several repositories/packages.
The [rmf.repos](https://github.com/open-rmf/rmf/blob/main/rmf.repos) provides a snapshot of these packages.
This repository stores different versions of this file depending on the ROS 2 distribution and version of the release.
Depending on the use case, you may choose to download this file from one of the following branches in this repository:
* `main` : Latest version of all packages which may or may not have a binary release yet. This is recommended for development and bug fixes.
* `<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.
* `<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.
* `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.

##### Compile using clang

Update colcon mixin which is a one time step:
Setup a new ROS 2 workspace and pull in the demo repositories using `vcs`.
Replace `main` with the branch of your choice.

```bash
colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
colcon mixin update default
mkdir -p ~/rmf_ws/src
cd ~/rmf_ws
wget https://raw.githubusercontent.com/open-rmf/rmf/main/rmf.repos
vcs import src < rmf.repos
```

Compile the workspace:
Install dependencies via `rosdep`.
Replace `humble` with ROS 2 distro of your choice.

```bash
cd ~/rmf_ws
source /opt/ros/humble/setup.bash

export CXX=clang++
export CC=clang
colcon build --mixin release lld
rosdep install --from-paths src --ignore-src --rosdistro humble -y
```

> 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.
> 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).
### Binary install

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:
**NOTE: We strongly recommend compiling Open-RMF packages with `clang` as compiler and `lld` as linker.**

```bash
apt-cache search ros-humble-rmf
sudo apt update
sudo apt install clang clang-tools lldb lld libstdc++-12-dev
```

#### RMF Demos
Compile the workspace after sourcing the ROS 2 distro of choice.

**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).
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.
Please follow the instructions in the [Additional Dependencies](#additional-dependencies) section to install `fastapi` along with other dependencies needed to run Open-RMF demos.
```bash
cd ~/rmf_ws
source /opt/ros/humble/setup.bash # replace humble with ROS 2 distro of choice.

[//]: # (A good way to install the `rmf` set of packages in one go is to install the one of the main [RMF Demos]&#40;https://github.com/open-rmf/rmf_demos&#41; 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:)
export CXX=clang++
export CC=clang
colcon build --mixin release lld
```

[//]: # ()
[//]: # (```bash)
> 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`
[//]: # (sudo apt install ros-humble-rmf-demos-gz-classic)
[//]: # (```)
To run some demonstrations of Open-RMF in simulation, see [README in rmf_demos](https://github.com/open-rmf/rmf_demos).

### Docker Containers

Alternatively, you can run RMF Demos by using [docker](https://docs.docker.com/engine/install/ubuntu/).
We also provide a [docker](https://docs.docker.com/engine/install/ubuntu/) image for Open-RMF.

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)).
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)).

```bash
docker pull ghcr.io/open-rmf/rmf/rmf_demos:latest
Expand Down Expand Up @@ -190,3 +190,7 @@ A number of commercial robots, infrastructure systems, workcells and devices hav
Help us add to this list!

A helpful starting point for integrating your fleet with RMF is the [fleet_adapter_template](https://github.com/open-rmf/free_fleet) package.

## Development and Release

More information for on the development and release process may be found [here](docs/Development-and-Release.md)
32 changes: 32 additions & 0 deletions docs/Development-and-Release.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
## Development and Release

The development, versioning and release of Open-RMF follows that of the [ROS 2 project](https://docs.ros.org/en/rolling/).

### Development and versioning
* 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.
* Repositories also have ROS 2 distro branches, eg., `humble`, containing versions of the packages distributed as a binary for that distro.
* 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.
* 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).
* 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`.
* Do not update any changelogs.

### Release
* Open-RMF binaries for new ROS 2 distributions will be available along with the new release of ROS 2.
* 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)
* 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.
* Binary packages may be updated by running `sudo apt update && sudo apt upgrade -y`.


### Additional information for maintainers
* We release into ROS 2 Rolling from the `main` source branch and from `<distro>` branches into supported ROS 2 distributions.
* 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.
* 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.
* The release repositories for Open-RMF are found in the [ros2-gbp](https://github.com/ros2-gbp) Github organization.
* 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.
* Please be mindful of the following when making a release for a repository:
* 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.
* 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`.
* If anything goes wrong during the release, bump the patch version, create a new tag, and make another release (numbers are cheap).
* 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.
* 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.
* Make an announcements regarding new releases on the `openrmf-general` Discord channel and on [ROS Discourse](https://discourse.ros.org/).

0 comments on commit 3914da0

Please sign in to comment.