Development

Prerequisites

Rust toolchain
git-lfs (required for library binaries)
smolvm itself (for cross-compiling the agent — builds inside a rust:alpine VM)
e2fsprogs (for storage template creation; mkfs.ext4; on macOS: brew install e2fsprogs)
LLVM (macOS only, for building libkrun: brew install llvm)
cargo-make: cargo install cargo-make

Quick Start

We use cargo-make to orchestrate build tasks:

# Install cargo-make (one-time)
cargo install cargo-make

# View all available tasks
cargo make --list-all-steps

# Build and codesign (macOS) - binary ready at ./target/release/smolvm
cargo make dev

# Run smolvm with environment variables set up automatically
cargo make smolvm --version
cargo make smolvm machine run --net --image alpine:latest -- echo hello
cargo make smolvm machine ls

# Or run the binary directly with environment variables:
DYLD_LIBRARY_PATH="./lib" SMOLVM_AGENT_ROOTFS="./target/agent-rootfs" ./target/release/smolvm <command>

How it works:

cargo make dev builds + codesigns (macOS only), binary ready at ./target/release/smolvm
cargo make smolvm <args> runs smolvm with DYLD_LIBRARY_PATH and SMOLVM_AGENT_ROOTFS set up
On macOS, binary is automatically signed with hypervisor entitlements

Building Distribution Packages

# Build distribution package
cargo make dist

# Build using local libkrun changes from ../libkrun
./scripts/build-dist.sh --with-local-libkrun

Running Tests

# Run all tests
cargo make test

# Run specific test suites
cargo make test-cli        # CLI tests only
cargo make test-sandbox    # Sandbox tests only
cargo make test-machine    # MicroVM tests only
cargo make test-pack       # Pack tests only
cargo make test-lib        # Unit tests (no VM required)

Agent Rootfs

The agent rootfs resolution order is:

SMOLVM_AGENT_ROOTFS env var (explicit override)
./target/agent-rootfs (local development)
Platform data directory (~/.local/share/smolvm/ on Linux, ~/Library/Application Support/smolvm/ on macOS)

# Build agent for Linux (size-optimized)
cargo make build-agent

# Build agent rootfs
cargo make agent-rootfs

# Rebuild agent and update rootfs
cargo make agent-rebuild

Code Quality

# Run clippy and fmt checks
cargo make lint

# Auto-fix linting issues
cargo make fix-lints

Other Tasks

# Install locally from dist package
cargo make install

The cargo make dist task wraps scripts/build-dist.sh. Other scripts:

./scripts/build-dist.sh
./scripts/build-agent-rootfs.sh
./scripts/install-local.sh

Rebuilding Libraries

The pre-built library binaries in lib/ cover most development workflows. If you need to rebuild them (after submodule updates, kernel config changes, or enabling new features), see:

Building libkrun — rebuild lib/libkrun.dylib (GPU support, blk, net)
Building libkrunfw — rebuild lib/libkrunfw.5.dylib (kernel blob)

Troubleshooting

Database lock errors ("Database already open"):

pkill -f "smolvm serve"
pkill -f "smolvm-bin machine start"

Hung tests: Check for stuck VM processes:

ps aux | grep smolvm

3.3 KiB Raw Permalink Blame History