Debugger

[idavis]

This is a tracking issue for adding debugger support for Q#.

For a debugger to function across Monaco, VSCode, and potentially in a REPL, the core debugging functionality needs to reside in a new interpreter. As a first cut we can model this on the stateless interpreter. If we wish to look into supporting the REPL or (VS Code debugger REPL) we need to look at what it will take to do side effect free evaluation. This would also potentially power conditional breakpoints.

Components involved

1. Compiler (QSC): Create a new debugger interpreter alongside the current stateful and stateless evaluator. We should be able to deprecate one or both eventually with the debugger running in execution mode and not using any breakpoint functionality.
2. WASM: create a decorator around the debugger which translates the rust data structures into JS compatible values. The API should have the same shape and just be a data marshaling shim.
3. npm package: This is the same package used by the playground that incorporates the Q# compiler. A new interface will be added to provide access to the debugger which handles the loading of the wasm shim and provides a strongly typed interface for consumption by Monaco and VS Code.
4. VS Code extension: Implementation of the VS Code debug adapter APIs mapping the calls to the shim and setting up debugging capabilities.
5. Playground: Similar to VS Code, the debugger needs to be wired up to the Monaco editor extension points in the playground. This will require more changes to the way we hook into Monaco as it doesn't natively support debugging extensions. The extent of the work to be done here is TBD.

%%{init: { "flowchart": { "nodeSpacing": 3 } } }%%
flowchart TD

subgraph JS
  vscode[VS Code extension]
  npm[npm package]
end

subgraph Rust
  wasm["JS bindings (WASM)"]
  debugger[Debugger]
  compiler[Compiler]
end

vscode

vscode-->npm

npm-->wasm
wasm-->debugger
debugger-->compiler

Implementation plan

The initial plan is to support the base scaffolding and core features. Several of the triage and out of scope features require side effect free expression evaluation (log points, hit/conditional breakpoints, etc.). After the core features are functional for VS Code, the base functionality can be exposed for Monaco.

• Scaffolding:
  • [x] #470
• Core Features (compiler and VS Code)
  • [x] Get available breakpoint locations from target #514
  • [x] Set breakpoints #514
  • [x] Validate pre-set breakpoints on launch #514
  • [x] Run program with debugging stopping at breakpoints #514
  • [x] Call stack information #514
  • [x] Locals #540
  • [x] Stepping #540
  • [x] In #540
  • [x] Over #540
  • [x] Out #540
  • [x] Core/STD library source stepping #540
• Debugging Cleanup Task
  • [ ] Stepping fixes
  • [ ] Some stepping has too many steps. Need to isolate test cases.
  • [ ] Span Fixes
  • [ ] Loops
  • [ ] Conjugate blocks
  • [ ] Breakpoint fixes
  • [ ] Allow breakpoints on some expression if/within/etc
• Other features for triage
  • Web view for results and output instead of just to the console
  • Disassembly
  • Custom launch configurations (launch.json)
  • Step/breakpoint granularity
  • Restarting debugging
  • Setting expression/variable values (modifying runtime state)
  • Viewing quantum state
• Out of scope
  • Debug REPL
  • Completion requests
  • side effect free evaluation
  • Step back
  • Restart frame
  • Go to targets
  • Step in targets
  • Module to package mapping and request support
  • Logpoint messages
  • Conditional Breakpoints
  • Hit Conditional Breakpoints
  • Side effect free evaluation of hovers
  • Function Breakpoints

Notes

Tracking breakpoints with HIR node ids is blocked on #453

Resources

• Debugger Extension guide
• Debug Adapter Protocol

[sezna]

Is this issue still up to date? It might be worth breaking out into smaller issues to tackle in the future.

[idavis]

@sezna It is a tracking issue for work. Smaller issues are created for those work items. We can discuss if we want to maintain the tracking issue.

[sezna]

I was referring to the items without issues already created for them, primarily the Debug Cleanup Task section.