Building from Source

Building from Source

Build and test the MQTT platform from source.

---

Prerequisites

Required

• Rust 1.88+ - Install via rustup
• cargo-make - Task runner

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install cargo-make
cargo install cargo-make

Optional

• wasm-pack - For WASM builds
• Docker - For container builds

cargo install wasm-pack

---

Clone Repository

git clone https://github.com/LabOverWire/mqtt-lib.git
cd mqtt-lib

---

Build Commands

Quick Build

# Build all crates
cargo build

# Build release version
cargo build --release

# Build specific crate
cargo build -p mqtt5
cargo build -p mqttv5-cli

Using cargo-make

# Build
cargo make build
cargo make build-release

# Check compilation
cargo make check

---

Test Commands

Generate Test Certificates

Required for TLS tests:

./scripts/generate_test_certs.sh

Run Tests

# All tests
cargo test

# Fast unit tests only
cargo test --lib --bins

# Specific test
cargo test --test cli_functionality

# With output
cargo test -- --nocapture

Using cargo-make

# Fast tests (unit + binary tests only)
cargo make test-fast

# All tests including integration
cargo make test

# QUIC integration tests
cargo make test-quic

# CLI functionality tests
cargo make test-cli

---

Linting

# Run clippy (pedantic)
cargo clippy --all-targets --workspace -- -D warnings -W clippy::pedantic

# Using cargo-make
cargo make clippy

# Format code
cargo fmt
cargo make fmt

# Check formatting only
cargo make fmt-check

---

CI Verification

Run all checks that must pass before pushing:

cargo make ci-verify

This runs, in order:

1. fmt-check - cargo fmt --all -- --check
2. clippy - workspace clippy with -D warnings
3. wasm-clippy - clippy for the WASM target
4. build - cargo build
5. test-fast - unit and binary tests
6. test-cli - CLI functionality tests

For a lighter pre-commit check (formatting and linting only):

cargo make pre-commit

---

Platform-Specific Builds

WASM

# Check WASM compilation
cargo make wasm-verify

# Build WASM package
cargo make wasm-build

Embedded (no_std)

# ARM Cortex-M4
cargo make embedded-cortex-m4

# RISC-V
cargo make embedded-riscv

# All embedded targets
cargo make embedded-verify

All Targets

cargo make all-targets

---

Running Examples

Broker Examples

# Simple broker
cargo run -p mqtt5 --example simple_broker

# Broker with TLS
cargo run -p mqtt5 --example broker_with_tls

# Broker with WebSocket
cargo run -p mqtt5 --example broker_with_websocket

# All transports
cargo run -p mqtt5 --example broker_all_transports

# With monitoring
cargo run -p mqtt5 --example broker_with_monitoring

# With OpenTelemetry
cargo run -p mqtt5 --example broker_with_opentelemetry --features opentelemetry

Client Examples

# Simple client
cargo run -p mqtt5 --example simple_client

# Shared subscriptions
cargo run -p mqtt5 --example shared_subscription_demo

---

Debug Logging

Enable tracing for debugging:

# Basic debug
RUST_LOG=debug cargo test

# Specific crate
RUST_LOG=mqtt5=debug cargo test

# Transport layer
RUST_LOG=mqtt5::transport=trace cargo test

# All traces
RUST_LOG=trace cargo test

---

Benchmarking

Performance is measured with the CLI bench subcommand rather than cargo bench:

# Build the CLI
cargo build --release -p mqttv5-cli

# Throughput benchmark
./target/release/mqttv5 bench --duration 15 --subscribers 5

# Latency benchmark (p50/p95/p99)
./target/release/mqttv5 bench --mode latency --duration 10

# Connection rate benchmark
./target/release/mqttv5 bench --mode connections --duration 10 --concurrency 10

---

Docker Build

# Build Docker image
docker build -t mqtt5 .

# Build multi-arch
docker buildx build --platform linux/amd64,linux/arm64 -t mqtt5 .

---

Directory Structure

mqtt-lib/
├── crates/
│   ├── mqtt5/           # Native client + broker
│   ├── mqtt5-protocol/  # Protocol crate (no_std)
│   ├── mqtt5-wasm/      # WASM client + broker
│   └── mqttv5-cli/      # CLI tool
├── scripts/             # Helper scripts
├── test_certs/          # Generated test certificates
├── Makefile.toml        # cargo-make tasks
└── Cargo.toml           # Workspace manifest

---

Dependency Management

Always use cargo commands (never edit Cargo.toml directly):

# Add dependency
cargo add serde -p mqtt5

# Add dev dependency
cargo add tokio-test --dev -p mqtt5

# Remove dependency
cargo remove some-crate -p mqtt5

---

Common Issues

TLS Tests Failing

Error: No such file or directory: "test_certs/ca.pem"

Run:

./scripts/generate_test_certs.sh

Clippy Warnings

error: clippy warnings treated as errors

Fix all warnings or run:

cargo clippy --fix --allow-dirty

WASM Build Errors

Error: wasm32-unknown-unknown target not installed

Run:

rustup target add wasm32-unknown-unknown

Embedded Build Errors

Error: thumbv7em-none-eabihf target not installed

Run:

rustup target add thumbv7em-none-eabihf