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.
C and C++#
Please see the Native Debugging section.
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 Debuging (C, C++, Rust etc)#
There are a number of options for using dap-mode
with languages which compile
to native code. All of these use the GDB or
LLDB debuggers in one way or another.
dap-gdb
#
This package requires GDB version 14 or later. It communicates directly with the debugger using DAP JSON (without the need for an adapter layer), and there is no directly equivalent VSCode extension.
This package registers two types of debugger:
:type "gdb"
:type "gdbserver"
The latter allows debugging of programs which are running (usually remotely)
under the
gdbserver
program.
-
Installation
Please ensure that you have GDB version 14 or later installed on your system, and add the following line to your Emacs setup:
If(require 'dap-gdb)
gdb
is not on yourPATH
, set or customizedap-gdb-debug-program
with the flags requried to start it in DAP mode, e.g.:(setq dap-gdb-debug-program '("/path/to/gdb" "-i" "dap"))
-
Usage
Create a configuration with M-x
dap-debug-edit-template
, using either "GDB Run Configuration" or "GDBServer Connect Configuration" as the base settings. See the GDB documentation for full descriptions of launch configuration options.Note you must set the
:program
property in your debug template, otherwise you will get an error when the debugger attempts to execute your source file.
dap-lldb
#
LLDB is a debugger that supports, among others, C, C++, Objective-C and
Swift. LLDB supports direct communication with the debugger using DAP JSON,
without an adapter layer, similar to newer versions of GDB. Unlike GDB, the DAP
server is provided by a separate binary which ships with the main LLDB command
tool. The binary is called lldb-vscode
on older versions, and is called
lldb-dap
since version 18.
This package registers a single debugger type:
:type lldb-vscode
The official VSCode extension is LLDB
DAP,
although it is not necessary to install this to use dap-lldb
in Emacs.
-
Installation
Ensure that you have the command-line program
lldb-dap
(orlldb-vscode
) installed on your system. If you want to build the tool from scratch, clone and follow the instructions to compile lldb-dap from:https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap
Note: For proper Swift support, you need to compile LLDB from https://github.com/apple/swift-lldb.
Then put the following in your emacs configuration:
(require 'dap-lldb)
This package expects to find the
lldb-vscode
program in the extensions folder used by VSCode. If you have this installed elsewhere, or are using the more modernlldb-dap
version, you will need to set or customizedap-lldb-debug-program
appropriately:(setq dap-lldb-debug-program '("/path/to/lldb-dap"))
-
Usage
Create a configuration with M-x
dap-debug-edit-template
, selecting the template prefixed "LLDB (VS Code)" for the base settings. Detailed descriptions of the launch configuration options are provided in the LLDB DAP README. Remember to set the:program
property to the path to the binary you wish to debug.
dap-cpptools
#
This package utilizes the official Microsoft extension VSCode CPPTools, which ships with a debug adapter which translates DAP JSON into GDB's Machine Interface (MI) protocol, (used by many debugger GUIs, including Emacs' built-in gud debugger). It therefore works with older versions of GDB which do not support the DAP protocol directly. The adapter is written in C# and is called OpenDebugAD7. The installation steps below will install this program as an executable binary on your system, so it can be used by this package.
This package registers a single debugger type:
:type cpptools
which uses the OpenDebugAD7 adapter to run GDB debugging sessions.
-
Installation
Add the following to your Emacs configuration:
(require 'dap-cpptools)
A one-time step is required to download the extension and set it up automatically - M-x
dap-cpptools-setup
- then you are good start debugging. Note that this will download the extension from the address specified indap-cpptools-download-url
, which is by default set to a specific release under https://github.com/microsoft/vscode-cpptools/releases.The location of the OpenDebugAD7 binary is specified by
dap-cpptools-debug-program
, which can be customized if needed. -
Usage
Run M-x
dap-debug-edit-template
and select the "cpptools" prefixed template as a base. Additional configuration options are documented on the extension's official page.
dap-gdb-lldb
#
This package uses the VSCode extension WebFreak Native
Debug. This
extension is written in Typescript and implements a DAP JSON to MI
translation layer, similar to the CPPTools extension. The extension advertizes
support for both GDB and LLDB - LLDB support requires the additional binary
lldb-mi
; to install this follow the instructions in the link above.
This package registers several debugger types:
:type gdb
:type gdbserver
:type lldb-mi
Note that the first two conflict with the types registered by the dap-gdb
package, so you must avoid adding both dap-gdb
and dap-gdb-lldb
to your
Emacs configuration.
The source code for the extension may be found at https://github.com/WebFreak001/code-debug.
-
Installation
Add the following to your Emacs configuration:
(require 'dap-gdb-lldb)
If you do not have the VSCode extension installed already, you can install it with M-x
dap-gdb-lldb-setup
. Or download and extract VSCode extension (make sure thatdap-gdb-lldb-path
is pointing to the extract location).You will also need to have NodeJS installed on your system, to run the adapter.
-
Usage
Run M-x
dap-debug-edit-template
and select one of the following base templates, depending on your needs:- "GDB Run Configuration"
- "GDBServer Connect Configuration"
- "LLDB Run Configuration"
See the project's README for additional documentation on the launch configurations. Note - be sure to set the working directory (
:cwd
property) to an absolute path - the default may insert a tilde (~) shortcut for your home directory (which the adapter does not understand) and this will cause a launch failure with a misleading error message questioning the existence of the target binary.
Rust#
First, please see the Native Debugging section.
The rustup tool (at least for the x86_64 toolchain) provides additional
configuration for both GDB and LLDB to provide pretty-printers for standard Rust
types. The most straightforward way to use this functionality is to configure
the debug adapters to pick up these scripts rather than the debugger
directly. For dap-gdb
, you can configure the GDB debug program as follows
(assuming ~/.cargo/bin
is in your $PATH
):
(setq dap-gdb-debug-program '("rust-gdb" "-i" "dap"))
For the MI debug adapters, you can supply the debugger program as part of the
launch configuration - for dap-cpptools
the relevant property is
:miDebuggerPath
, and for dap-gdb-lldb
it is :gdbpath
.
Another way to enable pretty-printing is to specify the relevant configuration
steps as part of the launch intialization (and this is the only option for
dap-lldb
). Looking at the rust-lldb
script in
~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/bin
, we see that it
sources a python file to define the pretty printers, and then a command file to
register them. The same things can be done as an initialization step when
launching the DAP debugger, for example:
(dap-register-debug-template
"MyProgram"
(list :type "lldb-vscode"
:initCommands '("command script import ~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/etc/lldb_lookup.py"
"command source ~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/etc/lldb_commands")
:request "launch"
...
))
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.
Julia#
DebugAdapter.jl is DAP-compatible server built on top of Debugger.jl.
To setup, first install DebugAdapter.jl
:
$ julia -e 'import Pkg; Pkg.add("DebugAdapter")'
Then add the following to your configuration:
(require 'dap-julia)
To launch a debug session, call dap-debug
with the Julia Run Configuration
template.