Build System

Building, testing, and packaging the Provisioning platform and extensions with Cargo, Just, and Nickel.

Build Tools

Building Platform Services

Build All Services

# Build all Rust services in release mode
cd provisioning/platform
cargo build --release --workspace

# Or using just task runner
just build-platform

Binary outputs in target/release/:

• provisioning-orchestrator
• provisioning-control-center
• provisioning-vault-service
• provisioning-installer

Build Individual Service

# Orchestrator service
cd provisioning/platform/crates/orchestrator
cargo build --release

# Control Center service
cd provisioning/platform/crates/control-center
cargo build --release

# Development build (faster compilation)
cargo build

Testing

Run All Tests

# Rust unit and integration tests
cargo test --workspace

# Nushell script tests
just test-nushell

# Complete test suite
just test-all

Test Specific Component

# Test orchestrator crate
cargo test -p provisioning-orchestrator

# Test with output visible
cargo test -p provisioning-orchestrator -- --nocapture

# Test specific function
cargo test -p provisioning-orchestrator test_workflow_creation

# Run tests matching pattern
cargo test workflow

Security Tests

# Run 350+ security test cases
cargo test -p security --test '*'

# Specific security component
cargo test -p security authentication
cargo test -p security authorization
cargo test -p security kms

Code Quality

Formatting

# Format all Rust code
cargo fmt --all

# Check formatting without modifying
cargo fmt --all -- --check

# Format Nickel schemas
nickel fmt provisioning/schemas/**/*.ncl

Linting

# Run Clippy linter
cargo clippy --all -- -D warnings

# Auto-fix Clippy warnings
cargo clippy --all --fix

# Clippy with all features enabled
cargo clippy --all --all-features -- -D warnings

Nickel Validation

# Type check Nickel schemas
nickel typecheck provisioning/schemas/main.ncl

# Evaluate schema
nickel eval provisioning/schemas/main.ncl

# Format Nickel files
nickel fmt provisioning/schemas/**/*.ncl

Continuous Integration

The platform uses automated CI workflows for quality assurance.

GitHub Actions Pipeline

Key CI jobs:

1. Rust Build and Test
   - cargo build --release --workspace
   - cargo test --workspace
   - cargo clippy --all -- -D warnings

2. Nushell Validation
   - nu --check core/cli/provisioning
   - Run Nushell test suite

3. Nickel Schema Validation
   - nickel typecheck schemas/main.ncl
   - Validate all schema files

4. Security Tests
   - Run 350+ security test cases
   - Vulnerability scanning

5. Documentation Build
   - mdbook build docs
   - Markdown linting

Packaging and Distribution

Create Release Package

# Build optimized binaries
cargo build --release --workspace

# Strip debug symbols (reduce binary size)
strip target/release/provisioning-orchestrator
strip target/release/provisioning-control-center

# Create distribution archive
just package

Package Structure

provisioning-5.0.0-linux-x86_64.tar.gz
├── bin/
│   ├── provisioning                    # Main CLI
│   ├── provisioning-orchestrator       # Orchestrator service
│   ├── provisioning-control-center     # Control Center
│   ├── provisioning-vault-service      # Vault service
│   └── provisioning-installer          # Platform installer
├── lib/
│   └── nulib/                          # Nushell libraries
├── schemas/                            # Nickel schemas
├── config/
│   └── config.defaults.toml            # Default configuration
├── systemd/
│   └── *.service                       # Systemd unit files
└── README.md

Cross-Platform Builds

Supported Targets

# Linux x86_64 (primary platform)
cargo build --release --target x86_64-unknown-linux-gnu

# Linux ARM64 (Raspberry Pi, cloud ARM instances)
cargo build --release --target aarch64-unknown-linux-gnu

# macOS x86_64
cargo build --release --target x86_64-apple-darwin

# macOS ARM64 (Apple Silicon)
cargo build --release --target aarch64-apple-darwin

Cross-Compilation Setup

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

# Install cross-compilation tool
cargo install cross

# Cross-compile with Docker
cross build --release --target aarch64-unknown-linux-gnu

Just Task Runner

Common build tasks in justfile:

# Build all components
build-all: build-platform build-plugins

# Build platform services
build-platform:
    cd platform && cargo build --release --workspace

# Run all tests
test: test-rust test-nushell test-integration

# Test Rust code
test-rust:
    cargo test --workspace

# Test Nushell scripts
test-nushell:
    nu scripts/test/test_all.nu

# Format all code
fmt:
    cargo fmt --all
    nickel fmt schemas/**/*.ncl

# Lint all code
lint:
    cargo clippy --all -- -D warnings
    nickel typecheck schemas/main.ncl

# Create release package
package:
    ./scripts/package.nu

# Clean build artifacts
clean:
    cargo clean
    rm -rf target/

Usage examples:

just build-all     # Build everything
just test          # Run all tests
just fmt           # Format code
just lint          # Run linters
just package       # Create distribution
just clean         # Remove artifacts

Performance Optimization

Release Builds

# Cargo.toml
[profile.release]
opt-level = 3              # Maximum optimization
lto = "fat"                # Link-time optimization
codegen-units = 1          # Better optimization, slower compile
strip = true               # Strip debug symbols
panic = "abort"            # Smaller binary size

Build Time Optimization

# Cargo.toml
[profile.dev]
opt-level = 1              # Basic optimization
incremental = true         # Faster recompilation

Speed up compilation:

# Use faster linker (Linux)
sudo apt install lld
export RUSTFLAGS="-C link-arg=-fuse-ld=lld"

# Parallel compilation
cargo build -j 8

# Use cargo-watch for auto-rebuild
cargo install cargo-watch
cargo watch -x build

Development Workflow

Recommended Workflow

# 1. Start development
just clean
just build-all

# 2. Make changes to code

# 3. Test changes quickly
cargo check                # Fast syntax check
cargo test <specific-test> # Test specific functionality

# 4. Full validation before commit
just fmt
just lint
just test

# 5. Create package for testing
just package

Hot Reload Development

# Auto-rebuild on file changes
cargo watch -x build

# Auto-test on changes
cargo watch -x test

# Run service with auto-reload
cargo watch -x 'run --bin provisioning-orchestrator'

Debugging Builds

Debug Information

# Build with full debug info
cargo build

# Build with debug info in release mode
cargo build --release --profile release-with-debug

# Run with backtraces
RUST_BACKTRACE=1 cargo run
RUST_BACKTRACE=full cargo run

Build Verbosity

# Verbose build output
cargo build -vv

# Show build commands
cargo build -vvv

# Show timing information
cargo build --timings

Dependency Tree

# View dependency tree
cargo tree

# Duplicate dependencies
cargo tree --duplicates

# Build graph visualization
cargo depgraph | dot -Tpng > deps.png

Best Practices

• Always run just test before committing
• Use cargo fmt and cargo clippy for code quality
• Test on multiple platforms before release
• Strip binaries for production distributions
• Version binaries with semantic versioning
• Cache dependencies in CI/CD
• Use release profile for production builds
• Document build requirements in README
• Automate common tasks with Just
• Keep build times reasonable (<5 min)

Troubleshooting

Common Build Issues

Compilation fails with linker error:

# Install build dependencies
sudo apt install build-essential pkg-config libssl-dev

Out of memory during build:

# Reduce parallel jobs
cargo build -j 2

# Use more swap space
sudo fallocate -l 8G /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Clippy warnings:

# Fix automatically where possible
cargo clippy --all --fix

# Allow specific lints temporarily
#[allow(clippy::too_many_arguments)]

Related Documentation

• Testing - Testing strategies and procedures
• Contributing - Contribution guidelines including build requirements