Skip to content

Configuration#

DAP mode configuration#

For an auto-configuration enable the dap-auto-configure-mode. You can configure which features from dap-mode do you want with dap-auto-configure-features:

;; Enabling only some features
(setq dap-auto-configure-features '(sessions locals controls tooltip))

Or if you want to enable only specific modes instead:

(dap-mode 1)

;; The modes below are optional

(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)
;; displays floating panel with debug buttons
;; requies emacs 26+
(dap-ui-controls-mode 1)

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

Java#

  1. 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 a server update via C-u M-x lsp-install-server and select "jdtls". In order to enable lsp java, you will have to require dap-java.el.

    (require 'dap-java)
    
  2. 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

    You can also edit one of the existing templates and execute it with dap-debug. dap-mode will take care of filling missing values, such as classpath. JVM arguments can be specified with :vmArgs:

    (dap-register-debug-template "My Runner"
                                 (list :type "java"
                                       :request "launch"
                                       :args ""
                                       :vmArgs "-ea -Dmyapp.instance.name=myapp_1"
                                       :projectName "myapp"
                                       :mainClass "com.domain.AppRunner"
                                       :env '(("DEV" . "1"))))
    

Python#

  1. Installation

    Make sure to install the required modules in the project's virtual environment (if any).

    • install debugpy
      pip install "debugpy"
      
    • Or install ptvsd

      pip install "ptvsd>=4.2"
      
      NOTE: ptvsd is depracated, and as of 8/10/2022, ptvsd caused dap to break when it hits a breakpoint. This comment and issue has context: https://github.com/emacs-lsp/dap-mode/issues/625#issuecomment-1128961454

    • Then add the following line in your config:

      (require 'dap-python)
      ;; if you installed debugpy, you need to set this
      ;; https://github.com/emacs-lsp/dap-mode/issues/306
      (setq dap-python-debugger 'debugpy)
      
      This will add the python related configuration to dap-debug.

  2. Usage

    A template named "Python :: Run Configuration" will appear, which will execute the currently visited module. This will fall short whenever you need to specify arguments, environment variables or execute a setuptools based script. In such case, define a template:

    (dap-register-debug-template "My App"
      (list :type "python"
            :args "-i"
            :cwd nil
            :env '(("DEBUG" . "1"))
            :target-module (expand-file-name "~/src/myapp/.env/bin/myapp")
            :request "launch"
            :name "My App"))
    
  3. Template parameters

These parameters are handled by templates of type python:

  • :target-module: path to some python file to be executed (supersedes :program)
  • :program: path to some python script/program to be executed (defaults to the buffer's file-name)
  • :module: Python module to be executed using -m …. If given, this will be added to the argument list in front of program resp. target-module.
  • :args: either a string or a list of strings (["foo" "bar"]) If a string, it will be split into arguments and shell-unqouted.
  • :debugger: Debugger to use, either "debugpy" or "ptvsd" (defaults to the value defined in dap-python-debugger)

Remaining parameters are forwarded to the respective debugger.

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 ./dist/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)
    

Dart#

LSP Dart has support for debug using dap-mode.

You only need to run dap-dart-setup to setup automatically and then you are good to debug dart.

  1. Flutter

    LSP Dart also supports Flutter debug with options to debug a device or emulator.

LLDB#

  1. 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.

vscode-cpptools#

  1. Installation

You only need to run dap-cpptools-setup to setup automatically and then you are good start debugging.

  - Clone and follow the instructions to compile lldb-vscode from
    <https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode>

  - Put in your emacs configuration.

    ``` elisp
    (require 'dap-cpptools)
    ```
  1. Usage dap-debug-edit-template and select template "cpptools" prefixed configuration.

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 its documentation.

Erlang#

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

(require 'dap-erlang)

For more information about DAP support in Erlang LS please refer to the official documentation.

PHP#

Simplify setup of vscode extension with 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)

Start debugging by selecting "PHP Run Configuration" from the dap-debug menu, issue the debug request in your browser by choosing the running thread (dap-switch-thread) and then dap-step-in.

SWI-Prolog#

  1. With SWI-Prolog installed, run the following command to build and install the debug adapter executable swipl_debug_adapter:
    swipl -g "pack_install(debug_adapter)" -t halt
    
  2. Add the following line to your Emacs setup:
    (require 'dap-swi-prolog)
    
  3. Run dap-debug in a Prolog buffer and start debugging.

Native Debug (GDB/LLDB)#

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

  1. 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.

Rust#

To fully support rust and pretty printing of strings when debugging, remember to add set gdbpath to rust-gdb in your debug template. An example template would be

(dap-register-debug-template "Rust::GDB Run Configuration"
                             (list :type "gdb"
                                   :request "launch"
                                   :name "GDB::Run"
                           :gdbpath "rust-gdb"
                                   :target nil
                                   :cwd nil))

Go#

  1. Installation

    • install gopls

    • Install the delve command by following instructions on delve - installation.

    • install lsp-mode

    • Put in your emacs configuration.

      (require 'dap-dlv-go)
      

    • Usage

      assume you have your code at \~/src/cool/cmd/app/app.go

      • open your main package file e.g \~/src/cool/cmd/app/app.go
      • or open a test file e.g apptest.go
      • add folder to lsp session where your go.mod is or would be
        • M-x lsp-workspace-folders-add \~/src/cool
      • set break point
      • M-x dap-debug
      • if you want to launch a binary or test to debug, use "Go Dlv Launch File Configuration"
      • if you want to debug current test function inside test file use "Go Dlv Test Current Function Configuration"
      • if you want to debug current subtest put your cursor on this subtest and use "Go Dlv Test Current Subtest Configuration"
      • if you want to debug already running application select "Go Dlv Attach Configuration"
      • if you want to debug binary and need to interact with your application, install vterm package and call M-x dap-dlv-go-debug-in-vterm. If you need to add arguments to your command, use C-u M-x dap-dlv-go-debug-in-vterm
      • if you want to debug remote application you need start delve on remote machine first, for example: dlv --headless --accept-multiclient attach 123 -l :1080 (see dlv usage documentation for more command-line options) and select "Go Dlv Remote Debug"
      • if your build environment differs from your development environment (for example, you build project inside docker container or in CI pipeline) or you use -trimpath build flag you can use substitutePath. M-x dap-debug-edit-template then select some template and add substitutePath option to it:
        (dap-register-debug-template
         "Launch Executable trimmed path"
         (list :type "go"
               :request "launch"
               :name "Launch Executable trimmed path"
               :mode "exec"
               :program nil
               :args nil
               :env nil
               :substitutePath (vector (ht ("from" "/home/user/projects/tribonacci") ("to" "github.com/s-kostyaev/tribonacci")))))
        
        and after evaluation you can select this edited template and debug as usual. You also can use dir-locals to save this template for your project. Create .dir-locals.el in root directory of your project:
        ((go-mode  . ((eval . (progn
                                (dap-register-debug-template
                                 "Remote debug in docker container"
                                 (list :type "go"
                                       :request "attach"
                                       :name "Remote debug in docker container"
                                       :mode "remote"
                                       :substitutePath (vector (ht ("from" "/home/user/projects/tribonacci") ("to" "/app"))))))))))
        
        If you need to provide build flags, use :buildFlags key.
    • Trouble shooting

      • put (setq dap-print-io t) and check messages buffer
      • add --log --log-output debugger,rpc,dap to dlv command and check dlv logs
      • e.g linter can return note at debug session response resulting debug session to fail

Go (VS Code debug adapter)#

This debug adapter is deprecated. Use dap-dlv-go instead.

  1. Installation

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

      • Or manually download and extract VSCode Go Extension.. it is actually zip file.
      • check that you now have .emacs.d/.extension/vscode/golang.go/extension/out/src/debugAdapter/goDebug.js
    • install latest stable nodejs

    • install gopls

    • Install the delve command by following instructions on delve - installation.

    • install lsp-mode

    • Put in your emacs configuration.

      (require 'dap-go)
      
    • set up hydra hook as instructed above

    1. Usage

      assume you have your code at \~/src/cool/cmd/app/app.go

      • open your main package file e.g \~/src/cool/cmd/app/app.go
      • or open a test file e.g apptest.go
      • add folder to lsp session where your go.mod is or would be
        • M-x lsp-workspace-folders-add \~/src/cool
      • set break point
      • M-x dap-debug
      • if you are debugging test files use "Go Launch File Configuration"
      • else select e.g "Go Launch Unoptimized Debug Package Configuration"
    2. Trouble shooting

      • put (setq dap-print-io t) and check messages buffer
      • e.g linter can return note at debug session response resulting debug session to fail

Javascript#

  1. Firefox

    1. 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)
        
    2. 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.

  2. Chrome

    1. 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)
        
    2. 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.

  3. Microsoft Edge

    1. 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)
        
    2. 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.

  4. Node

    1. 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)
        
    2. 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.

Powershell#

(require 'dap-pwsh)

Start debugging by selecting "Powershell: Launch Script" from dap-debug menu.

Netcoredbg#

Netcoredbg is debugger that supports C#, F# and probably other languages of Dotnet platform.

(require 'dap-netcore)

If you have Emacs 26 or older you also need customize dap-netcore-download-url:

M-x customize RET dap-netcore-download-url RET

Start debugging by selecting ".Net Core Launch (Console)" or ".Net Core Attach (Console)" from dap-debug menu.

Unity#

  1. Installation

    • Automatic Installation:

      • Add dap-unity to your configuration file

      • Call dap-unity-setup to automatically download and extract the debugger

      • If automatic installation fails, see the manual installation steps below

    • Manual Installation:

      • Download the unity-debug extension from the VisualStudio Marketplace

      • Extract the extension contents (Default path: "{emacsconfigdir}/.extension/vscode/Unity.unity-debug/")

      • On non-Windows os, the debugger "{extensiondir}/extension/bin/UnityDebug.exe" must be flagged as executable Using your favorite terminal: chmod u+x UnityDebug.exe

  2. Usage

    Call dap-debug and select the "Unity Editor" template


Last update: April 25, 2023