Welcome to the SWI-Prolog Debug Adapter Protocol server, an implementation of DAP for SWI-Prolog, written in Prolog.
debug_adapter is available as a SWI-Prolog pack,
to use it simply run the following goal in the SWI-Prolog toplevel:
?- pack_install(debug_adapter).If you're using GNU Emacs with dap-mode, add the following lines to your init.el:
(require 'dap-swi-prolog)Now run M-x dap-debug in a Prolog buffer and have fun.
Most of the DAP specification is implemented and operational. For the status of specific features, see below.
For information about recent changes and additions, see NEWS.md.
Currently only tested with GNU Emacs and dap-mode until we have a VS Code extension.
event messages are notifications sent from the server to the client according to different
runtime hooks that are implemented by the
server.
| Event | Description | Status |
|---|---|---|
| Breakpoint | the status of a breakpoint has changed | ✅ |
| Capabilities | one or more capabilities have changed | |
| Continued | the execution of the debuggee has continued | ✅ |
| Exited | the debuggee has exited and returns its exit code | ✅ |
| Initialized | the debug adapter is ready to accept configuration requests | ✅ |
| Invalidated | some state in the debug adapter has changed | |
| LoadedSource | source has been added, changed, or removed | ✅ |
| Memory | memory range has been updated | |
| Module | information about a module has changed | |
| Output | the target has produced some output | ✅ |
| Process | the debugger has begun debugging a new process | |
| ProgressEnd | signals the end of the progress reporting | |
| ProgressStart | a long running operation is about to start | |
| ProgressUpdate | progress reporting needs to updated | |
| Stopped | the execution of the debuggee has stopped | ✅ |
| Terminated | debugging of the debuggee has terminated | |
| Thread | a thread has started or exited | ✅ |
request messages are sent from the client to the server to retrieve
information about the current runtime.
| Request | Description | Status |
|---|---|---|
| Attach | attach to a debuggee that is already running | ✅ |
| BreakpointLocations | obtain possible locations for source breakpoints in a given range | |
| Completions | obtain possible completions for a given caret position and text | ✅ |
| ConfigurationDone | finish initialization of the debug adapter | ✅ |
| Continue | resume execution of all threads | ✅ |
| DataBreakpointInfo | obtain information on a possible data breakpoint that could be set | |
| Disassemble | disassemble code at the provided location | |
| Disconnect | stop debugging | ✅ |
| Evaluate | evaluate the given expression in the context of the debuggee | ✅ |
| ExceptionInfo | obtain details about thrown exceptions | ✅ |
| Goto | set the location where the debuggee will continue to run | |
| GotoTargets | obtain possible goto targets for the specified source location | |
| Initialize | configure the debug adapter and obtain its capabilities | ✅ |
| Launch | start the debuggee | ✅ |
| LoadedSources | obtain all sources currently loaded by the debuggee | |
| Modules | obtain modules currently loaded by the debuggee | |
| Next | execute the specified thread for one step | ✅ |
| Pause | suspend the debuggee | ✅ |
| ReadMemory | read bytes from memory at the specified location | |
| Restart | restart the debug session | |
| RestartFrame | restart execution of the specified stackframe | ✅ |
| ReverseContinue | resume backward execution of all threads | |
| Scopes | obtain the variable scopes for a given stackframe | ✅ |
| SetBreakpoints | set breakpoints in specified source locations | ✅ |
| SetDataBreakpoints | set data breakpoints | |
| SetExceptionBreakpoints | set the debug adapter's behaviour upon debuggee exceptions | ✅ |
| SetExpression | assign runtime values to a given expression | |
| SetFunctionBreakpoints | set functions breakpoints | ✅ |
| SetInstructionBreakpoints | set intructions breakpoints | |
| SetVariable | assign runtime values to a given variable | |
| Source | obtain source code for a given source reference | ✅ |
| StackTrace | obtain stacktrace from the current execution state of a given thread | ✅ |
| StepBack | execute the specified thread one backward step | |
| StepIn | resume the specified thread to step into a function | ✅ |
| StepInTargets | obtain possible stepIn targets for the specified stackframe | ✅ |
| StepOut | resume the specified thread to step out from a function | ✅ |
| Terminate | terminate the specified thread | |
| TerminateThreads | terminate the specified threads | |
| Threads | obtain the list of current threads | ✅ |
| Variables | obtain all child variables for the specified variable reference | ✅ |
| WriteMemory | write bytes to memory at the specified location |
Reverse requests are request messages sent from the server to the
client to trigger client side operations.
| Reverse Request | Description | Status |
|---|---|---|
| RunInTerminal | run a command in a client controlled terminal | ✅ |
The two big milestones for this project are:
- Reaching feature parity with SWI-Prolog's built-in graphical debugger with a DAP enabled IDE (GNU Emacs +
dap-modein particular), and - Supporting the entire DAP specification
Some of the needed steps towards these goals are:
- Stepping through the source code of a debuggee with precise source positions
- Restarting debuged frames
- Supporting more debug requests -
stepOut,stepBack,next - Providing source code for dynamic predicates through decompilation
- Installing breakpoints at source positions
- Providing information about variable bindings in each frame
- Editing and reloading source code during break
- ...