/dap-mode

Emacs :heart: Debug Adapter Protocol

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

https://melpa.org/packages/dap-mode-badge.svg https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg https://travis-ci.org/yyoncho/dap-mode.svg?branch=master

Table of Contents

Summary

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

Note: dap-mode works only against lsp.el interface.

Project status

The project is in it’s early stage but although it is not extensively tested it is considered stable enough to be used. The API considered unstable until 1.0 release is out. It is tested against Java, Python, Ruby, Elixir and LLDB (C/C++/Objective-C/Swift).

Usage

The main entry points are dap-debug and dap-debug-edit-template. The first one asks for a registered debug template and starts the configuration using the default values for that particular configuration. The later creates a debug template which could be customized before running.

Screenshot

Java

screenshots/MultiSession.png

Swift

screenshots/Swift.png

RUST

screenshots/rust.png

Go

screenshots/go.png

Javascript

screenshots/javascript.png

Features

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

Debugger commands

CommandDescription
dap-breakpoint-toggleToggle breakpoint at line
dap-breakpoint-deleteDelete breakpoint at line
dap-breakpoint-addAdd java breakpoint at line
dap-breakpoint-conditionSet/unset breakpoint condition
dap-breakpoint-hit-conditionSet/unset breakpoint hit condition
dap-breakpoint-log-messageSet/unset breakpoint log message
dap-evalEval string
dap-eval-regionEval region string
dap-eval-thing-at-pointEval symbol at point
dap-step-inDebug step in
dap-nextDebug next
dap-step-outDebug step out
dap-stop-threadStop thread
dap-restart-frameRestart frame
dap-continueDebug continue
dap-disconnectCancel current debug session
dap-switch-stack-frameSwitch active stack frame
dap-switch-threadSwitch active thread
dap-switch-sessionSwitch active session
dap-debug-edit-templateGenerate run command
dap-debugCreate and run new configuration using the available templates
dap-debug-lastDebug previous configuration
dap-debug-recentSelect configuration to run from the previously started command
dap-go-to-output-bufferGo output buffer

Windows

CommandDescription
dap-ui-sessionsShow active/terminated sessions view
dap-ui-localsShow locals view
dap-ui-breakpointsShow breakpoints view
dap-ui-inspectInspect
dap-ui-replDAP UI REPL
dap-ui-inspect-regionInspect region
dap-ui-inspect-thing-at-pointInspect symbol at point

Sessions

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

Keybindings

CommandDescriptionKeybindings
dap-ui-session-selectSelect object at point<return>
dap-ui-session-remove WIPRemove terminated session from the list of running sessions
tree-mode-toggle-expandToggle 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

CommandDescriptionKeybindings
dap-ui-breakpoints-gotoGo to breakpoint under cursor<return>
dap-ui-breakpoints-deleteDelete breakpoint under cursord
dap-ui-breakpoints-delete-selectedDelete selected breakpointsD
bui-list-markMark breakpoint under pointm
bui-list-unmarkUnmark breakpoint under pointu
bui-list-unmark-allUnmark breakpoint under pointU

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. screenshots/dap-ui-repl.png

Configuration

DAP mode configuration

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

(dap-mode 1)
(dap-ui-mode 1)
;; enables mouse hover support
(dap-tooltip-mode 1)
;; use tooltips for mouse hover
;; if it is not enabled `dap-mode' will use the minibuffer.
(tooltip-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

CommandDescription
dap-java-debugDebug java
dap-java-run-test-methodRun test method
dap-java-debug-test-methodDebug test method
dap-java-run-test-classRun test class
dap-java-debug-test-classDebug test class

Python

Installation

  • install latest version of ptvsd.
    pip install "ptvsd>=4.2"
        
    • Then add the following line in your config:
    (require 'dap-python)
        

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

Ruby

  • Download and extract VSCode Ruby Extension. You can do that either by:
    • Calling dap-ruby-setup, the extension will be downloaded and all your path will be automatically set up.
    • Or download the extension manually. Make sure that dap-ruby-debug-program is: ("node" path-to-main-js) where node is either “node” if nodejs is on the path or path to nodejs and path-to-main-js is full path ./out/debugger/main.js which is part of the downloaded VScode package.
  • Follow the instructions on installing rdebug-ide from Ruby Debug Installation
  • Put in your emacs configuration.
    (require 'dap-ruby)
        

LLDB

Installation

LLDB is a debugger that supports, among others, C, C++, Objective-C and Swift.

Note: For proper Swift support, you need to compile LLDB from https://github.com/apple/swift-lldb and put the compiled LLDB library/framework in the “extensions” folder.

Elixir

Make sure that you have properly configured Elixir and that you have Elixir LS binaries on the path and put in your emacs configuration.

(require 'dap-elixir)

Then when you do dap-debug-edit-template and select Elixir which will generate runnable debug configuration. For more details on supported settings by the Elixir Debug Server refer to it’s documentation.

PHP

For easier of setting up vscode extension, you only need to call dap-php-setup after requiring dap-php.

This is using felixbecker/vscode-php-debug (downloadable from the marketplace) as dap-server between emacs and the xdebug-extension on the http-server side. Make sure it is trans/compiled to javascript properly. Only tested under linux with node.

(require 'dap-php)

To begin debugging, select “PHP Run Configuration” from the dap-debug menu, issue the debug request in your browser, select the running thread (dap-switch-thread) and then dap-step-in.

Native Debug (GDB/LLDB)

Using https://github.com/WebFreak001/code-debug

Configuration

For easier of setting up vscode extension, you only need call dap-gdb-lldb-setup after requiring dap-gdb-lldb.

Or download and extract VSCode extension (make sure that dap-gdb-lldb-path is pointing to the extract location).

(require 'dap-gdb-lldb)

Then do dap-debug or dap-debug-edit-template and selet GBD or LLDB configuration.

Go

Installation

  • For easier of setting up vscode extension, you only need call dap-go-setup after requiring dap-go.
  • Install the delve command by following instructions on delve - installation.
  • Put in your emacs configuration.
    (require 'dap-go)
        

Javascript

Firefox

Installation

  • For easier of setting up vscode extension, you only need call dap-firefox-setup after requiring dap-firefox.
  • Make sure that dap-firefox-debug-program is pointing to the proper file.
  • Put in your configuration file:
    (require 'dap-firefox)
        

Usage

dap-debug or dap-debug-edit-template and select the firefox template. For additional documentation on the supported template parameters or about different configuration templates refer to Firefox Debug Adapter.

Chrome

Installation

  • For easier of setting up vscode extension, you only need call dap-chrome-setup after requiring dap-chrome.
  • Make sure that dap-chrome-debug-program is pointing to the proper file.
  • Put in your configuration file:
    (require 'dap-chrome)
        

Usage

dap-debug or dap-debug-edit-template and select the chrome template. For additional documentation on the supported template parameters or about different configuration templates refer to Chrome Debug Adapter.

Microsoft Edge

Installation

  • For easier of setting up vscode extension, you only need call dap-edge-setup after requiring dap-edge.
  • Make sure that dap-edge-debug-program is pointing to the proper file.
  • Put in your configuration file:
    (require 'dap-edge)
        

Usage

dap-debug or dap-debug-edit-template and select the edge template. For additional documentation on the supported template parameters or about different configuration templates refer to Edge Debug Adapter.

Node

Installation

  • For easier of setting up vscode extension, you only need call dap-node-setup after requiring dap-node.
  • Make sure that dap-node-debug-program is pointing to the proper file.
  • Put in your configuration file:
    (require 'dap-node)
        

Usage

dap-debug or dap-debug-edit-template and select the node template. For additional documentation on the supported template parameters or about different configuration templates refer to Nodejs Debugging.

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 template 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

Troubleshooting

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

Acknowledgments

What’s next

  • Watches