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"))))
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.
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