provisioning/docs/src/development/build-system.md

# 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

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

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

```bash
# Rust unit and integration tests
cargo test --workspace

# Nushell script tests
just test-nushell

# Complete test suite
just test-all
```

### Test Specific Component

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

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

```bash
# Format all Rust code
cargo fmt --all

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

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

### Linting

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

```bash
# 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:

```text
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

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

```text
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

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

```bash
# 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`:

```just
# 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:

```bash
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

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

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

Speed up compilation:

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

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

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

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

```bash
# Verbose build output
cargo build -vv

# Show build commands
cargo build -vvv

# Show timing information
cargo build --timings
```

### Dependency Tree

```bash
# 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:**

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

**Out of memory during build:**

```bash
# Reduce parallel jobs
cargo build -j 2

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

**Clippy warnings:**

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

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

## Related Documentation

- [Testing](testing.md) - Testing strategies and procedures
- [Contributing](contributing.md) - Contribution guidelines including build requirements