From 1b99805e1bb70a2ec0c4244e4cfb61af24c651ec Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Fri, 28 Oct 2022 23:11:50 +0200 Subject: [PATCH] docs(debugger): add hacks, dap overview, basic usage info Close: #6605 Co-authored-by: rittelle --- modules/tools/debugger/README.org | 108 ++++++++++++++++++++++-------- 1 file changed, 79 insertions(+), 29 deletions(-) diff --git a/modules/tools/debugger/README.org b/modules/tools/debugger/README.org index db526b7be..11f21e568 100644 --- a/modules/tools/debugger/README.org +++ b/modules/tools/debugger/README.org @@ -1,5 +1,5 @@ #+title: :tools debugger -#+subtitle: Step through code to help you add bugs +#+subtitle: Step through code to add more bugs #+created: February 20, 2020 #+since: 2.0.0 @@ -23,10 +23,11 @@ there is still not *enough* documentation for it. - [[doom-package:dap-mode]] - [[doom-package:posframe]] -** TODO Hacks -#+begin_quote - 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] -#+end_quote +** 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 section will be machine generated. Don't edit it by hand. @@ -61,51 +62,83 @@ You need this if you are having ~"wrong-type-argument stringp nil"~ error when calling ~dap-gdb-lldb-setup~. [[github:emacs-lsp/dap-mode/issues/313][See emacs-lsp/dap-mode#313]] ** DAP debuggers -*** Python -DAP expects [[https://github.com/Microsoft/ptvsd][ptvsd]] by default as the Python debugger, but [[https://github.com/microsoft/debugpy][debugpy]] is recommended. -See [[*Configuration][Configuration]]. +*** dap-cpptools +- Languages: C, C++, Rust +- Documentation + - [[https://code.visualstudio.com/docs/cpp/cpp-debug][adapter]] + - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#vscode-cpptools][dap-mode configuration]] -*installing ptvsd:* -#+begin_src sh -pip3 install ptvsd --user -#+end_src +Run =M-x dap-cpptools-setup= to setup the adapter before using it the first +time. -*install debugpy:* +*** dap-gdb-lldb +- Languages: C, C++, Rust +- Documentation + - [[https://github.com/WebFreak001/code-debug][adapter]] + - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#native-debug-gdblldb][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 + - [[https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode][adapter]] + - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#lldb][dap-mode configuration]] + +Needs [[https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode][lldb-vscode]]. Install LLDB from your package manager. For example: + +- *Arch Linux:* ~$ pacman -S lldb~ +- *Fedora:* ~$ dnf install lldb~ + +*** dap-python +- Languages: Python +- Documentation: + - [[https://github.com/microsoft/debugpy/][adapter]] + - [[https://emacs-lsp.github.io/dap-mode/page/configuration/#python][dap-mode configuration]] + +By default, DAP expects [[https://github.com/Microsoft/ptvsd][ptvsd]] as the Python debugger, but [[https://github.com/microsoft/debugpy][debugpy]] is +recommended. See [[*Configuration][Configuration]]. + +*installing ptvsd and debugpy:* #+begin_src sh -pip3 install debugpy --user +$ pip3 install ptvsd --user +$ pip3 install debugpy --user #+end_src #+begin_src emacs-lisp ;; in $DOOMDIR/config.el (after! dap-mode (setq dap-python-debugger 'debugpy)) -#+end_src +#+end_src* TODO Usage -*** C, C++, Rust, Golang -Needs [[https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode][lldb-vscode]]. Install LLDB from your package manager. +* Usage +Start a debugging session with ~M-x +debugger/start~ (bound to [[kbd:][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: [[kbd:][SPC u SPC o d]] or [[kbd:][C-u C-c +o d]]. The last used configuration is stored for each project individually. -*Fedora:* -#+begin_src sh -dnf install lldb -#+end_src +~M-x +debugger/start-last~ starts the last used debug configuration, if it +exists, and prints a message otherwise instead of offering a selection. -* TODO Usage +Once the session is started, it can be terminated by ~M-x +debugger/quit~ or by +using the mode-specific way. + +** TODO realgud #+begin_quote - 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] + 🔨 Instructions for realgud haven't been written yet. [[doom-contrib-module:][Write some?]] #+end_quote -- ~M-x +debugger/start~ -- ~M-x +debugger/start-last~ -- ~M-x +debugger/quit~ - -** Realgud +** 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. [[github:WebFreak001/code-debug/blob/master/package.json#L72][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~ +*** dap-mode with ~+lsp~ Intuitive and powerful debugging. - Breakpoints @@ -116,6 +149,20 @@ Intuitive and powerful debugging. expressions. ** Keybindings + +*** General +| Keybind | Description | +|---------+--------------------------| +| [[kbd:][SPC o d]] | Start a debugger session | + +*** dap-mode +When a dap-mode session is running, the following mappings are active: + +| Keybind | Description | +|---------+----------------------------------| +| [[kbd:][SPC m d]] | Open a hydra for session control | + +The hydra is defined as follows: #+begin_src emacs-lisp (map! :map dap-mode-map :leader @@ -161,6 +208,9 @@ Intuitive and powerful debugging. * Frequently asked questions /This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] +** Setting breakpoints in realgud does not work outside a session +This currently is not supported by realgud. + * TODO Appendix #+begin_quote 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]