mahinshaw/dap-mode

Debug Adapter Protocol for Emacs

Table of Contents

• Summary
  • Project status
• Screenshot
• Features
  • Debugger commands
  • Windows
  • Sessions
    • Keybindings
  • Locals
  • Breakpoints
    • Keybindings
  • DAP debug REPL
• Configuration
  • DAP mode configuration
  • Java
    • Installation
    • Commands
  • Python
    • Installation
• Extending DAP with new Debug servers
  • Example
• Links
• Troubleshooting
• What’s next

Summary

Emacs client/library for Debug Adapter Protocol Debug Adapter Protocol is a wire protocol for communication between client and Debug Server. It similar to the LSP but providers integration with debug server.

Project status

The project is in it’s early stage and is still not extensively tested. The API considered unstable until 1.0 release is out. It is tested only against Java and Python.

Screenshot

Features

• Launch/Attach
• Breakpoints
• Exceptions
• Pause & Continue
• Step In/Out/Over
• Callstacks
• Threads
• Multiple simultaneous debug sessions
• Evaluating statements
• Debug/Run configurations

Debugger commands

Command	Description
dap-breakpoint-toggle	Toggle java breakpoint at line
dap-breakpoint-delete	Delete java breakpoint at line
dap-breakpoint-add	Add java breakpoint at line
dap-breakpoint-condition	Set/unset breakpoint condition
dap-breakpoint-hit-condition	Set/unset breakpoint hit condition
dap-breakpoint-log-message	Set/unset breakpoint log message
dap-eval	Eval string
dap-eval-region	Eval region string
dap-eval-thing-at-point	Eval symbol at point
dap-step-in	Debug step in
dap-next	Debug next
dap-step-out	Debug step out
dap-stop-thread	Stop thread
dap-restart-frame	Restart frame
dap-continue	Debug continue
dap-disconnect	Cancel current debug session
dap-switch-stack-frame	Switch active stack frame
dap-switch-thread	Switch active thread
dap-switch-session	Switch active session
dap-debug	Create and run new configuration using the available templates
dap-debug-last	Debug previous configuration
dap-debug-recent	Select configuration to run from the previously started command
dap-go-to-output-buffer	Go output buffer

Windows

Command	Description
dap-ui-sessions	Show active/terminated sessions view
dap-ui-locals	Show locals view
dap-ui-breakpoints	Show breakpoints view
dap-ui-inspect	Inspect
dap-ui-repl	DAP UI REPL
dap-ui-inspect-region	Inspect region
dap-ui-inspect-thing-at-point	Inspect symbol at point

Sessions

The sessions view is showed after invoking dap-ui-sessions . It represents the list of the active sessions.

Keybindings

Command	Description	Keybindings
dap-ui-session-select	Select object at point	<return>
dap-ui-session-remove WIP	Remove terminated session from the list of running sessions
tree-mode-toggle-expand	Toggle node expand state	<tab>

Locals

Locals can be viewed after invoking dap-ui-locals.

Breakpoints

Breakpoints can be viewed after invoking dap-ui-breakpoints.

Keybindings

Command	Description	Keybindings
dap-ui-breakpoints-goto	Go to breakpoint under cursor	<return>
dap-ui-breakpoints-delete	Delete breakpoint under cursor	d
dap-ui-breakpoints-delete-selected	Delete selected breakpoints	D
bui-list-mark	Mark breakpoint under point	m
bui-list-unmark	Unmark breakpoint under point	u
bui-list-unmark-all	Unmark breakpoint under point	U

DAP debug REPL

DAP provides a debug shell to execute command when the program has hit breakpoints. The REPL has the same features as standart emacs shell (e. g. command history, C-p/n navigation through history, etc.) in addition to optional company-mode autocompletion.

Configuration

DAP mode configuration

Enable both dap-mode and dap-ui-mode.

(dap-mode 1)
(dap-ui-mode 1)

After enabling DAP mode on emacs side follow the language specific settings.

Java

Installation

Latest version of LSP Java will automatically discover if dap-mode is present and it will download and install the required server side components. If you have already downloaded a Eclispe JDT Server you will have to force server update via lsp-java-update-server. In order to enable lsp java you will have to require dap-java.el

(require 'dap-java)

Commands

Command	Description
dap-java-debug	Debug java
dap-java-run-test-method	Run test method
dap-java-debug-test-method	Debug test method
dap-java-run-test-class	Run test class
dap-java-debug-test-class	Debug test class

Python

Installation

• Make sure you have installed and configured lsp-python.
• install latest version of ptvsd.

  pip install "ptvsd>=4.1.1a11"
      

  • Then add the following line in your config:

  (require 'dap-python)
      

  This will add the python related configuration to dap-debug.

Extending DAP with new Debug servers

There are two methods that are used for registering remote extensions:

• dap-register-debug-provider - register a method to call for populating startup parameters. It should either populate :debugPort and :host in case of TCP Debug Adapter Server or :dap-server-path when STD out must be used for Debug Adapter Server communication.
• dap-register-debug-template register a debug teplate which will be available when dap-debug is called. The debug template must specify :type key which will be used to determine the provider to be called to populate missing fields.

Example

For full example you may check dap-java.el.

(dap-register-debug-provider
 "programming-language-name"
 (lambda (conf)
   (plist-put conf :debugPort 1234)
   (plist-put conf :host "localhost")
   conf))

(dap-register-debug-template "Example Configuration"
                             (list :type "java"
                                   :request "launch"
                                   :args ""
                                   :name "Run Configuration"))

Links

• Debug Adapter Protocol
• LSP Java
• Debug Adapter Protocol Server Implementations

Troubleshooting

If you notice a bug, open an issue on Github Issues.

What’s next

• Watches