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
DEPLOYMENT_MODE	standalone,	standalone
	single-process

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
# For echo-breakdown benchmark.
./z build -- all RELEASE=yes LOG_LEVEL=panic TIMESTAMP_MSG=yes

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 requires VERUS_EXECUTABLE_DIR to be set; when unset, make verify is a no-op.

# Install verus and run verification.
./scripts/setup/verus.sh ~/toolchain/verus
./z build -- verify VERUS_EXECUTABLE_DIR=~/toolchain/verus

# Verify a single crate.
./z build -- verify-bitmap VERUS_EXECUTABLE_DIR=~/toolchain/verus

• Set VERUS_EXECUTABLE_DIR to the directory containing the verus binary.
• Use scripts/setup/verus.sh <dir> to download the pinned release.
• 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 across multiple machine and deployment configurations.

Validate across deployment modes before declaring success. Lint runs with -- -D warnings, so warnings like dead_code become hard failures; code compiled only under a non-default DEPLOYMENT_MODE (for example, a helper used only with standalone) may build cleanly in the default config but fail the pre-commit hook and CI under single-process. Do not report a change as done after checking only the default mode — run ./scripts/pipeline.sh, or repeat the relevant lint-check/build across DEPLOYMENT_MODE={standalone,single-process}.

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).