0

dap-mode

Emacs :heart: Debug Adapter Protocol

官方網站
Github 資源庫
主要指標

Github星跟蹤圖

[[https://melpa.org/#/dap-mode][file:https://melpa.org/packages/dap-mode-badge.svg]]
[[http://spacemacs.org][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
[[https://travis-ci.org/yyoncho/dap-mode][https://travis-ci.org/yyoncho/dap-mode.svg?branch=master]]

  • Table of Contents :TOC_4_gh:noexport:
  • [[#summary][Summary]]
    • [[#project-status][Project status]]
  • [[#usage][Usage]]
  • [[#screenshot][Screenshot]]
    • [[#java][Java]]
    • [[#swift][Swift]]
    • [[#rust][RUST]]
    • [[#go][Go]]
    • [[#javascript][Javascript]]
  • [[#features][Features]]
    • [[#debugger-commands][Debugger commands]]
    • [[#windows][Windows]]
    • [[#sessions][Sessions]]
    • [[#locals][Locals]]
    • [[#expressions][Expressions]]
    • [[#breakpoints][Breakpoints]]
      • [[#keybindings][Keybindings]]
    • [[#loaded-sources][Loaded sources]]
    • [[#dap-debug-repl][DAP debug REPL]]
  • [[#configuration][Configuration]]
    • [[#dap-mode-configuration][DAP mode configuration]]
    • [[#java-1][Java]]
      • [[#installation][Installation]]
      • [[#commands][Commands]]
    • [[#python][Python]]
      • [[#installation-1][Installation]]
      • [[#usage-1][Usage]]
    • [[#ruby][Ruby]]
    • [[#lldb][LLDB]]
      • [[#installation-2][Installation]]
    • [[#elixir][Elixir]]
    • [[#php][PHP]]
    • [[#native-debug-gdblldb][Native Debug (GDB/LLDB)]]
      • [[#configuration-1][Configuration]]
    • [[#go-1][Go]]
      • [[#installation-3][Installation]]
    • [[#javascript-1][Javascript]]
      • [[#firefox][Firefox]]
        • [[#installation-4][Installation]]
        • [[#usage-2][Usage]]
      • [[#chrome][Chrome]]
        • [[#installation-5][Installation]]
        • [[#usage-3][Usage]]
      • [[#microsoft-edge][Microsoft Edge]]
        • [[#installation-6][Installation]]
        • [[#usage-4][Usage]]
      • [[#node][Node]]
        • [[#installation-7][Installation]]
        • [[#usage-5][Usage]]
    • [[#powershell][Powershell]]
  • [[#extending-dap-with-new-debug-servers][Extending DAP with new Debug servers]]
    • [[#example][Example]]
  • [[#links][Links]]
  • [[#acknowledgments][Acknowledgments]]

  • Summary
    Emacs client/library for [[https://code.visualstudio.com/docs/extensionAPI/api-debugging][Debug Adapter Protocol]] is a wire protocol for
    communication between client and Debug Server. It's similar to the [[https://github.com/Microsoft/language-server-protocol][LSP]] but
    provides integration with debug server.
    ** Project status
    The API considered unstable until 1.0 release is out. It is tested against
    Java, Python, Ruby, Elixir and LLDB (C/C++/Objective-C/Swift).

  • Usage
    The main entry points are ~dap-debug~ and ~dap-debug-edit-template~. The first
    one asks for a registered debug template and starts the configuration using
    the default values for that particular configuration. The latter creates a
    debug template which could be customized before running.
    ~dap-debug-edit-template~ will prepare a template deceleration inside a
    temporary buffer. You should execute this code using ~C-M-x~ for the changes to
    apply. You should also copy this code into your Emacs configuration if you wish to
    make it persistent.

    dap-mode also provides a [[https://github.com/abo-abo/hydra][hydra]] with ~dap-hydra~. You can automatically trigger
    the hydra when the program hits a breakpoint by using the following code.

    #+BEGIN_SRC emacs-lisp
    (add-hook 'dap-stopped-hook
    (lambda (arg) (call-interactively #'dap-hydra)))
    #+END_SRC

  • Screenshot
    ** Java

** Swift

** RUST
#+caption: RUST via Native Debug

** Go

** Javascript
#+caption: Javascript via Firefox debugger

  • Features

    • Launch/Attach
    • Breakpoints
    • Exceptions
    • Pause & Continue
    • Step In/Out/Over
    • Callstacks
    • Threads
    • Multiple simultaneous debug sessions
    • Evaluating statements
    • Debug/Run configurations
    • Expressions
      ** Debugger commands, Command, Description, --------------------------------+-----------------------------------------------------------------, ~dap-breakpoint-toggle~, Toggle breakpoint at line, ~dap-breakpoint-delete~, Delete breakpoint at line, ~dap-breakpoint-add~, Add java breakpoint at line, ~dap-breakpoint-condition~, Set/unset breakpoint condition, ~dap-breakpoint-hit-condition~, Set/unset breakpoint hit condition, ~dap-breakpoint-log-message~, Set/unset breakpoint log message, ~dap-eval~, Eval string, ~dap-eval-region~, Eval region string, ~dap-eval-thing-at-point~, Eval symbol at point, ~dap-step-in~, Debug step in, ~dap-next~, Debug next, ~dap-step-out~, Debug step out, ~dap-stop-thread~, Stop thread, ~dap-restart-frame~, Restart frame, ~dap-continue~, Debug continue, ~dap-disconnect~, Cancel current debug session, ~dap-switch-stack-frame~, Switch active stack frame, ~dap-switch-thread~, Switch active thread, ~dap-switch-session~, Switch active session, ~dap-debug-edit-template~, Generate run command, ~dap-debug~, Create and run new configuration using the available templates, ~dap-debug-last~, Debug previous configuration, ~dap-debug-recent~, Select configuration to run from the previously started command, ~dap-go-to-output-buffer~, Go output buffer, ** Windows, Command, Description, ---------------------------------+--------------------------------------, ~dap-ui-sessions~, Show active/terminated sessions view, ~dap-ui-locals~, Show locals view, ~dap-ui-expressions~, Show expressions view, ~dap-ui-breakpoints~, Show breakpoints view, ~dap-ui-repl~, DAP UI REPL, ** Sessions
      The session view is showed after invoking ~dap-ui-sessions~ . It represents
      the list of the active sessions.
      ** Locals
      Locals can be viewed after invoking ~dap-ui-locals~.
      ** Expressions
      Watch expressions can be viewed after invoking ~dap-ui-expressions~. You
      could add remove watch expressions via =dap-ui-expressions-add= and
      =dap-ui-expressions-remove=.
      ** Breakpoints
      Breakpoints can be viewed after invoking ~dap-ui-breakpoints~.
      *** Keybindings, Command, Description, Keybindings, --------------------------------------+--------------------------------+-------------, ~dap-ui-breakpoints-goto~, Go to breakpoint under cursor, , ~dap-ui-breakpoints-delete~, Delete breakpoint under cursor, d, ~dap-ui-breakpoints-delete-selected~, Delete selected breakpoints, D, ~bui-list-mark~, Mark breakpoint under point, m, ~bui-list-unmark~, Unmark breakpoint under point, u, ~bui-list-unmark-all~, Unmark breakpoint under point, U, ** Loaded sources
      Loaded sources can be viewed by invoking ~dap-tm-loaded-sources~.
      ** DAP debug REPL
      DAP provides a debug shell to execute commands when the program has hit
      breakpoints. The REPL has the same features as regular emacs shells (e.g.
      command history, ~C-p/n~ navigation through history, etc.) in addition to
      optional ~company-mode~ autocompletion.

  • Configuration
    ** DAP mode configuration
    Enable both ~dap-mode~ and ~dap-ui-mode~ (requires posframe to be installed manually, available only for emacs version >= 26).
    #+BEGIN_SRC emacs-lisp
    (dap-mode 1)
    (dap-ui-mode 1)
    ;; enables mouse hover support
    (dap-tooltip-mode 1)
    ;; use tooltips for mouse hover
    ;; if it is not enabled `dap-mode' will use the minibuffer.
    (tooltip-mode 1)
    #+END_SRC
    After enabling DAP mode on emacs side follow the language specific settings.
    ** Java
    *** Installation
    Latest version of [[https://github.com/emacs-lsp/lsp-java][LSP Java]] will automatically discover if ~dap-mode~ is
    present and it will download and install the required server side
    components. If you have already downloaded a ~Eclispe JDT Server~ you will
    have to force a server update via ~lsp-java-update-server~. In order to enable lsp java,
    you will have to require ~dap-java.el~.
    #+BEGIN_SRC emacs-lisp
    (require 'dap-java)
    #+END_SRC
    *** Commands, Command, Description, ------------------------------+-------------------, ~dap-java-debug~, Debug java, ~dap-java-run-test-method~, Run test method, ~dap-java-debug-test-method~, Debug test method, ~dap-java-run-test-class~, Run test class, ~dap-java-debug-test-class~, Debug test class, You can also edit one of the existing templates and execute it with
    ~dap-debug~. dap-mode will take care of filling missing values, such as
    classpath. JVM arguments can be specified with ~:vmArgs~:

#+BEGIN_SRC emacs-lisp
(dap-register-debug-template "My Runner"
(list :type "java"
:request "launch"
:args ""
:vmArgs "-ea -Dmyapp.instance.name=myapp_1"
:projectName "myapp"
:mainClass "com.domain.AppRunner"
:env '(("DEV" . "1"))))
#+END_SRC
** Python
*** Installation
- install latest version of ptvsd.
#+BEGIN_SRC bash
pip install "ptvsd>=4.2"
#+END_SRC
- Then add the following line in your config:
#+BEGIN_SRC elisp
(require 'dap-python)
#+END_SRC
This will add the python related configuration to ~dap-debug~.

*** Usage
A template named "Python :: Run Configuration" will appear, which will execute
the currently visited module. This will fall short whenever you need to specify
arguments, environment variables or execute a setuptools based script. In such
case, define a template:

#+BEGIN_SRC emacs-lisp
(dap-register-debug-template "My App"
(list :type "python"
:args "-i"
:cwd nil
:env '(("DEBUG" . "1"))
:target-module (expand-file-name "~/src/myapp/.env/bin/myapp")
:request "launch"
:name "My App"))
#+END_SRC

** Ruby
- Download and extract [[https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby][VSCode Ruby Extension]]. You can do that either by:
- Calling ~dap-ruby-setup~, the extension will be downloaded and all your path will be automatically set up.
- Or download the extension manually. Make sure that ~dap-ruby-debug-program~ is: ~("node" path-to-main-js)~ where ~node~ is either "node" if nodejs is on the path or path to nodejs and ~path-to-main-js~ is full path ~./out/debugger/main.js~ which is part of the downloaded VScode package.
- Follow the instructions on installing ~rdebug-ide~ from [[https://github.com/rubyide/vscode-ruby/wiki/1.-Debugger-Installation][Ruby Debug Installation]]
- Put in your emacs configuration.
#+BEGIN_SRC elisp
(require 'dap-ruby)
#+END_SRC
** LLDB
*** Installation
LLDB is a debugger that supports, among others, C, C++, Objective-C and Swift.

- Clone and follow the instructions to compile lldb-vscode from https://github.com/llvm-mirror/lldb/tree/master/tools/lldb-vscode
- Put in your emacs configuration.
  #+BEGIN_SRC elisp
    (require 'dap-lldb)
  #+END_SRC

*Note*: For proper Swift support, you need to compile LLDB from https://github.com/apple/swift-lldb and put the compiled LLDB library/framework in the "extensions" folder.

** Elixir
Make sure that you have properly configured ~Elixir~ and that you have [[https://github.com/elixir-lsp/elixir-ls][Elixir LS]]
binaries on the path and put in your emacs configuration.
#+BEGIN_SRC elisp
(require 'dap-elixir)
#+END_SRC
Then when you do ~dap-debug-edit-template~ and select Elixir which will
generate runnable debug configuration. For more details on supported settings
by the Elixir Debug Server refer to its documentation.
** PHP
Simplify setup of vscode extension with ~dap-php-setup~ after requiring ~dap-php~.

This is using [[https://github.com/felixfbecker/vscode-php-debug][felixbecker/vscode-php-debug]]
([[https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug][downloadable from the marketplace]])
as dap-server between emacs and the xdebug-extension on the http-server side. Make sure it is trans/compiled to
javascript properly. Only tested under linux with node.
#+BEGIN_SRC elisp
(require 'dap-php)
#+END_SRC
Start debugging by selecting "PHP Run Configuration" from the ~dap-debug~ menu, issue the debug request in your
browser by choosing the running thread (~dap-switch-thread~) and then ~dap-step-in~.
** Native Debug (GDB/LLDB)
Using https://github.com/WebFreak001/code-debug
*** Configuration
For easier of setting up vscode extension, you only need call ~dap-gdb-lldb-setup~ after requiring ~dap-gdb-lldb~.

Or download and extract [[https://marketplace.visualstudio.com/items?itemName=webfreak.debug][VSCode extension]] (make sure that ~dap-gdb-lldb-path~ is pointing to the extract location).
#+BEGIN_SRC elisp
  (require 'dap-gdb-lldb)
#+END_SRC
Then do ~dap-debug~ or ~dap-debug-edit-template~ and selet GBD or LLDB configuration.

** Go
*** Installation
- For easier of setting up vscode extension, you only need call ~dap-go-setup~ after requiring ~dap-go~.
- Or manually download and extract [[https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go][VSCode Go Extension]].. it is actually zip file.
- check that you now have .emacs.d/.extension/vscode/ms-vscode.go/extension/out/src/debugAdapter/goDebug.js
- install latest stable nodejs
- install gopls
- Install the delve command by following instructions on [[https://github.com/go-delve/delve/tree/master/Documentation/installation][delve - installation]].
- install lsp-mode
- Put in your emacs configuration.
#+BEGIN_SRC elisp
(require 'dap-go)
#+END_SRC
- set up hydra hook as instructed above
**** Usage
assume you have your code at ~/src/cool/cmd/app/app.go
- open your main package file e.g ~/src/cool/cmd/app/app.go
- or open a test file e.g app_test.go
- add folder to lsp session where your go.mod is or would be
- M-x lsp-workspace-folders-add ~/src/cool
- set break point
- M-x dap-debug
- if you are debugging test files use "Go Launch File Configuration"
- else select e.g "Go Launch Unoptimized Debug Package Configuration"
**** Trouble shooting
- put (setq dap-print-io t) and check messages buffer
- e.g linter can return note at debug session response resulting debug session to fail
** Javascript
*** Firefox
**** Installation
- For easier of setting up vscode extension, you only need call ~dap-firefox-setup~ after requiring ~dap-firefox~.
- Or manually download and extract [[https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-firefox-debug][VSCode Firefox Debug Extension]].
- Make sure that ~dap-firefox-debug-program~ is pointing to the proper file.
- Put in your configuration file:
#+BEGIN_SRC elisp
(require 'dap-firefox)
#+END_SRC
**** Usage
~dap-debug~ or ~dap-debug-edit-template~ and select the firefox template. For additional documentation on the supported template parameters or about different configuration templates refer to [[https://github.com/hbenl/vscode-firefox-debug][Firefox Debug Adapter]].
*** Chrome
**** Installation
- For easier of setting up vscode extension, you only need call ~dap-chrome-setup~ after requiring ~dap-chrome~.
- Or manually download and extract [[https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome][VSCode Chrome Debug Extension]].
- Make sure that ~dap-chrome-debug-program~ is pointing to the proper file.
- Put in your configuration file:
#+BEGIN_SRC elisp
(require 'dap-chrome)
#+END_SRC
**** Usage
~dap-debug~ or ~dap-debug-edit-template~ and select the chrome template. For additional documentation on the supported template parameters or about different configuration templates refer to [[https://github.com/Microsoft/vscode-chrome-debug][Chrome Debug Adapter]].
*** Microsoft Edge
**** Installation
- For easier of setting up vscode extension, you only need call ~dap-edge-setup~ after requiring ~dap-edge~.
- Or manually download and extract [[https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-edge][VSCode Edge Debug Extension]].
- Make sure that ~dap-edge-debug-program~ is pointing to the proper file.
- Put in your configuration file:
#+BEGIN_SRC elisp
(require 'dap-edge)
#+END_SRC
**** Usage
~dap-debug~ or ~dap-debug-edit-template~ and select the edge template. For additional documentation on the supported template parameters or about different configuration templates refer to [[https://github.com/microsoft/vscode-edge-debug2][Edge Debug Adapter]].
*** Node
**** Installation
- For easier of setting up vscode extension, you only need call ~dap-node-setup~ after requiring ~dap-node~.
- Or manually download and extract [[https://marketplace.visualstudio.com/items?itemName=ms-vscode.node-debug2][VSCode Node Debug Extension]].
- Make sure that ~dap-node-debug-program~ is pointing to the proper file.
- Put in your configuration file:
#+BEGIN_SRC elisp
(require 'dap-node)
#+END_SRC
**** Usage
~dap-debug~ or ~dap-debug-edit-template~ and select the node template. For additional documentation on the supported template parameters or about different configuration templates refer to [[https://code.visualstudio.com/docs/nodejs/nodejs-debugging][Nodejs Debugging]].
** Powershell
#+BEGIN_SRC elisp
(require 'dap-pwsh)
#+END_SRC
Start debugging by selecting "Powershell: Launch Script" from ~dap-debug~ menu.

  • Extending DAP with new Debug servers
    There are two methods that are used for registering remote extensions:

    • ~dap-register-debug-provider~ - register a method to call for populating
      startup parameters. It should either populate ~:debugPort~ and ~:host~ in
      case of TCP Debug Adapter Server or ~:dap-server-path~ when STD out must be used for
      Debug Adapter Server communication.

    • ~dap-register-debug-template~ register a debug template which will be
      available when ~dap-debug~ is called. The debug template must specify
      ~:type~ key which will be used to determine the provider to be called to
      populate missing fields.
      *** Example
      For full example you may check ~dap-java.el~.
      #+BEGIN_SRC emacs-lisp
      (dap-register-debug-provider
      "programming-language-name"
      (lambda (conf)
      (plist-put conf :debugPort 1234)
      (plist-put conf :host "localhost")
      conf))

      (dap-register-debug-template "Example Configuration"
      (list :type "java"
      :request "launch"
      :args ""
      :name "Run Configuration"))
      #+END_SRC

  • Links
    • [[https://code.visualstudio.com/docs/extensionAPI/api-debugging][Debug Adapter Protocol]]
    • [[https://github.com/emacs-lsp/lsp-java][LSP Java]]
    • [[https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/][Debug Adapter Protocol Server Implementations]]
  • Acknowledgments
    • [[https://github.com/danielmartin][Daniel Martin]] - LLDB integration.
    • [[https://github.com/kiennq][Kien Nguyen]] - NodeJS debugger, Edge debuggers, automatic extension installation.
    • [[https://github.com/Ladicle][Aya Igarashi]] - Go debugger integration.

主要指標

概覽
名稱與所有者emacs-lsp/dap-mode
主編程語言Emacs Lisp
編程語言Emacs Lisp (語言數: 4)
平台
許可證GNU General Public License v3.0
所有者活动
創建於2018-05-19 20:10:50
推送於2025-04-23 00:28:27
最后一次提交2025-04-22 17:27:51
發布數8
最新版本名稱0.8 (發布於 )
第一版名稱v0.1 (發布於 )
用户参与
星數1.3k
關注者數29
派生數188
提交數863
已啟用問題?
問題數522
打開的問題數220
拉請求數271
打開的拉請求數26
關閉的拉請求數24
项目设置
已啟用Wiki?
已存檔?
是復刻?
已鎖定?
是鏡像?
是私有?