Skip to content

QUICKSTART-USER.adoc

Latest commit

 

History

History
72 lines (54 loc) · 2.37 KB

QUICKSTART-USER.adoc

File metadata and controls

72 lines (54 loc) · 2.37 KB
Raw

snifs — Quick Start for Users

Table of Contents

What is snifs?

snifs — Safer Native Implemented Functions — gives the BEAM crash-isolated native interfaces. A normal NIF runs native code inside the VM’s address space, so any fault (out-of-bounds access, overflow, @panic) kills the entire BEAM VM. A SNIF keeps the NIF’s interface but compiles the guest to WebAssembly (Zig and Rust today) and runs it under wasmtime via wasmex, so a guest fault becomes a catchable {:error, reason} tuple and the calling process survives.

This is a research + reference repository (the SNIF architecture paper, a working BEAM + WASM implementation, integration tests, and formal-verification artifacts) — not a standalone installable application. The fastest way to "use" snifs is to run the demo and watch the BEAM survive a guest crash.

Prerequisites

  • just — task runner (install guide)

  • Elixir 1.15+ on OTP 25+ (the precompiled wasmex nif-2.15 artifact loads on OTP 25 through 28)

  • Zig 0.15+ — only if you want to rebuild the .wasm guests yourself (pre-built binaries ship in priv/)

Run the demo

git clone https://github.com/hyperpolymath/snifs.git
cd snifs/demo
mix deps.get
mix test

The ExUnit suite triggers every guest failure mode — out-of-bounds, @panic, overflow, divide-by-zero — and asserts that each returns {:error, _} while the caller process stays alive. That is crash isolation, demonstrated.

Rebuild the WASM guests (optional)

just build-wasm

Always built with -OReleaseSafe; ReleaseFast turns the same faults into silent wrong answers and is kept only as a negative control.

Self-diagnostic

If something isn’t working:

just doctor          # checks dependencies, permissions, paths

Get Help

  • Architecture & evidence: EXPLAINME

  • What is proven vs tested vs trusted: PROOF-STATUS

  • Guided tour: just tour

  • Report a problem: just help-me (pre-fills diagnostic context)

Next Steps

  • Read the README for scope, benchmarks, and the honesty boundary.

  • Read the paper: docs/whitepapers/academic/snif.pdf (also on Zenodo).