Repository navigation
VirtLang v3.2.0
VirtLang-Go v3.2.0 Release Notes: Advanced Debugger Engine with Call Stack & Stepping
We are incredibly excited to announce the release of VirtLang-Go v3.2.0! This version introduces a powerful, integrated debugging engine, building upon the foundational metadata and error reporting features of v3.0.0 and v3.1.0. VirtLang-Go now provides sophisticated internal mechanisms for step-through debugging, breakpoint management, and call stack inspection.
This release is a major step towards a full-featured debugging experience, providing the core engine capabilities for host environments (like Xel) to build rich debugger UIs upon.
- The signature of the
evaluator.Evaluatefunction has been updated to support debugger integration. Please see the "API Changes (for Go Consumers)" section below for details on how to adapt your code.
Major Features & Enhancements
-
Integrated Debugger Engine (
debuggerpackage):- State Management: The debugger can be in
Running,Paused, orSteppingstates. - Breakpoint Management: Full API for setting, removing, clearing, and checking breakpoints by file and line number (
debugger.BreakpointManager). - Execution Control:
Continue(): Resumes execution from a paused state.Pause(): Halts execution at the next debuggable statement.
- Advanced Stepping Capabilities:
StepInto(): Steps into function calls.StepOver(): Executes the current line, stepping over function calls (executing them without stopping inside unless a breakpoint is hit).StepOut(): Executes until the current function returns, then pauses.
- Call Stack Tracking:
- The debugger now maintains a
CallStack(debugger.CallStack), with eachdebugger.StackFramecontaining function/method name, filename, and line number. PushFrame()andPopFrame()methods allow the engine to manage the call stack during function/method invocations.
- The debugger now maintains a
- Synchronization: Robust internal use of mutexes and condition variables to manage debugger states and control evaluator execution.
- State Management: The debugger can be in
-
AST Interface Enhancement (
astpackage):- The
ast.Stmtandast.Exprinterfaces now include aGetSourceMetadata() SourceMetadatamethod. - All concrete AST node types implement this method, providing a standardized way to access the detailed source location (filename, start/end line & column) embedded in v3.1.0.
- The
Core Interpreter Enhancements
- Evaluator Debugger Integration:
- The main
evaluator.Evaluatefunction now accepts a*debugger.Debuggerinstance. - At the beginning of evaluating each (debuggable) AST node, the evaluator:
- Updates the debugger's
CurrentFileandCurrentLine. - Checks if a breakpoint is hit at the current location using
debugger.ShouldStop(). - If a breakpoint is hit or the debugger is in a stepping state, it pauses execution using
debugger.WaitIfPaused(nodeType). This method now intelligently handles different stepping modes (StepInto,StepOver,StepOut) based on call stack depth.
- Updates the debugger's
- The
*debugger.Debuggerinstance is now threaded through all internal evaluation functions.
- The main
- Call Stack Management in Evaluator:
evalCallExpr(for function and constructor calls) now correctly pushes a newStackFrameonto the debugger'sCallStackupon entry and pops it upon exit.evalProgrampushes a<main>frame for the top-level program execution.
API Changes (for Go Consumers)
evaluator.EvaluateFunction Signature Change:- Old Signature:
func Evaluate(astNode ast.Stmt, env *environment.Environment) (*shared.RuntimeValue, *errors.RuntimeError) - New Signature:
func Evaluate(astNode ast.Stmt, env *environment.Environment, dbgr *debugger.Debugger) (*shared.RuntimeValue, *errors.RuntimeError) - Migration Action (if your Go code directly calls
evaluator.Evaluate): You must update your calls to pass a third argument for the debugger.- If you are not using debugging features in that context, pass
nil:// Old: // result, err := evaluator.Evaluate(myAstNode, myEnv) // New: result, err := evaluator.Evaluate(myAstNode, myEnv, nil)
- If you are integrating with the debugger, pass your
*debugger.Debuggerinstance.
- If you are not using debugging features in that context, pass
- Old Signature:
Testing
- Added comprehensive unit tests for the new
debuggerpackage, covering:- Breakpoint manager functionality.
- Debugger state transitions and control methods (
Pause,Continue,StepInto,StepOver,StepOut). - Call stack push/pop operations.
- Correct behavior of
WaitIfPausedwith different stepping types and call stack depths. - Concurrent access patterns to ensure thread safety.
- Existing evaluator tests have been updated to pass
nilfor the debugger argument, ensuring they continue to validate core language evaluation.
Known Issues and Limitations
- While the engine provides robust stepping and call stack logic, the actual user interface for debugging (e.g., displaying variables, call stack, setting breakpoints via commands) is intended to be implemented by a host environment (like Xel).
- Variable inspection and expression evaluation capabilities during a debug session are to be provided by the host environment, which can leverage the
Debugger.EnvironmentandDebugger.CallStackexposed by the engine.
Upgrade Notes
- This release adds significant new debugging capabilities to the VirtLang-Go engine.
- Action Required for Go Consumers: Update any direct calls to
evaluator.Evaluateto include the new third*debugger.Debuggerargument (passnilif not debugging). - This version is otherwise backwards-compatible for VirtLang-Go language users; their scripts will compile and run as before (unless a debugger is explicitly attached and used by a host environment).
Getting Started
Refer to the README.md and the updated DOCS.md for information on how to use the interpreter, its new debugger engine capabilities, or contribute to the project.
Acknowledgements
Huge congratulations and thanks to @dev-kas for the rapid and impressive development of this advanced debugging engine for VirtLang-Go!