AIMMEDIATE PATH
Nim VM
Run a Nim program immediately and inspect its instructions, frames, and values in place. Debuggability is part of the execution model, not an adapter added later.
gudgeon run app.nif VIRTUAL MACHINE / NIM
The observable VM
for Nim.
GUDGEON is a virtual machine and execution platform for the Nim programming language. It runs lowered Nim IR immediately, exposes source-level debugging and instrumentation, and provides a path to native code without changing the program model.
LIVE EXECUTION GRAPH OBSERVABLE
INPUTNIF / Final IRtyped · lowered · mapped
ENGINE 01VMinterpret / debug
ENGINE 02NativeAOT / ABI / FFI
◉ shared source metadata · DAP / trace / profile
SCROLL TO TRACE THE LAYER
01 / THE MODEL
From Nim compiler output
to an observable runtime.
Nimony handles parsing, type checking, lowering, and IR generation. GUDGEON takes the next step: it executes Nim programs, pauses them, measures them, and hands them to another execution engine.
GUDGEON is first and foremost a VM for Nim. Its initial input is NIF, while its execution boundary remains a typed, lowered program IR so the runtime can evolve beyond a single frontend.
01SourceNim program
→
02Nimonysemantic + lower
→
03GUDGEONexecution boundary
→
04Observedebug · trace · profile
02 / ONE PROGRAM, TWO ENGINES
Interpret and compile
from the same map.
NIF / Final IR is not trapped as VM-only bytecode. It is the shared boundary for interpretation and compilation, preserving Nim source locations, types, and frame information across both execution modes.
BPERFORMANCE PATH
Native
Compile the same Nim IR ahead of time. GUDGEON can target C/NIFC, LLVM, or direct code generation without locking the project to one performance backend.
gudgeon build app.nif03 / DEBUG AT THE RIGHT LEVEL
Stop in Nim,
see Nim.
Instead of pretty-printing pointers from generated C, the VM returns its own frames and Nim type metadata to the debugger. A paused program stays at the level of abstraction its author wrote.
run()pause()continue()
stepInto()stepOver()stepOut()
stackTrace()locals()evaluate()
CALL STACK▾ foo (app.nim:18) ▾ module (app.nim:27) main (app.nim:32)
LOCALS / FRAME 0
userUser{ id: 7, active: true }
namesseq[string]["Ada", "Grace"]
retryCountint3
16let user = users[index]17let names = user.names18echo names[0]▌
04 / REFERENCE POINTS
Learning boundary design
from GraalVM and .NET.
The goal is not imitation. It is to adopt the separations that let a language runtime remain useful over time.
ConcernGraalVM.NETDirection for GUDGEON
Shared boundaryTruffle AST / interopIL / CLRTyped, lowered IR as the execution contract
NativeNative Image / Substrate VMNativeAOTVM and AOT share types and metadata
ObservabilityInstrumentation / SourceSectiondiagnostics / debuggerSource maps at the center of the runtime
FFIpolyglot interop / downcallP/Invoke / function pointerExplicit downcall and upcall boundaries
↳
Design principle: Do not choose the native backend first. Start with the VM's Value, Frame, Heap, Type Metadata, and Source Location as a contract shared by every execution engine.
05 / FOREIGN FUNCTION INTERFACE
A path out,
and a path back.
FFI is more than calling a C function. GUDGEON defines downcalls, callbacks into the Nim VM, garbage collection, ownership, exceptions, and type conversion as boundaries the runtime can understand.
GUDGEON VMdowncalltyped value → ABI
FFI boundary
NATIVE WORLDupcallcallback → frame
● stable ABI handle● explicit ownership● source-aware error
06 / TECHNICAL GOALS
One Nim program,
one execution surface.
GUDGEON is more than another way to run Nim. It reshapes the compiler–runtime boundary so execution, debugging, profiling, and native compilation share the same model.
01
Final IR Loader
Load lowered NIF / Final IR and normalize it into a stable internal Execution IR.
02
Debug Runtime API
Treat breakpoints, stepping, stacks, locals, and evaluation as first-class VM APIs.
03
Dual Engine Contract
Share Nim types, source maps, and FFI metadata between the VM executor and native backend.
04
Portable Instrumentation
Expose observation points for debugging, profiling, and tracing across execution engines.
G
GUDGEON — Gudgeon Unified Debuggable Guest Execution Orchestrator for NIF
Back to the top ↑