README.org

Table of Contents

• Summary
  • Project status
• Screenshot
• Features
  • Debugger commands
  • Windows
  • Sessions
    • Keybindings
  • Locals
  • Breakpoints
    • Keybindings
• Configuration
  • DAP mode configuration
  • Java
    • Installation
    • Commands
• 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.

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

Windows

Sessions

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

Keybindings

Locals

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

Breakpoints

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

Keybindings

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

Make sure that you have properly installed and configured LSP Java. Download latest version of Debug Java from Maven Central and add it to lsp-java-bundles. If you want to run unit tests you have to download the JUnit5’s JUnit Platform Console Standalone from Maven Central and you must swith Eclipse Che JDT server. On Linux/MacOS you can do the following:. On Linux you can do that by running the following command:

# Download debug plugin
mkdir -p ~/.emacs.d/eclipse.jdt.ls/plugins/
mvn dependency:get -DrepoUrl=https://mvnrepository.com/repos/central -DgroupId=com.microsoft.java -DartifactId=com.microsoft.java.debug.plugin -Dversion=0.10.0
cp -v ~/.m2/repository/com/microsoft/java/com.microsoft.java.debug.plugin/0.10.0/com.microsoft.java.debug.plugin-0.10.0.jar ~/.emacs.d/eclipse.jdt.ls/plugins/com.microsoft.java.debug.plugin-0.10.0.jar
# Download test runner
mkdir -p ~/.emacs.d/eclipse.jdt.ls/runner/
mvn dependency:get -DrepoUrl=https://mvnrepository.com/repos/central -DgroupId=org.junit.platform -DartifactId=junit-platform-console-standalone -Dversion=1.3.0-M1
cp -v ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.3.0-M1/junit-platform-console-standalone-1.3.0-M1.jar ~/.emacs.d/eclipse.jdt.ls/runner/junit-platform-console-standalone.jar
# Download Che JDT LS.
rm -rf ~/.emacs.d/eclipse.jdt.ls/server/
mkdir -p ~/.emacs.d/eclipse.jdt.ls/server/
wget http://download.eclipse.org/che/che-ls-jdt/snapshots/che-jdt-language-server-latest.tar.gz -O /tmp/jdt-latest.tar
tar xf /tmp/jdt-latest.tar -C ~/.emacs.d/eclipse.jdt.ls/server/

Then add the following settings in your emacs config file:

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

(add-to-list 'lsp-java-bundles (expand-file-name
                               (locate-user-emacs-file
                                "eclipse.jdt.ls/plugins/com.microsoft.java.debug.plugin-0.10.0.jar")))

Commands

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 :program 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
 "java"
 (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
• Debug console