Skip to main content

​
Installation

This guide walks you through building the Cerulion RCL Hooks shared library from source. The build process creates a shared library (.so file) that will be loaded into your ROS 2 processes.

​
Prerequisites

Before you begin, ensure you have:

Rust Toolchain

Rust and Cargo installed (the hooks are written in Rust)

ROS 2 Development

ROS 2 development libraries and headers installed

Build Tools

Standard build tools: make, gcc, pkg-config

Repository Access

Access to the Cerulion development repository
If you don’t have Rust installed, you can get it from rustup.rs. ROS 2 installation depends on your distribution - see the ROS 2 documentation for your specific setup.

​
Building the Shared Library

The build process compiles the Rust code into a shared library that can be loaded with LD_PRELOAD. Let’s walk through it step by step.
1

Navigate to the repository root

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

Build the debug version

Build the cerulion_rcl_hooks package using Cargo:
cargo build -p cerulion_rcl_hooks
This command:
  • Compiles the Rust code
  • Links against ROS 2 libraries
  • Generates the shared library file
The -p flag specifies which package to build. This is useful when working in a workspace with multiple packages.
3

Locate the output file

After a successful build, you’ll find the shared library at:
target/debug/libcerulion_rcl_hooks.so
Verify the file exists and has a reasonable size (typically several megabytes):
ls -lh target/debug/libcerulion_rcl_hooks.so
4

Build the release version (optional)

For production use, build an optimized release version:
cargo build --release -p cerulion_rcl_hooks
The release build:
  • Optimizes the code for performance
  • Reduces binary size
  • Takes longer to compile
The release library will be at:
target/release/libcerulion_rcl_hooks.so
Use the debug version for development and testing, and the release version for production deployments. The release version is faster but takes longer to build.

​
Understanding the Build Output

​
Shared Library File

The .so file is a shared library (similar to .dll on Windows or .dylib on macOS). This file contains:
  • The hook functions that intercept ROS calls before serialization
  • Message hijacking and shared memory publishing code
  • Schema loading logic
  • All necessary dependencies

​
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.

​
Schema Files

The hooks rely on schema files to understand ROS message types. These schemas are located in: 
schemas_ros2/

​
What are Schemas?

Schemas are YAML files that describe:
  • ROS message structure
  • Field types and names
  • How to map ROS message fields to Cerulion’s format (note: Cerulion doesn’t serialize - it publishes directly to shared memory)

​
Schema Location

Schemas are loaded at runtime when the hooks encounter a new message type. The hooks automatically look for schemas in the schemas_ros2/ directory relative to where the library is loaded.
You don’t need to rebuild the hooks when adding new schemas - just place new YAML files in schemas_ros2/ and they’ll be loaded automatically when needed.

​
Verifying the Build

After building, verify everything is correct:
1

Check file exists

file target/debug/libcerulion_rcl_hooks.so
You should see output indicating it’s a shared library, for example:
target/debug/libcerulion_rcl_hooks.so: ELF 64-bit LSB shared object
2

Check dependencies

Verify the library can find its dependencies:
ldd target/debug/libcerulion_rcl_hooks.so
This shows all libraries the hooks depend on. Make sure ROS 2 libraries are listed.
3

Check schema directory

Verify the schema directory exists:
ls schemas_ros2/
You should see YAML files for common ROS message types.

​
Troubleshooting Build Issues

This usually means dependencies aren’t installed. Try:
cargo update
cargo build -p cerulion_rcl_hooks
If that doesn’t work, check that you’re in the correct workspace directory.
Ensure ROS 2 development packages are installed. On Ubuntu/Debian:
sudo apt install ros-<distro>-rcl-dev
Replace <distro> with your ROS 2 distribution (humble, iron, etc.).
If you see linker errors, make sure:
  • ROS 2 environment is sourced: source /opt/ros/<distro>/setup.bash
  • All ROS 2 development packages are installed
  • Your Rust toolchain is up to date: rustup update

​
Next Steps

Now that you’ve built the hooks library, you’re ready to use it with ROS 2 nodes. Continue to the Usage Guide to learn how to run ROS nodes with the hooks enabled.