doomemacs/modules/tools/debugger

:tools debugger

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • Realgud debuggers
    • lldb and lldb-mi
    • gdb
  • DAP debuggers
    • dap-cpptools
    • dap-gdb-lldb
    • dap-lldb
    • dap-python
• Usage
  • realgud
  • dap-mode
    • How to add a debug configuration
    • dap-mode with +lsp
  • Keybindings
    • General
    • dap-mode
• Configuration
• Troubleshooting
• Frequently asked questions
  • Setting breakpoints in realgud does not work outside a session
• Appendix

Description   unfold

Introduces a code debugger to Emacs, powered by doom-package:realgud or doom-package:dap-mode (LSP).

This document will help you to configure doom-package:dap-mode Native Debug(GDB/LLDB) as there is still not enough documentation for it.

Maintainers

This module has no dedicated maintainers. Become a maintainer?

Module flags

+lsp

Enable support for Debug Adapter Protocol (DAP) debuggers.

Packages

• doom-package:realgud
• doom-package:realgud-trepan-ni if doom-module::lang javascript

• if doom-module:+lsp

  • doom-package:dap-mode
  • doom-package:posframe

Hacks

• Enables gdb-many-windows-mode in gdb-mode by default
• Patches doom-package:realgud to open in a popup window. This causes realgud bindings to focus the command window.
• Closes doom-package:realgud's command buffer after the session ends.

TODO Changelog

This module does not have a changelog yet.

TODO Installation

󱌣 This module's prerequisites documentation is incomplete. Complete it?

Enable this module in your doom! block.

Make sure all of these pre-requirements is in your $PATH:

• nodejs
• lldb and lldb-mi (optional)
• gdb (optional), requires unzip

If you are getting an error like Searching for program no such file or directory "node", then you need nodejs (emacs-lsp/dap-mode#79).

Realgud debuggers

lldb and lldb-mi

This is optional if you want to debug with LLDB. Install lldb and lldb-mi.

gdb

This is optional if you want to debug with GDB. Install gdb.

You will need unzip for dap-gdb-lldb-setup. It downloads a VS-Code extension and it needs to extract compressed downloaded file.

You need this if you are having "wrong-type-argument stringp nil" error when calling dap-gdb-lldb-setup. See emacs-lsp/dap-mode#313

DAP debuggers

dap-cpptools

• Languages: C, C++, Rust

• Documentation

  • adapter
  • dap-mode configuration

Run M-x dap-cpptools-setup to setup the adapter before using it the first time.

dap-gdb-lldb

• Languages: C, C++, Rust

• Documentation

  • adapter
  • dap-mode configuration

Install the vscode extension using M-x dap-gdb-lldb-setup before using it the first time.

dap-lldb

• Languages: C, C++, Rust

• Documentation

  • adapter
  • dap-mode configuration

Needs lldb-vscode. Install LLDB from your package manager. For example:

• Arch Linux: $ pacman -S lldb
• Fedora: $ dnf install lldb

dap-python

• Languages: Python

• Documentation:

  • adapter
  • dap-mode configuration

By default, DAP expects ptvsd as the Python debugger, but debugpy is recommended. See Configuration.

installing ptvsd and debugpy:

$ pip3 install ptvsd --user
$ pip3 install debugpy --user

;; in $DOOMDIR/config.el
(after! dap-mode
  (setq dap-python-debugger 'debugpy))

Usage

Start a debugging session with M-x +debugger/start (bound to SPC o d in evil). You'll be prompted to select a debugger preset if this is the first time you've used it. Otherwise, it will use the last preset automatically. Use the universal/prefix argument to invoke this prompt again: SPC u SPC o d or C-u C-c o d. The last used configuration is stored for each project individually.

M-x +debugger/start-last starts the last used debug configuration, if it exists, and prints a message otherwise instead of offering a selection.

Once the session is started, it can be terminated by M-x +debugger/quit or by using the mode-specific way.

TODO realgud

󱌣 Instructions for realgud haven't been written yet. Write some?

dap-mode

How to add a debug configuration

1. Call dap-gdb-lldb-setup function.
2. Use dap-debug-edit-template to configure debugging settings for your project. Available settings can be inspected here. Call eval-buffer to save your settings. Don't save the file!
3. Call dap-debug, select a configuration and start debugging.

dap-mode with +lsp

Intuitive and powerful debugging.

• Breakpoints
• REPL
• local variable view: Allows you to browse variables in the current stack frame.
• expressions: Add expressions to either watch variables or generic expressions.

Keybindings

General

Keybind	Description
SPC o d	Start a debugger session

dap-mode

When a dap-mode session is running, the following mappings are active:

Keybind	Description
SPC m d	Open a hydra for session control

The hydra is defined as follows:

(map! :map dap-mode-map
      :leader
      :prefix ("d" . "dap")
      ;; basics
      :desc "dap next"          "n" #'dap-next
      :desc "dap step in"       "i" #'dap-step-in
      :desc "dap step out"      "o" #'dap-step-out
      :desc "dap continue"      "c" #'dap-continue
      :desc "dap hydra"         "h" #'dap-hydra
      :desc "dap debug restart" "r" #'dap-debug-restart
      :desc "dap debug"         "s" #'dap-debug

      ;; debug
      :prefix ("dd" . "Debug")
      :desc "dap debug recent"  "r" #'dap-debug-recent
      :desc "dap debug last"    "l" #'dap-debug-last

      ;; eval
      :prefix ("de" . "Eval")
      :desc "eval"                "e" #'dap-eval
      :desc "eval region"         "r" #'dap-eval-region
      :desc "eval thing at point" "s" #'dap-eval-thing-at-point
      :desc "add expression"      "a" #'dap-ui-expressions-add
      :desc "remove expression"   "d" #'dap-ui-expressions-remove

      :prefix ("db" . "Breakpoint")
      :desc "dap breakpoint toggle"      "b" #'dap-breakpoint-toggle
      :desc "dap breakpoint condition"   "c" #'dap-breakpoint-condition
      :desc "dap breakpoint hit count"   "h" #'dap-breakpoint-hit-condition
      :desc "dap breakpoint log message" "l" #'dap-breakpoint-log-message)

TODO Configuration

󱌣 This module has no configuration documentation yet. Write some?

Troubleshooting

• There is a known issue with the +debugger/start command, which is bound to SPC o d right now. It prints "No debugging session to quit" no matter what.

Frequently asked questions

This module has no FAQs yet. Ask one?

Setting breakpoints in realgud does not work outside a session

This currently is not supported by realgud.

TODO Appendix

󱌣 This module has no appendix yet. Write one?