emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
doomemacs/modules/tools/debugger/README.org
Henrik Lissner 88bb045388
docs(*): replace all-the-icons with nerd-icons 
Also colorizes the leading icon in notices.
2023-09-16 20:19:11 +02:00

7.9 KiB
Raw Blame History

:tools debugger

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

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

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

dap-gdb-lldb

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

dap-lldb

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

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

dap-python

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?