Skip to content

docs(readme): improve formatting and add installation workarounds #589

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
esteve merged 1 commit into from
Jan 26, 2026
Merged

docs(readme): improve formatting and add installation workarounds #589

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 52 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,24 +6,22 @@ ROS 2 for Rust
[![Win CI Status](https://github.com/ros2-rust/ros2_rust/actions/workflows/rust-win.yml/badge.svg?branch=main)](https://github.com/ros2-rust/ros2_rust/actions/workflows/rust-win.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Introduction
------------
## Introduction

This is a set of projects (the `rclrs` client library, code generator, examples and more) that
This is a set of projects (the `rclrs` client library, code generator, examples, and more) that
enables developers to write ROS 2 applications in Rust.

Features and limitations
------------------------
## Features and Limitations

The current set of features include:
The current set of features includes:
- Message generation with support for all ROS message types
- Publishers and subscriptions (including async variants)
- Loaned messages (zero-copy messaging)
- Dynamic message handling (runtime message introspection and manipulation)
- Tunable QoS settings
- Clients and services (including async variants)
- Actions (action servers and clients with async support)
- Timers (repeating, oneshot, and inert timers)
- Timers (repeating, one-shot, and inert timers)
- Parameters (mandatory, optional, and read-only with parameter services)
- Logging with ROS-compliant logging utilities and rosout support
- Graph queries (topic/node discovery, endpoint information)
Expand All @@ -36,8 +34,7 @@ Some things are still missing however, see the [issue list](https://github.com/r

Since the client library is still rapidly evolving, there are no stability guarantees for the moment.

Installation
------------
## Installation

### Prerequisites

Expand All @@ -54,27 +51,48 @@ sudo apt install -y git libclang-dev python3-pip python3-vcstool
pip install --break-system-packages colcon-cargo colcon-ros-cargo
```

### All ROS distributions
Because of an issue in `rclrs` (https://github.com/ros2-rust/ros2_rust/issues/557), as a workaround, the following two packages need to be installed:

`rclrs` is released on [crates.io](https://crates.io/crates/rclrs), you can add it to your project directly:
```shell
# Install workaround packages
sudo apt install -y ros-$ROS_DISTRO-example-interfaces
sudo apt install -y ros-$ROS_DISTRO-test-msgs
```

### All ROS Distributions

`rclrs` is released on [crates.io](https://crates.io/crates/rclrs) and you can add it to your project directly:

```toml
[dependencies]
rclrs = "0.7"
```

Due to different ROS 2 distributions having different levels of integration with `rclrs`, if you'd like to
build and run the examples, please follow the according section.
build and run the examples, please follow the corresponding section.

### ROS 2 Lyrical Luth and Rolling

To run the examples, install the `test_msgs` and `example_interfaces` packages,
clone the examples repository to your workspace and build:
To run the examples, install the `test_msgs` and `example_interfaces` packages, clone the examples repository to your workspace, and build:

```shell
sudo apt install -y ros-rolling-example-interfaces ros-rolling-test-msgs
mkdir -p workspace/src && cd workspace
git clone https://github.com/ros2-rust/examples.git src/examples
```

Temporarily (as of 2025-01-21), the `rosidl_rust` repository which contains the code generator needs to be cloned as well:

```shell
mkdir -p workspace/src && cd workspace
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
```

The above commands can be removed once an updated version of the generator is shipped with the next ROS 2 sync.

Build the workspace:

```shell
. /opt/ros/rolling/setup.sh # Or source your ROS 2 installation
colcon build
```
Expand All @@ -88,9 +106,19 @@ mkdir -p workspace/src && cd workspace
git clone -b kilted https://github.com/ros2/common_interfaces.git src/common_interfaces
git clone -b kilted https://github.com/ros2/example_interfaces.git src/example_interfaces
git clone -b kilted https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
git clone -b kilted https://github.com/ros2/rosidl_core.git src/rosidl_core
git clone -b kilted https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
git clone -b kilted https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
```

Temporarily (as of 2025-01-21), the `rosidl_rust` repository which contains the code generator needs to be cloned as well:

```shell
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
```

The above command can be removed once an updated version of the generator is shipped with the next ROS 2 sync.

Build the workspace:

```shell
Expand All @@ -104,11 +132,13 @@ For ROS 2 Jazzy, you need to clone the code generator and message packages to yo

```shell
mkdir -p workspace/src && cd workspace
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
git clone -b jazzy https://github.com/ros2/common_interfaces.git src/common_interfaces
git clone -b jazzy https://github.com/ros2/example_interfaces.git src/example_interfaces
git clone -b jazzy https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
git clone -b jazzy https://github.com/ros2/rosidl_core.git src/rosidl_core
git clone -b jazzy https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
git clone -b jazzy https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
git clone https://github.com/ros2-rust/examples.git src/examples
```

Expand All @@ -126,11 +156,13 @@ For ROS 2 Humble, you need to clone the code generator and message packages to y

```shell
mkdir -p workspace/src && cd workspace
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
git clone -b humble https://github.com/ros2/common_interfaces.git src/common_interfaces
git clone -b humble https://github.com/ros2/example_interfaces.git src/example_interfaces
git clone -b humble https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
git clone -b humble https://github.com/ros2/rosidl_core.git src/rosidl_core
git clone -b humble https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
git clone -b humble https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
git clone https://github.com/ros2-rust/examples.git src/examples
```

Expand All @@ -153,7 +185,8 @@ ros2 run examples_rclrs_minimal_pub_sub minimal_publisher
. ./install/setup.sh
ros2 run examples_rclrs_minimal_pub_sub minimal_subscriber
```
or

Or:

```shell
# In a new terminal (or tmux window)
Expand All @@ -163,6 +196,7 @@ ros2 launch examples_rclrs_minimal_pub_sub minimal_pub_sub.launch.xml

For detailed building instructions and additional setup options, see the [in-depth guide](docs/building.md).

Further documentation articles:
## Further Documentation

- [Tutorial on writing your first node with `rclrs`](docs/writing-your-first-rclrs-node.md)
- [Contributor's guide](docs/CONTRIBUTING.md)