armless
pages / Testing and releases

Testing and releases

on this page

Filesystem images#

Test and example filesystems are built with scripts under tests/fs: make-9pfs.sh builds a test image, alpine/ a real Alpine, and fs2json.py with copy-to-sha256.py turn a directory into the tree and its content-addressed blobs. Files of 2 MiB and more are split into chunks (--chunk-threshold); --no-chunks makes images for armless 0.2.10 and older.

Testing#

cargo test --release --workspace unit tests (user mode's too); the bare-metal CPU suite (guest/); four CPUs racing on shared counters with LSE atomics and exclusives; TLS and HTTP of the web relay against rustls
tests/difftest/run.sh CLASS N SEED random instructions against qemu-aarch64; CLASS is int, fp, simd, simds, ldst, crypto or lse (DUT=jit: the wasm JIT)
tests/linux/{boot,userspace,smp}.sh Linux on armless-run; userspace and SMP stress output against qemu-aarch64
tests/linux/free-pages.sh free page reporting on the test kernel: a snapshot after the guest freed 200 MiB is that much smaller
ARMLESS_9PFS=DIR cargo test --release --test vm the snowglobe flow natively: 9p root, console, snapshot, restore
node tests/js/flow.mjs DIR [CPUS] the same through armless.js, plus HTTP over fetch and port forwarding
node tests/js/boot.mjs, run-bare.mjs, alpine.mjs kernels, bare-metal binaries and a real Alpine through armless.js
node --test 'tests/js/*.test.mjs' user mode's API in armless.js on build/armless.wasm (build it first with sh build-wasm.sh): argv and env, plain_std, hostname, reap_orphans, user_asleep_ms, and their errors. Self-contained: the programs are machine code made by the test (tests/js/prog.mjs) and the filesystem is in memory
node tests/js/user.mjs SITE user mode through armless.js against a real program (not in CI, by hand): a --kernel none snowglobe site restored from its native snapshot, asked a question, saved and restored again; --exec FSDIR PROGRAM ARGS starts a program from a filesystem
elixir bench/run.exs the benchmark guest under the interpreter, the native JIT and the wasm JIT (node)
node bench/syscalls.mjs, sh bench/machine-syscalls.sh KERNEL [--wasm] what system calls cost in user mode under Node, and under a guest kernel (machine mode), natively and under Node
elixir bench/sites.exs ../snowglobe real workloads: built snowglobe sites running their own commands
cargo bench --bench machine host-side costs with criterion: an instruction interpreted and compiled, a page's compile, a snapshot
cargo bench --bench zstd the zstd decoder's throughput, whole and in pieces

docs/profiling.md explains the benchmarks and profiles. CI (.github/workflows/ci.yml) runs the unit tests (with and without overflow checks), clippy natively and for wasm32, the KVM backend's lints, the wasm builds and armless.js's user-mode tests, and a Linux job that boots a kernel and compares userspace and SMP output with qemu-aarch64, natively, with the native JIT and through armless.js. On pull requests, .github/workflows/bench.yml runs the criterion benchmarks on the base and on the change, and comments with how they compare.

Releases#

A push to main that changes the version in Cargo.toml publishes a GitHub release armless-v<version> (once per version). It carries armless.js, armless.wasm, armless-smp.wasm, and armless-web.tar.gz with those three, the license and docs/armless.md. Native programs use the crate itself, as a git dependency on the tag (publish = false: it is not on crates.io). User mode is the armless-user crate in the same repository, a git dependency on the same tag.

this page's source