ROS 2 for Rust ==============

Introduction

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

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, 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)
• Guard conditions and wait sets
• Clock and time APIs (including time sources)
• Worker pattern for managing shared state across callbacks
• Executor pattern for coordinating node execution

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

Installation

Prerequisites

First, install Rust and the required system dependencies:

# Install Rust (see https://rustup.rs/)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Install required system packages
sudo apt install -y git libclang-dev python3-pip python3-vcstool
Install colcon plugins for Rust
pip install --break-system-packages colcon-cargo colcon-ros-cargo

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:

# 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 and you can add it to your project directly:

[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 corresponding section.

ROS 2 Lyrical Luth and Rolling

To run the examples, install the testmsgs and exampleinterfaces packages, clone the examples repository to your workspace, and build:

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:

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

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

Build the workspace:

. /opt/ros/rolling/setup.sh  # Or source your ROS 2 installation
colcon build

ROS 2 Kilted Kaiju

For ROS 2 Kilted, clone the ROS 2 message packages to your workspace:

mkdir -p workspace/src && cd workspace
git clone -b kilted https://github.com/ros2/commoninterfaces.git src/commoninterfaces
git clone -b kilted https://github.com/ros2/exampleinterfaces.git src/exampleinterfaces
git clone -b kilted https://github.com/ros2/rclinterfaces.git src/rclinterfaces
git clone -b kilted https://github.com/ros2/rosidlcore.git src/rosidlcore
git clone -b kilted https://github.com/ros2/rosidldefaults.git src/rosidldefaults
git clone -b kilted https://github.com/ros2/uniqueidentifiermsgs.git src/uniqueidentifiermsgs

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

git clone https://github.com/ros2-rust/rosidlrust.git src/rosidlrust

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

Build the workspace:

. /opt/ros/kilted/setup.sh
colcon build

ROS 2 Jazzy Jalisco

For ROS 2 Jazzy, you need to clone the code generator and message packages to your workspace:

mkdir -p workspace/src && cd workspace
git clone -b jazzy https://github.com/ros2/commoninterfaces.git src/commoninterfaces
git clone -b jazzy https://github.com/ros2/exampleinterfaces.git src/exampleinterfaces
git clone -b jazzy https://github.com/ros2/rclinterfaces.git src/rclinterfaces
git clone -b jazzy https://github.com/ros2/rosidlcore.git src/rosidlcore
git clone -b jazzy https://github.com/ros2/rosidldefaults.git src/rosidldefaults
git clone -b jazzy https://github.com/ros2/uniqueidentifiermsgs.git src/uniqueidentifiermsgs
git clone https://github.com/ros2-rust/rosidlrust.git src/rosidlrust
git clone https://github.com/ros2-rust/examples.git src/examples

Build the workspace:

. /opt/ros/jazzy/setup.sh
colcon build

ROS 2 Humble Hawksbill

For ROS 2 Humble, you need to clone the code generator and message packages to your workspace:

mkdir -p workspace/src && cd workspace
git clone -b humble https://github.com/ros2/commoninterfaces.git src/commoninterfaces
git clone -b humble https://github.com/ros2/exampleinterfaces.git src/exampleinterfaces
git clone -b humble https://github.com/ros2/rclinterfaces.git src/rclinterfaces
git clone -b humble https://github.com/ros2/rosidlcore.git src/rosidlcore
git clone -b humble https://github.com/ros2/rosidldefaults.git src/rosidldefaults
git clone -b humble https://github.com/ros2/uniqueidentifiermsgs.git src/uniqueidentifiermsgs
git clone https://github.com/ros2-rust/rosidlrust.git src/rosidlrust
git clone https://github.com/ros2-rust/examples.git src/examples

Build the workspace:

. /opt/ros/humble/setup.sh
colcon build

Running the examples

After building, source your workspace and run the examples:

# In a new terminal (or tmux window)
. ./install/setup.sh
ros2 run examplesrclrsminimalpubsub minimal_publisher
In a new terminal (or tmux window)
. ./install/setup.sh
ros2 run examplesrclrsminimalpubsub minimal_subscriber

Or:

# In a new terminal (or tmux window)
. ./install/setup.sh
ros2 launch examplesrclrsminimalpubsub minimalpubsub.launch.xml

For detailed building instructions and additional setup options, see the in-depth guide.

Further Documentation

• Tutorial on writing your first node with rclrs
• Contributor's guide