Development Guide

This guide is for developers who want to contribute to Capsa. If you're looking to use Capsa in your own project, see Getting Started.

Setting Up the Development Environment

Capsa uses Nix with devenv for development. This ensures all contributors have identical toolchains and dependencies.

Installing Nix

We recommend Determinate Nix for the best installation experience:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Alternatively, use the official installer:

curl -L https://nixos.org/nix/install | sh

Entering the Development Shell

cd capsa
nix develop

Or if you have direnv installed, the environment loads automatically when you enter the directory.

This provides:

• Rust toolchain with appropriate targets
• Platform-specific tooling (codesign-run on macOS)
• Test VM builders
• Pre-configured cargo aliases

Cargo Aliases

The devenv sets up cargo aliases for common operations:

Alias	Description
cargo test-linux	Run tests with Linux KVM feature
cargo test-macos	Run tests with macOS subprocess feature
cargo clippy-linux	Run clippy for Linux
cargo clippy-macos	Run clippy for macOS

Feature Flags

Feature	Description
linux-kvm	Enables the Linux KVM backend
macos-subprocess	Enables the macOS Virtualization.framework backend
test-utils	Provides test VM helpers for integration testing

Quick Reference

• Testing - Running tests and building test VMs
• Architecture - Crate structure and platform internals
• Contributing - Code style and PR guidelines