Building ros-z

ros-z is designed to work without ROS 2 dependencies by default, enabling pure Rust development while optionally integrating with existing ROS 2 installations. This flexible approach lets you choose your dependency level based on project requirements.

Philosophy

ros-z follows a dependency-optional design:

• Build pure Rust applications without ROS 2 installed
• Use bundled message definitions for common types
• Opt-in to ROS 2 integration when needed
• Pay only for what you use

Adding ros-z to Your Project

Get started by adding ros-z to your Cargo.toml. Choose the dependency setup that matches your needs:

Scenario 1: Pure Rust with Custom Messages

Use when: You want to define your own message types without ROS 2 dependencies

Add to your Cargo.toml:

[dependencies]
ros-z = "0.x"
tokio = { version = "1", features = ["full"] }  # Async runtime required

What you get:

• Full ros-z functionality
• Custom message support via derive macros
• Zero external dependencies
• Fast build times

Scenario 2: Using Bundled ROS Messages

Use when: You need standard ROS 2 message types but don't have ROS 2 installed

Add to your Cargo.toml:

[dependencies]
ros-z = "0.x"
ros-z-msgs = "0.x"  # Includes std_msgs, geometry_msgs, sensor_msgs, nav_msgs
tokio = { version = "1", features = ["full"] }

Bundled message packages:

• std_msgs - Primitive types (String, Int32, Float64, etc.)
• geometry_msgs - Spatial data (Point, Pose, Transform, Twist)
• sensor_msgs - Sensor data (LaserScan, Image, Imu, PointCloud2)
• nav_msgs - Navigation (Path, OccupancyGrid, Odometry)

Scenario 3: Full ROS 2 Integration

Use when: You need all ROS 2 message types or custom packages from your workspace

Requirements: ROS 2 installation (Jazzy, Humble, Rolling, etc.)

Add to your Cargo.toml:

[dependencies]
ros-z = "0.x"
ros-z-msgs = { version = "0.x", features = ["external_msgs"] }
tokio = { version = "1", features = ["full"] }

The external_msgs feature flag tells ros-z-msgs to generate bindings for all message types found in your ROS 2 installation. Without this flag, only bundled messages are included (Scenario 2).

Build your project:

# Ensure ROS 2 is sourced (Jazzy as an example)
source /opt/ros/jazzy/setup.bash

# Build your project with external_msgs feature
# This feature enables access to all ROS 2 message types from your installation
cargo build --features external_msgs

Additional packages available:

• example_interfaces - Tutorial services and actions
• action_msgs - Action communication types
• Any custom messages from your ROS 2 workspace

ROS 2 Distribution Compatibility

ros-z defaults to ROS 2 Jazzy compatibility, which is the recommended distribution for new projects. If you need to target a different distribution like Humble, see the ROS 2 Distribution Compatibility chapter for detailed instructions.

Quick reference:

# Default (Jazzy) - works out of the box
cargo build

# For Humble - use --no-default-features
cargo build --no-default-features --features humble

# For Rolling/Iron - just add the feature
cargo build --features rolling

The distribution choice affects type hash support and interoperability with ROS 2 nodes. See the Distribution Compatibility chapter for full details.

Development

This section is for contributors working on ros-z itself. If you're using ros-z in your project, you can skip this section.

Package Organization

The ros-z repository is organized as a Cargo workspace with multiple packages:

Building the Repository

When contributing to ros-z, you can build different parts of the workspace:

# Build core library
cargo build

# Run tests
cargo test

# Build with bundled messages for examples
cargo build -p ros-z-msgs

# Build all packages (requires ROS 2)
source /opt/ros/jazzy/setup.bash
cargo build --all

Message Package Resolution

The build system automatically locates ROS message definitions:

Search order:

1. System ROS installation (AMENT_PREFIX_PATH, CMAKE_PREFIX_PATH)
2. Common ROS paths (/opt/ros/{rolling,jazzy,iron,humble})
3. Roslibrust git checkout (~/.cargo/git/checkouts/roslibrust-*/assets/)

This fallback mechanism enables builds without ROS 2 installed.

Common Development Commands

# Fast iterative development
cargo check                # Quick compile check
cargo build                # Debug build
cargo build --release      # Optimized build
cargo test                 # Run tests
cargo clippy              # Lint checks

# Clean builds
cargo clean                # Remove all build artifacts
cargo clean -p ros-z-msgs  # Clean specific package

Next Steps

• ROS 2 Distribution Compatibility - Target Jazzy, Humble, or other distributions
• Running Examples - Try out the included examples
• Networking - Set up Zenoh router and session config
• Message Generation - Understand how messages work
• Troubleshooting - Solutions to common build issues

Start with the simplest build and add dependencies incrementally as your project grows.