=Dape= is a debug adapter client for Emacs. The debug adapter protocol, much like its more well-known counterpart, the language server protocol, aims to establish a common API for programming tools. However, instead of functionalities such as code completions, it provides a standardized interface for debuggers.
To begin a debugging session, invoke the ~dape~ command. In the minibuffer prompt, enter a debug adapter configuration name from ~dape-configs~.
For complete functionality, make sure to enable ~eldoc-mode~ in your source buffers and ~repeat-mode~ for more pleasant key mappings.
With ~(setq dape-buffer-window-arrangement 'right)~: [[https://raw.githubusercontent.com/svaante/dape/resources/c-right-14.0.0.png]] And with ~(setq dape-buffer-window-arrangement 'gud)~ + =corfu= as ~completion-in-region-function~: [[https://raw.githubusercontent.com/svaante/dape/resources/js-gud-14.0.0.png]] With =minibuffer= adapter configuration hints: [[https://raw.githubusercontent.com/svaante/dape/resources/minibuffer-hints-14.0.0.png]] Screenshots taken with [[https://elpa.gnu.org/packages/standard-themes.html][standard-light]].
(use-package dape :preface ;; By default dape shares the same keybinding prefix as `gud' ;; If you do not want to use any prefix, set it to nil. ;; (setq dape-key-prefix "\C-x\C-a")
:hook
;; Save breakpoints on quit
;; ((kill-emacs . dape-breakpoint-save)
;; Load breakpoints on startup
;; (after-init . dape-breakpoint-load))
:init
;; To use window configuration like gud (gdb-mi)
;; (setq dape-buffer-window-arrangement 'gud)
:config
;; Info buffers to the right
;; (setq dape-buffer-window-arrangement 'right)
;; Global bindings for setting breakpoints with mouse
;; (dape-breakpoint-global-mode)
;; Pulse source line (performance hit)
;; (add-hook 'dape-display-source-hook 'pulse-momentary-highlight-one-line)
;; To not display info and/or buffers on startup
;; (remove-hook 'dape-start-hook 'dape-info)
;; (remove-hook 'dape-start-hook 'dape-repl)
;; To display info and/or repl buffers on stopped
;; (add-hook 'dape-stopped-hook 'dape-info)
;; (add-hook 'dape-stopped-hook 'dape-repl)
;; Kill compile buffer on build success
;; (add-hook 'dape-compile-hook 'kill-buffer)
;; Save buffers on startup, useful for interpreted languages
;; (add-hook 'dape-start-hook (lambda () (save-some-buffers t t)))
;; Projectile users
;; (setq dape-cwd-fn 'projectile-project-root)
)
Dape takes a slightly different approach to configuration.
=Dape= does not support ~launch.json~ files, if per project configuration is needed use ~dir-locals~ and ~dape-command~.
=Dape= enhances ergonomics within the minibuffer by allowing users to modify or add PLIST entries to an existing configuration using options. For example ~dape-config :cwd default-directory :program "/home/user/b.out" compile "gcc -g -o b.out main.c"~.
No magic, no special variables like =${workspaceFolder}=. Instead, functions and variables are resolved before starting a new session.
Tries to envision how debug adapter configurations would be implemented in Emacs if vscode never existed.
Supported debug adapters In theory all debug adapters should be compatible with =Dape=.
* Javascript - vscode-js-
For more information see [[https://github.com/microsoft/vscode-js-debug/blob/main/OPTIONS.md][OPTIONS.md]].
** Go - dlv See [[https://github.com/go-delve/delve/tree/master/Documentation/installation][delve installation]]. For more information see [[https://github.com/go-delve/delve/blob/master/Documentation/usage/dlv_dap.md][documentation]].
** C, C++, Rust, and more - GDB Ensure that your GDB version is 14.1 or newer. For further details, consult the [[https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html][documentation]].
** C, C++ and Rust - codelldb
See [[https://github.com/vadimcn/codelldb/blob/v1.10.0/MANUAL.md][manual]] for more information.
** C and C++ - cpptools Download latesnd unpack =vsix= file with your favorite unzipper.
See [[https://code.visualstudio.com/docs/cpp/launch-json-reference][options]].
** C, C++ and Rust - lldb-dap
*** Example for MacOS using homebrew
** Python - debugpy Install debugpy with pip ~pip install debugpy~
See [[https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings][options]].
** Godot Configure debug adapter port under "Editor" > "Editor Settings" > "Debug Adapter".
** Dart - flutter See for installation https://docs.flutter.dev/get-started/install
** C# - netcoredbg See https://github.com/Samsung/netcoredbg for installation
** Ruby - rdbg Install with ~gem install debug~.
See https://github.com/ruby/debug for more information
** Java - JDTLS with Java Debug Server plugin See https://github.com/eclipse-jdtls/eclipse.jdt.ls for installation of JDTLS. See https://github.com/microsoft/java-debug for installation of the Java Debug Server plugin. The Java config depends on Eglot running JDTLS with the plugin prior to starting Dape. Extend ~eglot-server-programs~ as follows to have JDTLS load the plugin:
(add-to-list 'eglot-server-programs `((java-mode java-ts-mode) . ("jdtls" :initializationOptions (:bundles ["/PATH/TO/java-debug/com.microsoft.java.debug.plugin/target/com.microsoft.java.debug.plugin-VERSION.jar"]))))
** PHP - Xdebug
** Other untested adapters If you find a working configuration for any other debug adapter please submit a PR.
See [[https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/][microsofts list]] for other adapters, your mileage will vary.
Any legally [[https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant][significant]] contributions can only be merged after the author has completed their paperwork. See [[https://www.fsf.org/licensing/contributor-faq][Contributor's Frequently Asked Questions (FAQ)]] for more information.
Some minor gains to performance in the debugger can be achieved in changing Emacs configuration values for process interaction and garbage collection.
** =gc-cons-threshold=
This variable controls the frequency of garbage collection in Emacs. Too high a value will lead to increased system memory pressure and longer stalls, and too low a value will result in extra interruptions and context switches (poor performance).
According to [[https://www.reddit.com/r/emacs/comments/brc05y/comment/eofulix/][GNU Emacs Maintainer Eli Zaretskii]]:
: My suggestion is to repeatedly multiply gc-cons-threshold by 2 until you stop seeing significant improvements in : responsiveness, and in any case not to increase by a factor larger than 100 or somesuch. If even a 100-fold increase : doesn't help, there's some deeper problem with the Lisp code which produces so much garbage, or maybe GC is not the : reason for slowdown.
Abiding the upper end of that advice, you can try to set =gc-cons-threshold= to 100x the original value:
(setq gc-cons-threshold 80000000) ;; original value * 100
** =read-process-output-max=
The default =read-process-output-max= of 4096 bytes may inhibit performance to some degree, also.
*** Linux
On Linux, you should be able to set it up to about =1mb=. To check the max value, check the output of:
cat /proc/sys/fs/pipe-max-size
To set it:
(setq read-process-output-max (* 1024 1024)) ;; 1mb
*** Mac OS
For Mac OS, there isn't an easy way to see the operating system pipe-max-size. It's probably about =64kb=.
(setq read-process-output-max (* 64 1024)) ;; 64k
*** Windows
There doesn't seem to be a limit for Windows. You can try =1mb=.
(setq read-process-output-max (* 1024 1024)) ;; 1mb
Bugs and issues Before reporting any issues ~(setq dape-debug t)~ and take a look at =dape-repl= buffer. Please share your =dape-repl= and =dape-connection events= in the buffer contents with the bug report. The =master= branch is used as an development branch and releases on elpa should be more stable so in the mean time use elpa if the bug is a breaking you workflow.
Acknowledgements Big thanks to João Távora for the input and jsonrpc; the project wouldn't be where it is without João.