Skip to main content

Building HDDS from Source

This guide covers building HDDS from source for contributors, customization, or platforms without pre-built packages.

Prerequisites​

All Platforms​

  • Git
  • Rust 1.75+ with cargo
  • CMake 3.20+ (for C/C++ bindings)

Linux​

# Ubuntu/Debian
sudo apt install build-essential git cmake pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install gcc gcc-c++ git cmake openssl-devel

# Arch
sudo pacman -S base-devel git cmake openssl

macOS​

xcode-select --install
brew install cmake openssl

Windows​

Clone the Repository​

git clone https://github.com/hdds/hdds.git
cd hdds

Build HDDS (Rust)​

Debug Build​

cargo build

Release Build (Optimized)​

cargo build --release

With All Features​

cargo build --release --all-features

Run Tests​

cargo test

# With verbose output
cargo test -- --nocapture

# Integration tests only
cargo test --test integration

Run Benchmarks​

cargo bench

Build C/C++ Bindings​

cd bindings/c

# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build --config Release

# Install (Linux/macOS)
sudo cmake --install build

# Install (Windows, as Administrator)
cmake --install build

CMake Options​

OptionDefaultDescription
HDDS_BUILD_TESTSONBuild test suite
HDDS_BUILD_EXAMPLESONBuild example applications
HDDS_ENABLE_SECURITYONEnable DDS Security
HDDS_ENABLE_SHMOFFEnable shared memory transport
CMAKE_INSTALL_PREFIX/usr/localInstallation directory

Example with options:

cmake -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DHDDS_ENABLE_SHM=ON \
    -DCMAKE_INSTALL_PREFIX=/opt/hdds

Build Python Bindings​

cd bindings/python

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install build dependencies
pip install maturin

# Build and install
maturin develop --release

# Or build wheel
maturin build --release
pip install target/wheels/hdds-*.whl

Build Documentation​

# Rust docs
cargo doc --no-deps --open

# Full docs with dependencies
cargo doc --open

Project Structure​

hdds/
├── Cargo.toml              # Workspace root
├── crates/
│   ├── hdds/               # Core library
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── participant.rs
│   │   │   ├── topic.rs
│   │   │   ├── writer.rs
│   │   │   ├── reader.rs
│   │   │   └── ...
│   │   └── Cargo.toml
│   ├── hdds-async/         # Async wrapper
│   ├── hdds-gen/           # Code generator
│   ├── hdds-types/         # Type system
│   └── hdds-transport/     # Transport layer
├── bindings/
│   ├── c/                  # C bindings
│   ├── cpp/                # C++ bindings
│   └── python/             # Python bindings
├── examples/               # Example applications
├── tests/                  # Integration tests
└── benches/                # Benchmarks

Development Workflow​

Format Code​

cargo fmt

# Check only (CI)
cargo fmt -- --check

Run Clippy​

cargo clippy --all-targets --all-features -- -D warnings

Run All Checks​

# This is what CI runs
cargo fmt -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc --no-deps

Cross-Compilation​

Linux ARM64 (from x86_64)​

# Add target
rustup target add aarch64-unknown-linux-gnu

# Install cross-compiler
sudo apt install gcc-aarch64-linux-gnu

# Build
cargo build --release --target aarch64-unknown-linux-gnu

Using cross​

# Install cross
cargo install cross

# Build for ARM64
cross build --release --target aarch64-unknown-linux-gnu

# Build for Windows from Linux
cross build --release --target x86_64-pc-windows-gnu

Embedded Builds (no_std)​

For embedded targets:

cd crates/hdds-micro

# Build for Cortex-M4
cargo build --release --target thumbv7em-none-eabihf

# Build for ESP32
cargo build --release --target xtensa-esp32-none-elf

Troubleshooting​

Build Errors​

"Can't find OpenSSL"

# Linux
sudo apt install libssl-dev

# macOS
brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)

# Windows: Download from slproweb.com/products/Win32OpenSSL.html

"Linker error on Windows"

Ensure you have the Visual Studio C++ workload installed and are using the correct MSVC toolchain:

rustup default stable-x86_64-pc-windows-msvc

Performance Issues​

For maximum performance:

# Enable LTO and native CPU optimizations
RUSTFLAGS="-C target-cpu=native -C lto=fat" cargo build --release

Contributing​

See CONTRIBUTING.md for:

  • Code style guidelines
  • Pull request process
  • Issue reporting

Next Steps​