Feature Flags

Fine-grained control over dependencies and functionality through Cargo feature flags. Build exactly what you need, from zero-dependency core to full ROS 2 integration, without carrying unused code.

Feature Categories

ros-z Core Features

protobuf

Enables Protocol Buffers serialization using prost.

cargo build -p ros-z --features protobuf

Use cases:

• Schema evolution support
• Language-agnostic data exchange
• Efficient binary encoding
• Familiar protobuf ecosystem

Dependencies: prost, prost-types

Distribution Compatibility Features

ros-z defaults to ROS 2 Jazzy. Use distribution features to target other ROS 2 versions.

jazzy (default)

Targets ROS 2 Jazzy Jalisco with modern type hash support.

# Automatically enabled (default)
cargo build

# Explicitly enable
cargo build --features jazzy

Features:

• ✅ Type hash support (RIHS01)
• ✅ Shared memory optimization
• ✅ Modern ROS 2 protocol

humble

Targets ROS 2 Humble Hawksbill (LTS) with legacy compatibility.

# Disable defaults and enable humble
cargo build --no-default-features --features humble

Features:

• ❌ No type hash (uses placeholder)
• ❌ No shared memory support
• ✅ LTS support until 2027
• ✅ Compatible with rmw_zenoh_cpp v0.1.8

Important: Humble requires --no-default-features to avoid conflicts with the jazzy default.

rolling and iron

Target newer distributions:

# Rolling
cargo build --features rolling

# Iron
cargo build --features iron

See also: ROS 2 Distribution Compatibility for detailed documentation.

rcl-z

Enables RCL (ROS Client Library) integration for C/C++ interoperability.

cargo build -p ros-z --features rcl-z

Use cases:

• Integrating with existing RCL-based code
• Leveraging C/C++ ROS 2 libraries
• Hybrid Rust/C++ applications

Requirements: ROS 2 installation with RCL libraries

ros-z-msgs Features

Default Features

The default build includes commonly used message types via core_msgs:

cargo build -p ros-z-msgs

Includes:

• std_msgs - Basic types (String, Int32, etc.)
• geometry_msgs - Spatial types (Point, Pose, Transform)
• sensor_msgs - Sensor data (LaserScan, Image, Imu)
• nav_msgs - Navigation (Path, Odometry, OccupancyGrid)
• example_interfaces - Tutorial services (AddTwoInts)
• action_tutorials_interfaces - Tutorial actions (Fibonacci)

Individual Package Features

All packages are bundled in assets and work without ROS 2:

Usage:

# Single package
cargo build -p ros-z-msgs --no-default-features --features std_msgs

# Multiple packages
cargo build -p ros-z-msgs --no-default-features --features "std_msgs,geometry_msgs"

# Default (core_msgs)
cargo build -p ros-z-msgs

Convenience Aliases

core_msgs (default):

The most commonly used packages for ROS 2 development.

cargo build -p ros-z-msgs  # Uses core_msgs by default

Enables: std_msgs, geometry_msgs, sensor_msgs, nav_msgs, example_interfaces, action_tutorials_interfaces

common_interfaces:

cargo build -p ros-z-msgs --features common_interfaces

Enables: std_msgs, geometry_msgs, sensor_msgs

bundled_msgs:

cargo build -p ros-z-msgs --features bundled_msgs

Enables: std_msgs, geometry_msgs, sensor_msgs, nav_msgs

robotics:

Alias for core_msgs.

all_msgs:

cargo build -p ros-z-msgs --features all_msgs

Enables: All available packages including test_msgs

Protobuf Types

Generate protobuf types alongside ROS messages:

cargo build -p ros-z-msgs --features protobuf

Note: Requires ros-z/protobuf feature enabled as well.

ros-z-codegen Features

Protobuf Code Generation

Enable protobuf code generation support:

cargo build -p ros-z-codegen --features protobuf

Use case: Building tools that generate protobuf code from ROS messages

Feature Dependency Graph

graph TD
    A[all_msgs] --> B[bundled_msgs]
    A --> C[example_interfaces]
    A --> D[action_tutorials_interfaces]
    A --> E[test_msgs]

    B --> F[std_msgs]
    B --> G[geometry_msgs]
    B --> H[sensor_msgs]
    B --> I[nav_msgs]

    J[core_msgs] --> F
    J --> G
    J --> H
    J --> I
    J --> C
    J --> D

Common Feature Combinations

Minimal Development

Core library only, no messages:

cargo build -p ros-z

Dependencies: Rust, Cargo Use case: Custom messages only

Standard Development

Core with common message types:

cargo build -p ros-z-msgs  # Uses default common_interfaces
cargo build -p ros-z

Dependencies: Rust, Cargo Use case: Most applications

Full Message Set

All available message packages:

cargo build -p ros-z-msgs --features all_msgs

Dependencies: Rust, Cargo Use case: Access to all bundled message types including test_msgs

RCL Integration

For C/C++ ROS 2 interoperability:

source /opt/ros/jazzy/setup.bash
cargo build -p rcl-z

Dependencies: Rust, Cargo, ROS 2 Use case: Hybrid Rust/C++ applications

Protobuf Development

Core with protobuf serialization:

cargo build -p ros-z-codegen --features protobuf
cargo build -p ros-z-msgs --features protobuf
cargo build -p ros-z --features protobuf

Dependencies: Rust, Cargo, Protobuf compiler Use case: Cross-language data exchange

Feature Matrix

Checking Active Features

View enabled features for a package:

# Show features for ros-z-msgs
cargo tree -p ros-z-msgs -e features

# Show all workspace features
cargo tree -e features

# Build with specific features and verify
cargo build -p ros-z-msgs --features std_msgs,geometry_msgs -v

Feature Selection Strategy

flowchart TD
    A[Start Project] --> B{Need ROS messages?}
    B -->|No| C[Zero features<br/>Custom messages]
    B -->|Yes| D{Which messages?}

    D -->|Common| E[core_msgs<br/>default]
    D -->|Minimal| F[bundled_msgs or<br/>individual packages]
    D -->|All| G[all_msgs]

    C --> H[Minimal dependencies]
    E --> I[Standard dependencies]
    F --> I
    G --> I

Decision guide:

1. Most projects? → Use defaults (core_msgs) - includes common packages
2. Minimal build? → Use --no-default-features with specific packages
3. Custom messages only? → No message features
4. Cross-language data? → Add protobuf feature
5. C++ integration? → Add rcl-z feature (requires ROS 2)

Examples by Feature

Bundled Messages (Default)

cargo run --example z_pubsub          # std_msgs
cargo run --example twist_pub         # geometry_msgs
cargo run --example battery_state_sub # sensor_msgs
cargo run --example z_pingpong        # std_msgs
cargo run --example z_srvcli          # example_interfaces (now bundled)

Custom Messages

cargo run --example z_custom_message  # No features needed

Resources

• Building Guide - Build procedures for each scenario
• ROS 2 Distribution Compatibility - Target Jazzy, Humble, or other distributions
• Message Generation - How messages are generated

Start with default features and add more as your project evolves. Feature flags provide flexibility without forcing early architectural decisions.