Dape - Emacs的调试适配器协议

作者: Daniel Pettersson

Dape是Emacs的调试适配器客户端。调试适配器协议，类似于更广为人知的语言服务器协议，旨在为编程工具建立一个通用API。然而，它不是提供诸如代码补全之类的功能，而是为调试器提供一个标准化的接口。

要开始调试会话，请调用dape命令。在小缓冲区提示中，输入dape-configs中的调试适配器配置名称。

为了获得完整功能，请确保在源代码缓冲区中启用eldoc-mode，并启用repeat-mode以获得更舒适的按键映射。

特性

内置支持（describe-variable dape-configs）
日志断点
条件断点
变量探索器
变量监视
使用eldoc的变量悬停
REPL
类似gdb-mi.el的界面
使用hexl的内存编辑器
与compile集成
调试适配器配置的人体工程学
除核心Emacs外无外部依赖

使用(setq dape-buffer-window-arrangement 'right)： [[https://raw.githubusercontent.com/svaante/dape/resources/c-right-14.0.0.png]] 使用(setq dape-buffer-window-arrangement 'gud) + corfu作为completion-in-region-function： [[https://raw.githubusercontent.com/svaante/dape/resources/js-gud-14.0.0.png]] 带有minibuffer适配器配置提示： [[https://raw.githubusercontent.com/svaante/dape/resources/minibuffer-hints-14.0.0.png]] 截图使用[[https://elpa.gnu.org/packages/standard-themes.html][standard-light]]主题。

配置

Dape包含了各种编程语言的预定义调试适配器配置。更多详情请参考dape-configs。如果dape没有包含适合你需求的配置，你可以实现自己的配置。

(use-package dape
  :preface
  ;; 默认情况下，dape与`gud'共享相同的键绑定前缀
  ;; 如果你不想使用任何前缀，将其设置为nil。
  ;; (setq dape-key-prefix "\C-x\C-a")

  :hook
  ;; 退出时保存断点
  ;; ((kill-emacs . dape-breakpoint-save)
  ;; 启动时加载断点
  ;;  (after-init . dape-breakpoint-load))

  :init
  ;; 使用类似gud（gdb-mi）的窗口配置
  ;; (setq dape-buffer-window-arrangement 'gud)

  :config
  ;; 信息缓冲区放在右侧
  ;; (setq dape-buffer-window-arrangement 'right)

  ;; 使用鼠标设置断点的全局绑定
  ;; (dape-breakpoint-global-mode)

  ;; 脉冲显示源代码行（可能影响性能）
  ;; (add-hook 'dape-display-source-hook 'pulse-momentary-highlight-one-line)

  ;; 启动时不显示信息和/或缓冲区
  ;; (remove-hook 'dape-start-hook 'dape-info)
  ;; (remove-hook 'dape-start-hook 'dape-repl)

  ;; 在停止时显示信息和/或repl缓冲区
  ;; (add-hook 'dape-stopped-hook 'dape-info)
  ;; (add-hook 'dape-stopped-hook 'dape-repl)

  ;; 编译成功时关闭编译缓冲区
  ;; (add-hook 'dape-compile-hook 'kill-buffer)

  ;; 启动时保存缓冲区，对解释型语言有用
  ;; (add-hook 'dape-start-hook (lambda () (save-some-buffers t t)))

  ;; Projectile用户
  ;; (setq dape-cwd-fn 'projectile-project-root)
  )

与dap-mode的区别

Dape除了核心Emacs包外没有任何依赖，并尽可能地充分利用它们。

Dape在配置方面采取了略有不同的方法。

Dape不支持launch.json文件，如果需要每个项目的配置，请使用dir-locals和dape-command。
Dape通过允许用户使用选项修改或添加现有配置的PLIST条目来增强小缓冲区的人体工程学。例如dape-config :cwd default-directory :program "/home/user/b.out" compile "gcc -g -o b.out main.c"。
没有魔法，没有特殊变量如${workspaceFolder}。相反，函数和变量在启动新会话之前被解析。
尝试设想如果vscode从未存在，调试适配器配置在Emacs中会如何实现。

支持的调试适配器

理论上，所有调试适配器都应该与Dape兼容。

Javascript - vscode-js-*

安装node
访问https://github.com/microsoft/vscode-js-debug/releases/ 并下载资源js-debug-dap-<version>.tar.gz
解压 mkdir -p ~/.emacs.d/debug-adapters && tar -xvzf js-debug-dap-<version>.tar.gz -C ~/.emacs.d/debug-adapters

Go - dlv

参见[[https://github.com/go-delve/delve/tree/master/Documentation/installation][delve安装]]。更多信息请参见[[https://github.com/go-delve/delve/blob/master/Documentation/usage/dlv_dap.md][文档]]。

C, C++, Rust等 - GDB

确保你的GDB版本是14.1或更新。更多详情请参考[[https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html][文档]]。

C, C++和Rust - codelldb

下载最新的vsix [[https://github.com/vadimcn/codelldb/releases][发布版]]，选择适合你平台的codelldb-<platform>-<os>.vsix
解压 mkdir -p ~/.emacs.d/debug-adapters && unzip codelldb-<platform>-<os>.vsix -d ~/.emacs.d/debug-adapters/codelldb

C和C++ - cpptools

下载最新的vsix文件并用你喜欢的解压工具解压。

下载最新的vsix [[https://github.com/microsoft/vscode-cpptools/releases][发布版]]，选择适合你平台的cpptools-<platform>-<os>.vsix
解压 mkdir -p ~/.emacs.d/debug-adapters && unzip cpptools-<os>-<platform>.vsix -d ~/.emacs.d/debug-adapters/cpptools
然后 chmod +x ~/.emacs.d/debug-adapters/cpptools/extension/debugAdapters/bin/OpenDebugAD7
以及 chmod +x ~/.emacs.d/debug-adapters/cpptools/extension/debugAdapters/lldb-mi/bin/lldb-mi

参见[[https://code.visualstudio.com/docs/cpp/launch-json-reference][选项]]。

C, C++和Rust - lldb-dap

为你的平台安装[[https://github.com/helix-editor/helix/wiki/Debugger-Configurations#install-debuggers][lldb-dap]]

MacOS使用homebrew的示例

安装llvm套件：brew install llvm
将llvm路径添加到PATH变量的前面（$(brew --prefix --installed llvm)/bin）
执行M-x dape并传入感兴趣的参数
- 要传递参数，使用:args ["arg1" "arg2" ..]
- 要使用a.out以外的程序（例如，对于Rust），使用:program "target/debug/<crate_name>"

Python - debugpy

使用pip安装debugpy pip install debugpy

参见[[https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings][选项]]。

Godot

在"Editor" > "Editor Settings" > "Debug Adapter"下配置调试适配器端口。

Dart - flutter

安装请参见https://docs.flutter.dev/get-started/install

C# - netcoredbg

安装请参见https://github.com/Samsung/netcoredbg **Ruby - rdbg 使用 ~~gem install debug~~ 安装。

更多信息请参见 https://github.com/ruby/debug

**Java - 带有Java Debug Server插件的JDTLS 有关JDTLS的安装，请参见 https://github.com/eclipse-jdtls/eclipse.jdt.ls。有关Java Debug Server插件的安装，请参见 https://github.com/microsoft/java-debug。 Java配置依赖于在启动Dape之前运行带插件的JDTLS的Eglot。按以下方式扩展 ~~eglot-server-programs~~ 以使JDTLS加载插件： #+begin_src emacs-lisp (add-to-list 'eglot-server-programs `((java-mode java-ts-mode) . ("jdtls" :initializationOptions (:bundles ["/PATH/TO/java-debug/com.microsoft.java.debug.plugin/target/com.microsoft.java.debug.plugin-VERSION.jar"])))) #+end_src

**PHP - Xdebug

安装并设置 =Xdebug=，参见[[https://github.com/xdebug/vscode-php-debug][说明]]
安装 =node=
下载最新的 =Xdebug= DAP适配器 =vsix= [[https://github.com/xdebug/vscode-php-debug/releases][发布版本]] =php-debug-.vsix=
解压 ~mkdir -p ~/.emacs.d/debug-adapters && unzip php-debug-.vsix -d ~~/.emacs.d/debug-adapters/php-debug~~

**其他未经测试的适配器如果你发现任何其他调试适配器的可用配置，请提交PR。

查看[[https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/][微软的列表]]以了解其他适配器，效果可能会有所不同。

*贡献 =dape= 遵循与GNU Emacs相同的版权分配政策。

任何具有法律[[https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant][重要性]]的贡献只有在作者完成相关文书工作后才能被合并。更多信息请参见[[https://www.fsf.org/licensing/contributor-faq][贡献者常见问题解答（FAQ）]]。

*性能

通过更改Emacs配置中关于进程交互和垃圾回收的值，可以在调试器中获得一些微小的性能提升。

**=gc-cons-threshold=

这个变量控制Emacs中垃圾回收的频率。太高的值会导致系统内存压力增加和更长的停顿，而太低的值会导致额外的中断和上下文切换（性能不佳）。

根据[[https://www.reddit.com/r/emacs/comments/brc05y/comment/eofulix/][GNU Emacs维护者Eli Zaretskii]]的说法：

: 我的建议是反复将gc-cons-threshold乘以2，直到你不再看到响应性的显著改善， : 在任何情况下都不要增加超过100倍左右。如果即使100倍的增加也没有帮助， : 那么可能是Lisp代码中存在更深层次的问题，产生了太多垃圾，或者也许GC不是导致slowdown的原因。

遵循这个建议的上限，你可以尝试将 =gc-cons-threshold= 设置为原始值的100倍：

#+begin_src elisp (setq gc-cons-threshold 80000000) ;; 原始值 * 100 #+end_src

**=read-process-output-max=

默认的 =read-process-output-max= 为4096字节，可能在某种程度上会抑制性能。

***Linux

在Linux上，你应该能够将其设置到大约 =1mb=。要检查最大值，请查看以下输出：

#+begin_src sh cat /proc/sys/fs/pipe-max-size #+end_src

设置方法：

#+begin_src elisp (setq read-process-output-max (* 1024 1024)) ;; 1mb #+end_src

***Mac OS

对于Mac OS，没有简单的方法查看操作系统的pipe-max-size。它可能约为 =64kb=。

#+begin_src elisp (setq read-process-output-max (* 64 1024)) ;; 64k #+end_src

***Windows

Windows似乎没有限制。你可以尝试 =1mb=。

#+begin_src elisp (setq read-process-output-max (* 1024 1024)) ;; 1mb #+end_src

*错误和问题在报告任何问题之前，请 ~~(setq dape-debug t)~~ 并查看 =dape-repl= 缓冲区。请在错误报告中分享你的 =dape-repl= 和 =dape-connection events= 缓冲区内容。 =master= 分支用作开发分支，elpa上的发布版本应该更稳定，因此如果bug影响了你的工作流程，请暂时使用elpa。

*致谢非常感谢João Távora的意见和jsonrpc；没有João，这个项目不会达到现在的水平。