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.
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).
The main entry points are
first one asks for a registered debug template and starts the
configuration using the default values for that particular
configuration. The latter creates a debug template which could be
customized before running.
dap-debug-edit-template will prepare a
template declaration inside a temporary buffer. You should execute this
C-M-x for the changes to apply. You should also copy this
code into your Emacs configuration if you wish to make it persistent.
dap-mode also provides a hydra with
dap-hydra. You can automatically trigger the hydra when the program
hits a breakpoint by using the following code.
(add-hook 'dap-stopped-hook (lambda (arg) (call-interactively #'dap-hydra)))
You can also use this tool with dockerized debug servers: configure it
either with a
.dir-locals file or drop an
configuration file (use
lsp-docker for general
reference). Basically you have one function
performs all the heavy lifting (finding the original debug template,
patching it, registering a debug provider e.t.c). This function examines
a configuration file or falls back to the default configuration (which
can be patched using the
.dir-locals approach, take a note that the
default configuration doesn't provide any sane defaults for debugging)
and then operates on the combination of the two. This mechanism is the
same as in
Note: currently you cannot use this mode when using a network connection
to connect to debuggers (this part is yet to be implemented). Still want
to talk to debuggers over network? In order to do so you have to look at
launch-args patching done by
dap-docker--dockerize-start-file-args, you have to somehow assign
dap-server-path before it is passed further into session
If you want to stick to a configuration file, take a look at the example below:
lsp: server: # 'lsp-docker' fields mappings: - source: "/your/host/source/path" # used both by 'lsp-docker' and 'dap-docker' destination: "/your/local/path/inside/a/container" # used both by 'lsp-docker' and 'dap-docker' debug: type: docker # only docker is supported subtype: image # or 'container' name: <docker image or container that has the debugger in> # you can omit this field # in this case the 'lsp-docker' ('server' section) image name is used enabled: true # you can explicitly disable 'dap-docker' by using 'false' provider: <your default language debug provider, double quoted string> template: <your default language debug template, double quoted string> launch_command: <an explicit command if you want to override a default one provided by the debug provider> # e.g. if you have installed a debug server in a different directory, not used with 'container' subtype debuggers
Extending DAP with new Debug servers#
- Daniel Martin - LLDB integration.
- Kien Nguyen - NodeJS debugger, Edge debuggers, automatic extension installation.
- Aya Igarashi - Go debugger integration.
- Nikita Bloshchanevich - launch.json support (+ variable expansion), debugpy support, (with some groundwork by yyoncho) runInTerminal support, various bug fixes.
- Andrei Mochalov - Docker (debugging in containers) integration.