2020-04-15 12:39:59 +02:00
|
|
|
# DAP (Debug Adapter Protocol)
|
|
|
|
|
2022-04-15 15:04:15 +02:00
|
|
|
`nvim-dap` is a Debug Adapter Protocol client implementation for [Neovim][1].
|
|
|
|
`nvim-dap` allows you to:
|
2021-01-17 15:52:04 +01:00
|
|
|
|
|
|
|
- Launch an application to debug
|
|
|
|
- Attach to running applications and debug them
|
|
|
|
- Set breakpoints and step through code
|
|
|
|
- Inspect the state of the application
|
2020-04-15 12:39:59 +02:00
|
|
|
|
2021-07-02 16:46:17 +02:00
|
|
|
![demo][demo]
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2021-01-17 15:52:04 +01:00
|
|
|
## Installation
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2023-02-10 14:57:50 +01:00
|
|
|
[![LuaRocks](https://img.shields.io/luarocks/v/mfussenegger/nvim-dap?logo=lua&color=purple)](https://luarocks.org/modules/mfussenegger/nvim-dap)
|
|
|
|
|
2022-08-03 19:29:34 +02:00
|
|
|
- Install nvim-dap like any other Neovim plugin:
|
|
|
|
- `git clone https://github.com/mfussenegger/nvim-dap.git ~/.config/nvim/pack/plugins/start/nvim-dap`
|
|
|
|
- Or with [vim-plug][11]: `Plug 'mfussenegger/nvim-dap'`
|
|
|
|
- Or with [packer.nvim][12]: `use 'mfussenegger/nvim-dap'`
|
2021-01-17 15:52:04 +01:00
|
|
|
- Generate the documentation for nvim-dap using `:helptags ALL` or
|
|
|
|
`:helptags <PATH-TO-PLUGIN/doc/>`
|
2020-04-17 14:27:24 +02:00
|
|
|
|
2022-08-03 19:29:34 +02:00
|
|
|
Supported Neovim versions:
|
|
|
|
|
|
|
|
- Latest nightly
|
2024-05-30 12:34:14 +02:00
|
|
|
- 0.10.x (Recommended)
|
|
|
|
- 0.9.5
|
2022-08-03 19:29:34 +02:00
|
|
|
|
2021-01-17 15:52:04 +01:00
|
|
|
You'll need to install and configure a debug adapter per language. See
|
|
|
|
|
|
|
|
- [:help dap.txt](doc/dap.txt)
|
|
|
|
- the [Debug-Adapter Installation][5] wiki
|
|
|
|
- `:help dap-adapter`
|
|
|
|
- `:help dap-configuration`
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
A typical debug flow consists of:
|
|
|
|
|
|
|
|
- Setting breakpoints via `:lua require'dap'.toggle_breakpoint()`.
|
|
|
|
- Launching debug sessions and resuming execution via `:lua require'dap'.continue()`.
|
|
|
|
- Stepping through code via `:lua require'dap'.step_over()` and `:lua require'dap'.step_into()`.
|
2021-07-02 16:46:17 +02:00
|
|
|
- Inspecting the state via the built-in REPL: `:lua require'dap'.repl.open()`
|
|
|
|
or using the widget UI (`:help dap-widgets`)
|
2021-01-17 15:52:04 +01:00
|
|
|
|
|
|
|
See [:help dap.txt](doc/dap.txt), `:help dap-mapping` and `:help dap-api`.
|
2020-08-26 21:32:03 +02:00
|
|
|
|
2021-01-17 15:52:04 +01:00
|
|
|
## Supported languages
|
|
|
|
|
|
|
|
In theory all of the languages for which a debug adapter exists should be
|
|
|
|
supported.
|
|
|
|
|
|
|
|
- [Available debug adapters][13]
|
|
|
|
- [nvim-dap Debug-Adapter Installation & Configuration][5]
|
|
|
|
|
|
|
|
The Wiki is community maintained. If you got an adapter working that isn't
|
2022-04-17 18:41:51 +02:00
|
|
|
listed yet, please extend the Wiki.
|
2020-12-03 19:43:53 +01:00
|
|
|
|
2022-04-17 18:41:51 +02:00
|
|
|
Some debug adapters have [language specific
|
|
|
|
extensions](https://github.com/mfussenegger/nvim-dap/wiki/Extensions#language-specific-extensions).
|
|
|
|
Using them over a manual configuration is recommended, as they're
|
|
|
|
usually better maintained.
|
|
|
|
|
|
|
|
If the instructions in the wiki for a debug adapter are not working, consider
|
|
|
|
that debug adapters may have made changes since the instructions were written.
|
|
|
|
You may want to read the release notes of the debug adapters or try with an
|
|
|
|
older version. Please update the wiki if you discover outdated examples.
|
2020-09-11 22:05:22 +02:00
|
|
|
|
|
|
|
## Goals
|
2020-04-17 14:27:24 +02:00
|
|
|
|
2021-01-17 15:52:04 +01:00
|
|
|
- Have a basic debugger in Neovim.
|
|
|
|
- Extensibility and double as a DAP client library. This allows other plugins
|
|
|
|
to extend the debugging experience. Either by improving the UI or by making
|
|
|
|
it easier to debug parts of an application.
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2021-06-03 21:46:31 +02:00
|
|
|
- Examples of UI/UX extensions are [nvim-dap-virtual-text][7] and [nvim-dap-ui][15]
|
2021-01-17 15:52:04 +01:00
|
|
|
- Examples for language specific extensions include [nvim-jdtls][8] and [nvim-dap-python][9]
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2021-01-17 15:52:04 +01:00
|
|
|
## Extensions
|
|
|
|
|
|
|
|
All known extensions are listed in the [Wiki][10]. The wiki is community
|
|
|
|
maintained. Please add new extensions if you built one or if you discovered one
|
|
|
|
that's not listed.
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2020-09-11 22:05:22 +02:00
|
|
|
## Non-Goals
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2020-09-11 22:05:22 +02:00
|
|
|
- Debug adapter installations are out of scope. It's not the business of an
|
|
|
|
editor plugin to re-invent a package manager. Use your system package
|
|
|
|
manager. Use Nix. Use Ansible.
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2022-04-17 18:44:32 +02:00
|
|
|
- [nvim-dapconfig](https://github.com/nvim-lua/wishlist/issues/37#issuecomment-1023363686)
|
|
|
|
|
2020-09-11 22:05:22 +02:00
|
|
|
- Vim support. It's not going to happen. Use [vimspector][2] instead.
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2020-09-11 22:05:22 +02:00
|
|
|
## Alternatives
|
|
|
|
|
|
|
|
- [vimspector][2]
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2020-04-15 12:39:59 +02:00
|
|
|
|
2021-11-12 16:29:29 +01:00
|
|
|
## Contributing
|
|
|
|
|
|
|
|
Contributions are welcome:
|
|
|
|
|
|
|
|
- Give concrete feedback about usability.
|
|
|
|
- Triage issues. Many of the problems people encounter are debug
|
|
|
|
adapter specific.
|
|
|
|
- Improve upstream debug adapter documentation to make them more editor
|
|
|
|
agnostic.
|
|
|
|
- Improve the Wiki. But please refrain from turning it into comprehensive debug
|
|
|
|
adapter documentation that should go upstream.
|
|
|
|
- Write extensions.
|
|
|
|
|
|
|
|
Before making direct code contributions, please create a discussion or issue to
|
|
|
|
clarify whether the change is in scope of the nvim-dap core.
|
|
|
|
|
|
|
|
Please keep pull requests focused and don't change multiple things at the same
|
|
|
|
time.
|
|
|
|
|
2021-01-17 15:52:04 +01:00
|
|
|
## Features
|
2020-04-15 21:06:56 +02:00
|
|
|
|
2021-01-17 15:52:04 +01:00
|
|
|
- [x] launch debug adapter
|
|
|
|
- [x] attach to debug adapter
|
|
|
|
- [x] toggle breakpoints
|
|
|
|
- [x] breakpoints with conditions
|
|
|
|
- [x] logpoints
|
|
|
|
- [x] set exception breakpoints
|
|
|
|
- [x] step over, step into, step out
|
|
|
|
- [x] step back, reverse continue
|
|
|
|
- [x] Goto
|
|
|
|
- [x] restart
|
|
|
|
- [x] stop
|
|
|
|
- [x] pause
|
|
|
|
- [x] evaluate expressions
|
|
|
|
- [x] REPL (incl. commands to show threads, frames and scopes)
|
2020-12-31 03:20:37 +01:00
|
|
|
|
2020-04-15 12:39:59 +02:00
|
|
|
|
|
|
|
[1]: https://neovim.io/
|
|
|
|
[2]: https://github.com/puremourning/vimspector
|
2020-04-17 22:25:49 +02:00
|
|
|
[5]: https://github.com/mfussenegger/nvim-dap/wiki/Debug-Adapter-installation
|
2020-08-26 21:32:03 +02:00
|
|
|
[7]: https://github.com/theHamsta/nvim-dap-virtual-text
|
2020-09-11 22:05:22 +02:00
|
|
|
[8]: https://github.com/mfussenegger/nvim-jdtls
|
2020-11-15 15:21:29 +01:00
|
|
|
[9]: https://github.com/mfussenegger/nvim-dap-python
|
2020-12-03 19:43:53 +01:00
|
|
|
[10]: https://github.com/mfussenegger/nvim-dap/wiki/Extensions
|
2021-01-17 15:52:04 +01:00
|
|
|
[11]: https://github.com/junegunn/vim-plug
|
|
|
|
[12]: https://github.com/wbthomason/packer.nvim
|
|
|
|
[13]: https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/
|
2021-06-03 21:46:31 +02:00
|
|
|
[15]: https://github.com/rcarriga/nvim-dap-ui
|
2021-07-02 16:46:17 +02:00
|
|
|
[demo]: https://user-images.githubusercontent.com/38700/124292938-669a7100-db56-11eb-93b8-77b66994fc8a.gif
|
|
|
|
|