Walnut

Documentation

Hot reload

Reload compiled Walnut into a running Simulator or device app without killing the process.

Edit .walnut → recompile → push into the app → swap the live program → re-render.

walnut simulator --watch and walnut device --watch enable hot reload. Use --relaunch when you want a full rebuild and restart on every change.

Host scripts (walnut run / walnut repl) are separate — see jit.md.

Quick start (Simulator)

cd MyApp
walnut simulator --watch

# Full rebuild + relaunch on each change instead:
walnut simulator --relaunch

--watch also turns on the debug server used for reload (debug.md).

What you should see

  1. First run: full typecheck → compile → Xcode build → launch.
  2. Edit a label (or other body) in your Walnut sources.
  3. Within a short while:
→ Change detected — hot reloading…
  ✓ parse …
  ✓ typecheck …
  ✓ emit …
  ✓ clang …
  ✓ reload  preserve model · …ms
  ✓ hot reload · 180ms total

Edits that do not change the program’s exported types preserve the live model. Model / Msg / type export changes reinit safely.

Quick start (device)

walnut device login
walnut device --watch --device f --host <phone-lan-ip>
  1. Cold install builds and launches with the debug server listening.
  2. Later edits recompile, copy the new binary into the app’s Documents folder, and send a reload command over the network.

--host should be the phone’s LAN IP (printed at launch). You can set WALNUT_DEBUG_HOST instead of passing --host every time.

walnut device --relaunch --device f

Manual reload (from the debug console)

debug> reload
debug> reload /path/to/Main.dylib reinit
debug> reload /path/to/Main.dylib preserve

On device, omit the path after the CLI has already pushed the file into Documents.

Flags

FlagMeaning
--watchHot reload on .walnut change
--hotEmit a reloadable binary (implied by --watch)
--relaunchWith watch: full rebuild + terminate + relaunch each change
--no-hotSame as --relaunch when watching
--hostDevice only: debug server IP/hostname

Safety

  • Type / export change: reinit — drop the model, run init again.
  • Body-only change: preserve — keep the model, swap update / view / subscriptions.