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.

Success

Feature flags enable pay-per-use dependencies. Start minimal and enable features incrementally as requirements grow.

Feature Categories¶

Category	Purpose	Example Features
Distribution	Target specific ROS 2 versions	`humble`, `jazzy`, `rolling`
Message Packages	Enable ROS 2 message types	`std_msgs`, `geometry_msgs`
Serialization	Additional encoding formats	`protobuf`
Integration	External system bindings	`rcl-z`

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

Info

Protobuf is optional. CDR serialization (default) provides full ROS 2 compatibility without additional dependencies.

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`¶

Target Rolling distribution:

cargo build --features rolling

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

Warning

This feature requires you to source ROS 2 before building. See Building Guide for setup instructions.

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)

Tip

All messages are vendored in assets - no ROS 2 installation required. Feature flags control which packages to include in your build.

Individual Package Features¶

ros-z bundles all packages in assets so they work without ROS 2:

Feature	Package	Use Case
`std_msgs`	Standard messages	Strings, numbers, arrays
`geometry_msgs`	Geometric primitives	Points, poses, transforms
`sensor_msgs`	Sensor data	Cameras, lidars, IMUs
`nav_msgs`	Navigation	Paths, maps, odometry
`example_interfaces`	Tutorial services	AddTwoInts, Fibonacci
`action_tutorials_interfaces`	Tutorial actions	Fibonacci action
`rcl_interfaces`	Parameter service types	Parameter service client interop
`test_msgs`	Test types	Testing and validation

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¶

Package	Feature	Requires ROS 2	Adds Dependencies
ros-z	(none)	No	None
ros-z	jazzy (default)	No	None
ros-z	humble	No	None
ros-z	rolling	No	None
ros-z	protobuf	No	prost, prost-types
ros-z	rcl-z	Yes	RCL libraries
ros-z-msgs	core_msgs (default)	No	None (bundled)
ros-z-msgs	bundled_msgs	No	None (bundled)
ros-z-msgs	all_msgs	No	None (bundled)
ros-z-msgs	protobuf	No	prost, prost-types
ros-z-msgs	jazzy (default)	No	None
ros-z-msgs	humble	No	None
ros-z-codegen	protobuf	No	prost-build

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

Tip

Use cargo tree to debug feature resolution issues. It shows exactly which features are active and why.

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:

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

Note

All message packages are vendored - no ROS 2 installation required for any message feature.