Internals

Build guide

Build the NanoVM WebAssembly images from the nano repository: the slim emulator, the BusyBox image used for terminals, the Boa engine and the wasm apps, then run the test suite.

Prerequisites

Rust nightly with rust-src (rust-toolchain.toml pins nightly and the wasm32-unknown-unknown target). The shared-memory build recompiles core with atomics via build-std.
Node.js for the tests and test/run.mjs.
Optional: wasm-opt (shrinks boa.wasm), the wasm32-wasip1 target (wasm apps), a riscv64 cross-compiler (test ELFs), Docker (make devenv).

Make targets

Target

Output

What it is

make build

wasm/nano.wasm

the slim default: emulator only, no embedded binaries (2,458,155 bytes for v0.2.1)

make build-busybox

wasm/nano.busybox.wasm

emulator + BusyBox (3,229,271 bytes); served on this site as console.wasm

make build-boa

wasm/boa.wasm

the Boa scripting engine, size-optimized with wasm-opt when available (2,813,775 bytes)

make build-full

wasm/nano.wasm

legacy all-in-one: embeds BusyBox, Node.js and the devenv (--features demo); needs the images and build/devenv.tar.gz

make build-minimal

wasm/nano.wasm

slim + the trace feature (per-syscall debug_log), for test/run.mjs --trace

make build-min

wasm/nano.min.wasm

release conformance runtime, no trace

make build-trace

wasm/nano.trace.wasm

release conformance runtime with trace

make build-rg

apps/core/rg.wasm

a minimal rg --files for the wasm runner

make build-photon

apps/core/photon.wasm

the Photon image CLI for the wasm runner (508,268 bytes)

make devenv

build/devenv.tar.gz

npm/TypeScript toolchain archive via Docker

make serve

make build, then python3 -m http.server 8080 in wasm/

make test

make build-minimal, then bash test/run_tests.sh

make test-devenv

make build, then the suite with --devenv

make test-boa / test-boa-vm

Boa unit tests / a Boa script driving the emulator

make test-trace

builds min + trace and checks only the trace build emits syscall events

make test-build

builds the test ELFs (needs a riscv64 cross-compiler)

make clean

cargo clean and removes the built wasm files

Sizes are of the v0.2.1 artifacts in this site's /nano/ directory. The devenv archive (build/devenv.tar.gz) is 113,955,964 bytes, which is why the legacy all-in-one build is large; prefer installing tools from the catalog.

Feature flags

Cargo feature

Embeds

(none, default)

nothing

busybox

runners/riscv/images/busybox (1,149,392-byte ELF, gzipped into the data section)

node

runners/riscv/images/node (legacy; prefer the catalog's node)

devenv

build/devenv.tar.gz (legacy)

demo

busybox + node + devenv

trace

per-syscall debug_log(0x0A | nr) events

Memory configuration

toml

# .cargo/config.toml
[target.wasm32-unknown-unknown]
rustflags = [
  "-C", "target-feature=+atomics,+bulk-memory,+mutable-globals,+sign-ext,+nontrapping-fptoint",
  "-C", "link-args=-z stack-size=1048576 --initial-memory=201326592 --max-memory=2147483648 --shared-memory --import-memory",
]

1 MiB stack, 192 MiB initial and 2 GiB maximum shared memory imported from the host. Release profile: opt-level = 3, lto = "fat", codegen-units = 1, panic = "abort", strip = true.

Tests

bash test/run_tests.sh runs the MemFS, net-bridge and kernel unit tests, the nodert tier (smoke, differential against the Node.js oracle, ordering, engine selector, ESM, worker_threads, wasm tier, WASI services, cross-tier chains), the applet differential tests, ELF execution, BusyBox smoke tests, shipped-host tests and the Boa scripting layer. Run on 2026-10-11 against the slim v0.2.1 build:

bash

$ bash test/run_tests.sh
…
--- Devenv Tool Tests ---
  SKIP: Devenv tool tests (no bundled WASM - run 'make build' then use --devenv)

Phase: Scripting layer (Boa)
  PASS: scripting: Boa scripting: 21 passed, 0 failed

============================================
  Results: 56 passed, 0 failed, 1 skipped (57 total)
============================================

Each result line is one test phase; a phase such as "MemFS Unit Tests" (50 assertions) counts once. Devenv tool tests need a bundled build and --devenv.

Use your build

Serve the files next to your app and point the SDK at them: createNano({ image: { wasm: "/nano/console.wasm" } }). See Quick start and Configuration.

← Previous

Performance

Limitations