build

name	build
description	Guide for building, formatting, linting, and spell-checking Nanvix with z. Use this when asked to build or validate the repository.

Build Nanvix

Use this skill when the user asks to build, compile, format, lint, or spell-check Nanvix. This covers all build-system operations exposed through the z utility.

Prerequisites

• Development environment set up per doc/setup.md.
• A local cross-compilation toolchain (toolchain/).
• Windows 11: GNU Make on PATH, Windows Hypervisor Platform enabled, Developer Mode enabled, and Rust toolchain installed. See doc/setup.md for details.

Windows Setup Summary

Before building on Windows, ensure:

1. Windows Hypervisor Platform is enabled (Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All, then reboot).
2. Developer Mode is on (Settings > Privacy & Security > For developers).
3. GNU Make is on PATH (winget install ezwinports.make).
4. Rust toolchain is installed via winget install Rustlang.Rustup.
5. Repository was cloned with git clone -c core.symlinks=true.
6. Git hooks are installed: ./z.ps1 setup.

Building

Preferred Build Commands (using z utility)

# Build everything with the local toolchain.
./z build -- all

Building Individual Components

# Kernel only.
./z build -- kernel
# Nanvixd only.
./z build -- all-nanvixd
# UserVM only.
./z build -- all-uservm

Build Parameters

Set these as environment variables or pass them after -- in the z command:

Parameter	Values	Default
MACHINE	microvm	microvm
TARGET	x86	x86
RELEASE	yes, no	no
LOG_LEVEL	trace, debug,	error
	info, warn,
	error, panic
PROFILER	yes, no	no

Example with custom parameters:

./z build -- all RELEASE=yes LOG_LEVEL=error

Manual Build Variants

# Default debug build.
./z build -- all
# Release build.
./z build -- all RELEASE=yes LOG_LEVEL=panic

Building on Windows (using z.ps1)

On Windows 11, the z.ps1 PowerShell script provides the same CLI interface. Guest components are cross-compiled using a local toolchain; host binaries (nanvixd, uservm) are built natively with the microvm backend (WHP on Windows).

# Build everything (guest via make + host binaries natively).
.\z.ps1 build -- all

# Build only the UserVM (native Windows build).
.\z.ps1 build -- uservm

# Build only nanvixd (native Windows build).
.\z.ps1 build -- nanvixd

# Build only nanvix-bench (native Windows build).
.\z.ps1 build -- nanvix-bench

# Build only guest components (kernel + hello-rust-nostd).
.\z.ps1 build -- guest

# Release build.
.\z.ps1 build -- all RELEASE=yes

Any unrecognized target is forwarded to make, just like on Linux:

.\z.ps1 build -- kernel
.\z.ps1 build -- format-check
.\z.ps1 build -- lint-check

Code Quality

Formatting

# Check formatting issues.
./z build -- format-check
# Auto-fix formatting issues.
./z build -- format

Linting

# Check linting issues.
./z build -- lint-check
# Auto-fix linting issues.
./z build -- lint

Spell Checking

# Check spelling errors.
./z build -- spellcheck
# Fix spelling errors.
./z build -- spellcheck-fix

When spell checking flags a legitimate domain term or acronym (for example, vas for Virtual Address Space, or slab), add it to .codespellrc rather than rewording the code or documentation.

Formal Verification

Nanvix uses Verus for formal verification of selected kernel crates. The expected Verus version is pinned in build/verus-version. Verification uses ~/verus by default, matching the setup command. Set VERUS_EXECUTABLE_DIR only for a custom installation.

# Install Verus and run verification.
./z setup --verus
./z build -- verify

# Verify a single crate.
./z build -- verify-bitmap

• Set VERUS_EXECUTABLE_DIR to the directory containing the verus binary.
• Use python3 scripts/setup/verus.py <dir> to download the pinned release on Linux, or python scripts/setup/verus.py <dir> on Windows.
• The vstd crate version in Cargo.toml is exact-pinned (=) to match the Verus binary.

Cleaning

./z clean        # Clean build artifacts.
./z distclean    # Remove all generated files.

Cleaning on Windows

.\z.ps1 clean        # Quick clean (UserVM artifacts + cache).
.\z.ps1 distclean    # Full clean (cargo clean + all artifacts).

CI/CD Pipeline

# Run the full CI pipeline locally.
./scripts/pipeline.sh

The pipeline covers spell checking, formatting, linting, building, and testing for microvm in debug and release configurations. Run ./scripts/pipeline.sh before declaring broad changes done.

IDE Setup (Optional)

Visual Studio Code

Use the host-specific settings template. The Linux template invokes ./z, while the Windows template routes Rust Analyzer through ./z.bat build -- check, which runs native cargo check on host crates (uservm, nanvixd, nanvix-test, mkramfs).

Linux:

mkdir -p .vscode && cd .vscode
ln -s ../scripts/setup/vscode/settings-linux.json settings.json

Windows (PowerShell):

New-Item -ItemType Directory -Path .vscode -Force
Copy-Item scripts\setup\vscode\settings-windows.json .vscode\settings.json

Note: The check target in z.ps1 only checks host crates natively. Guest and kernel crates require the cross-compilation toolchain. Run .\z.ps1 build -- check-kernel check-guest-binaries for a full cross-target check.

Troubleshooting Build Issues

• If builds fail with toolchain errors, verify toolchain/ symlink points to a valid toolchain.
• Use ./z help for usage information.
• Windows: Use .\z.ps1 help for Windows-specific usage information.
• Windows: If the UserVM build fails, verify that the Windows Hypervisor Platform feature is enabled (Get-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform).