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#
-
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 aEclispe JDT Server
you will have to force a server update via C-u M-xlsp-install-server
and select "jdtls". In order to enable lsp java, you will have to requiredap-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 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"))))
Kotlin#
-
Installation To use dap-mode with Kotlin, you need to download the kotlin-debug-adapter. The releases are a bit infrequent, so it is recommended to build it from source yourself. You will also need to have installed
lsp-mode
, asdap-kotlin
shares some configuration with it. After building it, point the variablelsp-kotlin-debug-adapter-path
to the path of the kotlin-debug-adapter executable. You will find this in the pathadapter/build/install/adapter/bin
(from the kotlin-debug-adapter root). You should also make sure thatlsp-kotlin-debug-adapter-enabled
is set to true. -
Usage First of all, each time you you want to debug, make sure you BUILD YOUR PROJECT FIRST! Simply running your regular build with Maven or Gradle should be enough.
You can set up debug templates using Kotlin.
dap-kotlin
provides some sensible defaults, but there are one parameters you MUST give yourself: -:mainClass
: The class name, including package for the main class you want to run. If the class takes argument, you can give them as well. If project root path needs to be different, you can give it using the parameter:projectRoot
. Other parameters include: -:type
:launch
orattach
-:hostName
: If type isattach
, you can specify a hostname to connect to. Defaults tolocalhost
. -:port
: If type isattach
, you can specify a port to connect to. Defaults to5005
. -:noDebug
: Whether or not to use a debug session -:enableJsonLogging
: Enable logging of adapter communication logs. -:jsonLogFile
: File to log to.
Thanks to interop with lsp-kotlin
, you can have it set up code lenses with run/debug-options for main classes.
For this to work, you need kotlin-langauge-server running, be in a file with a main method, and have activated lsp-kotlin-lens-mode
Sadly, there is no test-running functionality like in Java dap-mode
. This can be combated by setting up a debug template with
the Junit5 ConsoleLauncher
. Remember that this class needs to be part of your classpath. Sometimes this is included in bigger frameworks
testing utilities, but can also be included explicitly by adding the junit-platform-console
dependency.
(dap-register-debug-template "Kotlin tests with launcher"
(list :type "kotlin"
:request "launch"
:mainClass "org.junit.platform.console.ConsoleLauncher --scan-class-path"
:enableJsonLogging nil
:noDebug nil))
ConsoleLauncher
. Arguments are documented on the official JUnit website.
Python#
-
Installation
Make sure to install the required modules in the project's virtual environment (if any).
- install debugpy
pip install "debugpy"
-
Or install ptvsd
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-1128961454pip install "ptvsd>=4.2"
-
Then add the following line in your config:
This will add the python related configuration to(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)
dap-debug
.
- install debugpy
-
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"))
-
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 indap-python-debugger
)
Remaining parameters are forwarded to the respective debugger.
- Attach to an existing process
dap-python
supports also the "attach" mode to attach and debug a long running script. A template named "Python :: Attach to running process" is also pre-registered for this purpose.The(dap-register-debug-template "Python :: Attach to running process" (list :type "python" :request "attach" :processId "${command:pickProcess}" :name "Python :: Attach to running process"))
${command:pickProcess}
configuration variable used by default to facilitate the user selecting the debug process by a completion popping up window. The realprocessId
can always be specified using its pid. Note: on Linux this is achieved using the ptrace syscall wrapped inside the GDB tool, which means that for distributions that enable YAMA (e.g. Ubuntu) some additional steps may be necessary:- Install GDB.
- Turn on classic ptrace permission
sudo sh -c 'echo 0 > /proc/sys/kernel/yama/ptrace_scope'
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)
wherenode
is either "node" if nodejs is on the path or path to nodejs andpath-to-main-js
is full path./dist/debugger/main.js
which is part of the downloaded VScode package.
- Calling
-
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.
-
Flutter
LSP Dart also supports Flutter debug with options to debug a device or emulator.
LLDB#
-
Installation
LLDB is a debugger that supports, among others, C, C++, Objective-C and Swift.
-
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.
(require 'dap-lldb)
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#
- 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)
```
- 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#
- 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
- Add the following line to your Emacs setup:
(require 'dap-swi-prolog)
- Run
dap-debug
in a Prolog buffer and start debugging.
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 requiringdap-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
ordap-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#
-
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 callM-x
dap-dlv-go-debug-in-vterm
. If you need to add arguments to your command, useC-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 usesubstitutePath
.M-x
dap-debug-edit-template
then select some template and addsubstitutePath
option to it: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(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")))))
.dir-locals.el
in root directory of your project:If you need to provide build flags, use((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"))))))))))
:buildFlags
key.
-
Trouble shooting
- put (setq dap-print-io t) and check messages buffer
- add
--log --log-output debugger,rpc,dap
todlv
command and checkdlv
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.
-
Installation
-
For easier of setting up vscode extension, you only need call
dap-go-setup
after requiringdap-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
-
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"
-
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#
-
Firefox
-
Installation
-
For easier of setting up vscode extension, you only need call
dap-firefox-setup
after requiringdap-firefox
.- Or manually download and extract VSCode Firefox Debug Extension.
-
Make sure that
dap-firefox-debug-program
is pointing to the proper file. -
Put in your configuration file:
(require 'dap-firefox)
-
-
Usage
dap-debug
ordap-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 requiringdap-chrome
.- Or manually download and extract VSCode Chrome Debug Extension.
-
Make sure that
dap-chrome-debug-program
is pointing to the proper file. -
Put in your configuration file:
(require 'dap-chrome)
-
-
Usage
dap-debug
ordap-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 requiringdap-edge
.- Or manually download and extract VSCode Edge Debug Extension.
-
Make sure that
dap-edge-debug-program
is pointing to the proper file. -
Put in your configuration file:
(require 'dap-edge)
-
-
Usage
dap-debug
ordap-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 requiringdap-node
.- Or manually download and extract VSCode Node Debug Extension.
-
Make sure that
dap-node-debug-program
is pointing to the proper file. -
Put in your configuration file:
(require 'dap-node)
-
-
Usage
dap-debug
ordap-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#
-
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
-
-
-
Usage
Call
dap-debug
and select the "Unity Editor" template
OCaml#
earlybird is an OCaml debugger with support for DAP.
-
Installation
-
Install earlybird through
opam install earlybird
-
Put in your configuration file:
(require 'dap-ocaml)
-
Usage
Call
dap-debug
and edit the "OCaml Debug Template". Make sure to set the program field as the path of your byte-code compiled program. Note that this debugger only works with bytecode compiled OCaml programs.