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

# Real-World: OmniOS Builder VM

This tutorial walks through the real-world VMFile.kdl used in the vm-manager project itself to build software on OmniOS (an illumos distribution).

## The Goal

Build a Rust binary (`forger`) on OmniOS. This requires:

1. An OmniOS cloud VM with development tools.
2. Uploading the source code.
3. Compiling on the guest.

## The VMFile

    vm "omnios-builder" {
        image-url "https://downloads.omnios.org/media/stable/omnios-r151056.cloud.qcow2"
        vcpus 4
        memory 4096
        disk 20

        cloud-init {
            hostname "omnios-builder"
        }

        ssh {
            user "smithy"
        }

        provision "shell" {
            script "scripts/bootstrap-omnios.sh"
        }

        provision "file" {
            source "scripts/forger-src.tar.gz"
            destination "/tmp/forger-src.tar.gz"
        }

        provision "shell" {
            script "scripts/install-forger.sh"
        }
    }

## Stage 1: Bootstrap (`bootstrap-omnios.sh`)

This script installs system packages and the Rust toolchain:

- Sets up PATH for GNU tools (OmniOS ships BSD-style tools by default).
- Installs `gcc14`, `gnu-make`, `pkg-config`, `openssl`, `curl`, `git`, and other build dependencies via IPS (`pkg install`).
- Installs Rust via `rustup`.
- Verifies all tools are available.

## Stage 2: Upload Source

The `file` provisioner uploads a pre-packed tarball of the forger source code. This tarball is created beforehand with:

    ./scripts/pack-forger.sh

The pack script:

- Copies `crates/forger`, `crates/spec-parser`, and `images/` into a staging directory.
- Generates a minimal workspace `Cargo.toml`.
- Includes `Cargo.lock` for reproducible builds.
- Creates `scripts/forger-src.tar.gz`.

## Stage 3: Build and Install (`install-forger.sh`)

- Extracts the tarball to `$HOME/forger`.
- Runs `cargo build -p forger --release`.
- Copies the binary to `/usr/local/bin/forger`.

## The Full Workflow

    # Pack the source on the host
    ./scripts/pack-forger.sh

    # Bring up the VM, provision, and build
    vmctl up

    # SSH in to test the binary
    vmctl ssh
    forger --help

    # Tear it down when done
    vmctl down --destroy

## Key Takeaways

- Multi-stage provisioning separates concerns: system setup, source upload, build.
- File provisioners transfer artifacts to the guest.
- Script provisioners are easier to iterate on than inline commands for complex logic.
- Streaming output lets you watch the build progress in real-time.