Skip to main content

​
Installation

This guide walks you through building the Cerulion Visualization bridge server from source. The bridge is a Rust application that provides a WebSocket server for visualizing Cerulion topics.

​
Prerequisites

Before you begin, ensure you have:

Rust Toolchain

Rust and Cargo installed (the bridge is written in Rust)

Cerulion Repository

Access to the Cerulion development repository with cerulion_viz crate

Build Tools

Standard build tools: make, gcc, pkg-config

Transport Dependencies

iceoryx2 and/or zenoh libraries depending on your transport mode
If you don’t have Rust installed, you can get it from rustup.rs. The bridge requires Rust 1.70 or later.

​
Building the Bridge Server

The bridge server is built as part of the Cerulion workspace. You need to enable the bridge feature flag to include the WebSocket server functionality.
1

Navigate to the repository root

Change to the Cerulion development repository directory:
cd /path/to/cerulion-repo
Replace /path/to/cerulion-repo with the actual path to your Cerulion repository.
2

Build with bridge feature

Build the cerulion binary with the bridge feature flag enabled:
cargo build --features bridge
This command:
  • Compiles the cerulion_viz crate
  • Includes WebSocket server functionality
  • Links against required dependencies (tokio, tokio-tungstenite, etc.)
  • Generates the bridge server binary
The --features bridge flag is required. Without it, the bridge server functionality won’t be included in the build.
3

Locate the binary

After a successful build, you’ll find the bridge server binary at:
target/debug/cerulion
Verify the binary exists and has a reasonable size (typically several megabytes):
ls -lh target/debug/cerulion
4

Build the release version (optional)

For production use, build an optimized release version:
cargo build --release --features bridge
The release build:
  • Optimizes the code for performance
  • Reduces binary size
  • Takes longer to compile
  • Better suited for production deployments
The release binary will be at:
target/release/cerulion
Use the debug version for development and testing, and the release version for production deployments. The release version is faster and uses less memory.

​
Building the Example

The repository includes an example that demonstrates the bridge functionality:
1

Build the example

Build the example with the bridge feature:
cargo build --example lichtblick_bridge --features bridge
2

Locate the example binary

The example binary will be at:
target/debug/examples/lichtblick_bridge

​
Understanding the Build Output

​
Binary File

The cerulion binary includes:
  • The bridge server functionality
  • WebSocket server implementation
  • Transport adapters (iox2 and zenoh)
  • Schema-based message conversion
  • Topic discovery mechanisms

​
Build Artifacts

The target/ directory contains:
  • target/debug/ - Debug build with symbols for debugging
  • target/release/ - Optimized release build
  • Intermediate compilation artifacts (you can ignore these)
Don’t delete the target/ directory while developing - it contains build cache that speeds up subsequent builds. Use cargo clean if you need to start fresh.

​
Dependencies

The bridge feature includes these optional dependencies:
  • tokio - Async runtime for handling WebSocket connections
  • tokio-tungstenite - WebSocket implementation
  • futures-util - Async utilities for stream handling
  • iceoryx2 - Local IPC transport (for iox2 mode)
  • zenoh - Network transport (for zenoh mode)
  • cerulion_core - Core Cerulion functionality
These dependencies are only included when the bridge feature is enabled, keeping the base cerulion binary lightweight.

​
Verifying the Build

After building, verify everything is correct:
1

Check binary exists

file target/debug/cerulion
You should see output indicating it’s an executable, for example:
target/debug/cerulion: ELF 64-bit LSB executable
2

Check bridge subcommand

Verify the bridge subcommand is available:
target/debug/cerulion bridge --help
You should see help text for the bridge command with options for port, transport mode, etc.
If you see the help text, the bridge functionality is correctly built!
3

Check dependencies (optional)

On Linux, verify the binary can find its dependencies:
ldd target/debug/cerulion
This shows all libraries the binary depends on. Make sure required libraries are listed.

​
Troubleshooting Build Issues

This usually means dependencies aren’t installed. Try:
cargo update
cargo build --features bridge
If that doesn’t work, check that you’re in the correct workspace directory and that all required crates are available.
This means the cerulion_viz crate doesn’t have a bridge feature defined, or you’re building the wrong package. Ensure:
  • You’re in the correct repository
  • The cerulion_viz crate exists
  • The bridge feature is defined in Cargo.toml
If you see errors about missing iceoryx2 or zenoh libraries:
  • For iox2: Ensure iceoryx2 is installed and in your library path
  • For zenoh: Ensure zenoh is installed and configured correctly
You can build with only one transport if needed, but you’ll need at least one for the bridge to function.
If you see linker errors, make sure:
  • All required system libraries are installed
  • Your Rust toolchain is up to date: rustup update
  • Transport libraries (iox2/zenoh) are properly installed
  • You have the necessary development packages

​
Next Steps

Now that you’ve built the bridge server, you’re ready to use it. Continue to the Usage Guide to learn how to run the bridge and connect visualization tools.