## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Build System

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

## Build Tools

Tool | Purpose | Version Required
--- | --- | ---
Cargo | Rust compilation and testing | Latest stable
Just | Task runner for common operations | Latest
Nickel | Schema validation and type checking | 1.15.1+
Nushell | Script execution and testing | 0.109.0+

## 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