:tools debugger

Stepping through code to help you add bugs

1. Description

Introduces a code debugger to Emacs, powered by realgud or DAP (LSP).

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

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

+lsp
Enable support for Debug Adapter Protocol (DAP) debuggers.

1.3. Packages

1.4. Hacks

No hacks documented for this module.

2. Prerequisites

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 it means you need to install nodejs. See issue.

2.1. Realgud debuggers

2.1.1. lldb and lldb-mi

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

2.1.2. 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

2.2. DAP debuggers

2.2.1. Python

DAP expects ptvsd by default as the Python debugger, however debugpy is recommended. See Configuration.

installing ptvsd:

# ⎘
pip3 install ptvsd --user

install debugpy:

# ⎘
pip3 install debugpy --user
# ⎘
;; add to $DOOMDIR/config.el
(after! dap-mode
  (setq dap-python-debugger 'debugpy))

2.2.2. C, C++, Rust, Golang

Needs lldb-vscode.

Install LLDB from you package manager.

Fedora:

# ⎘
dnf install lldb

3. TODO Usage

This module has no usage documentation yet. Write some?

  • M-x +debugger/start
  • M-x +debugger/start-last
  • M-x +debugger/quit

3.1. Realgud

  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.

3.2. 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.

3.3. Keybindings

# ⎘
(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)

4. TODO Configuration

This module’s usage documentation is incomplete. Complete it?

4.1. Keybindings

This module doesn’t have keybinds yet. Here are some examples for the time being:

# ⎘
(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)

5. 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.

6. TODO Appendix

This module has no appendix yet. Write one?