spacemacs/layers/+tools/dap/README.org

#+TITLE: DAP layer

#+TAGS: layer|tool

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#layer-installation][Layer installation]]
- [[#configuration][Configuration]]
  - [[#dap-configuration-in-supported-layers][DAP configuration in supported layers]]
  - [[#variables][Variables]]
- [[#key-bindings][Key bindings]]
  - [[#declared-prefixes][Declared prefixes]]
  - [[#transient-state][Transient state]]
  - [[#startstop][Start/Stop]]
  - [[#breakpoints][Breakpoints]]
  - [[#navigation][Navigation]]
  - [[#evaluation-and-repl][Evaluation and REPL]]
  - [[#inspection][Inspection]]
- [[#references][References]]

* Description
Experimental integrated visual debugger using [[https://code.visualstudio.com/docs/extensionAPI/api-debugging][Debug Adapter Protocol]].

[[https://code.visualstudio.com/docs/extensionAPI/api-debugging][Debug Adapter Protocol]] is a wire protocol for communication between client and
Debug Server. It similar to the [[https://github.com/Microsoft/language-server-protocol][LSP]] but providers integration with debug
server.

** Features:
Fully featured IDE-like debugger providing:
- Launch/Attach
- Breakpoints
- Exceptions
- Pause & Continue
- Step In/Out/Over
- Callstacks
- Threads
- Multiple simultaneous debug sessions
- Evaluating statements
- Debug/Run configurations
- Debug REPL

* Layer installation
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =dap= to the existing =dotspacemacs-configuration-layers= list in this
file.

* Configuration
** DAP configuration in supported layers
To register =dap-mode= key bindings in a supported layer, the layer must
register itself using the variable =spacemacs--dap-supported-modes=.

For instance the =java= layer:

#+begin_src emacs-lisp
(defun java/pre-init-dap-mode ()
  (add-to-list 'spacemacs--dap-supported-modes 'java-mode))
#+end_src

See the =java= layer for further example on how to setup correctly =dap-mode=.

** Variables

| Variable name              | Default | Description                  |
|----------------------------+---------+------------------------------|
| =dap-enable-mouse-support= | t       | Enable/disable mouse support |

* Key bindings
** Declared prefixes
The following prefixes have been declared:

| prefix      | name              |
|-------------+-------------------|
| ~SPC m d~   | debug             |
| ~SPC m d b~ | breakpoints       |
| ~SPC m d d~ | launching         |
| ~SPC m d e~ | eval              |
| ~SPC m d I~ | inspect           |
| ~SPC m d l~ | debug windows     |
| ~SPC m d S~ | context switching |
| ~SPC m d T~ | toggles           |

** Transient state
Most of the DAP functions can be easily repeated using the built-in DAP
transient state which can be initiate with ~SPC m d .~.

| Key binding | Description           |
|-------------+-----------------------|
| ~SPC m d .~ | debug transient state |

** Start/Stop

| Key binding   | Description                     |
|---------------+---------------------------------|
| ~SPC m d A~   | abandon all process             |
| ~SPC m d a~   | abandon current session         |
| ~SPC m d d d~ | start debugging                 |
| ~SPC m d d e~ | edit debug template             |
| ~SPC m d d l~ | debug last configuration        |
| ~SPC m d d r~ | debug recent configuration      |

** Breakpoints

| Key binding   | Description                     |
|---------------+---------------------------------|
| ~SPC m d b b~ | toggle a breakpoint             |
| ~SPC m d b c~ | change breakpoint condition     |
| ~SPC m d b l~ | change breakpoint log condition |
| ~SPC m d b h~ | change breakpoint hit count     |
| ~SPC m d b a~ | add a breakpoint                |
| ~SPC m d b d~ | delete a breakpoint             |
| ~SPC m d b D~ | clear all breakpoints           |
| ~SPC m d w b~ | list breakpoints                |

** Navigation

| Key binding   | Description                   |
|---------------+-------------------------------|
| ~SPC m d c~   | continue                      |
| ~SPC m d i~   | step in                       |
| ~SPC m d o~   | step out                      |
| ~SPC m d s~   | next step                     |
| ~SPC m d r~   | restart frame                 |
| ~SPC m d S f~ | switch frame                  |
| ~SPC m d S s~ | switch session                |
| ~SPC m d S t~ | switch thread                 |
| ~SPC m d w o~ | goto output buffer if present |
| ~SPC m d w s~ | list sessions                 |

** Evaluation and REPL

| Key binding   | Description         |
|---------------+---------------------|
| ~SPC m d '_~  | Run debug REPL      |
| ~SPC m d e e~ | eval                |
| ~SPC m d e r~ | eval region         |
| ~SPC m d e t~ | eval value at point |

** Inspection

| Key binding   | Description                               |
|---------------+-------------------------------------------|
| ~SPC m d I i~ | inspect                                   |
| ~SPC m d I r~ | inspect region                            |
| ~SPC m d I t~ | inspect value at point                    |
| ~SPC m d v~   | inspect value at point                    |
| ~SPC m d w l~ | list local variables                      |
| ~SPC m d T m~ | toggle mouse support for value inspection |

* References
- [[https://github.com/yyoncho/dap-mode][dap-mode repo]]
- [[https://github.com/emacs-lsp/lsp-mode][lsp-mode repo]]