DOCSEARCHbyAlgolia
Submit Docs

nvim-dap-view

website·Indexed 30 days ago

https://igorlfs.github.io/nvim-dap-view/home

A modern debugging UI for Neovim (requires Neovim 0.11+) that provides a visual interface for the Debug Adapter Protocol (DAP). It includes features such as a control bar, custom views, disassembly view, dynamic layout management, and support for custom formatting and highlight groups.

Tokens
7.9K
Snippets
40
Records
57
Agent score
75%

What's inside nvim-dap-view

  1. Understand the Debug Adapter Protocol (DAP) concept

    The Debug Adapter Protocol (DAP) standardizes communication between a text editor and a debugger. It introduces 'debug adapters'—programs that act as intermediaries to make various debuggers comply with a common communication standard. This prevents editors from needing custom integrations for every individual debugger. Note that a debugger (e.g., lldb) and a debug adapter (e.g., codelldb) are distinct programs, although some modern debuggers (like gdb 14.0+) implement the protocol natively.

  2. Restore nvim-dap-view state using Vim sessions

    nvim-dap-view integrates with the native Vim session system to persist specific debugger state across sessions.

    Restored Data:

    • The currently selected view (section).
    • The full state of watched expressions, including variable expansions.

    Non-Restored (Ephemeral) Data:

    • Active DAP sessions.
    • Stack traces.

    Optional Breakpoint Restoration: Breakpoints are not restored by nvim-dap-view itself. To restore breakpoints, use a plugin like persistent-breakpoints.nvim or a session manager that supports breakpoint persistence (e.g., possession.nvim).

  3. Understand nvim-dap-view core features

    nvim-dap-view provides a set of integrated views and UI enhancements for debugging in Neovim:

    • Watches View: CRUD operations for user-defined expressions evaluated by the debug adapter.
    • Threads View: List of threads and stack traces with the ability to jump to functions in the call stack and filter frames via Lua patterns.
    • Breakpoints View: List of breakpoints with syntax highlighting (Treesitter/LSP) and navigation to breakpoint locations.
    • Exceptions View: Control debugger stop behavior for exceptions.
    • Scopes View: Inspect, expand, collapse, and set values of variables in scope.
    • Sessions View: Switch between multiple debugging sessions (disabled by default).
    • REPL & Console Views: Integration with the nvim-dap REPL and terminal console.
    • Control Bar: A clickable button bar for session control (disabled by default).
    • Virtual Text: Displays variable values inline using asynchronous Treesitter parsing (disabled by default).
    • Hover: A keymap-driven window to inspect and modify variable states.

  4. Install nvim-dap-view

    To install nvim-dap-view, use the following configuration.

    Requirements:

    • Neovim 0.11+ (Note: Inline virtual text specifically requires 0.12+).
    • A Nerd Font is recommended (soft requirement).
    • nvim-treesitter is required for virtual text functionality.
    vim.pack.add({
 { src = "https://github.com/igorlfs/nvim-dap-view", version = vim.version.range("1.*")  },
})

  5. Define a debug adapter in nvim-dap

    To use a debugger in Neovim, you must first define an adapter in your nvim-dap configuration. This tells the plugin how to interact with the adapter executable. You only need to define an adapter once. For example, to define the codelldb adapter (used for C, C++, and Rust), you specify the adapter type as 'executable' and provide the command to run it.
    require("dap").adapters.codelldb = {
    type = "executable",
    command = "codelldb", -- or if not in $PATH: "/absolute/path/to/codelldb",

    -- On windows you may have to uncomment this:
    -- detached = false,
}

  6. Override jump behavior manually in nvim-dap-view

    To override your configured switchbuf settings for a single jump, press <C-w><CR>. This opens a list of all available switching options, allowing you to force a specific behavior for the current action.

  7. Configure nvim-dap-view settings

    The nvim-dap-view plugin applies default configurations automatically upon loading, so no explicit setup call is required. To override defaults, use require"dap-view".setup(opts). The provided options are deep-merged with the defaults, meaning you only need to specify the keys you wish to change.
    require("dap-view").setup({
    -- Your overrides here
})

  8. Create custom buttons for the nvim-dap-view Control Bar

    You can add custom buttons to the control bar by defining them in the winbar.controls.custom_buttons table and then adding the button's key to the winbar.controls.buttons list.

    A custom button requires two methods:

    1. render: A function that returns the string to display (e.g., an emoji or NerdFont glyph). It receives the focused session as a parameter.
    2. action: A function executed on click. It receives three arguments: clicks (number of clicks), button (the button clicked: l, r, m), and modifiers (a list of pressed modifiers: c for control, s for shift, a for alt, and m for meta).
    return {
    winbar = {
        controls = {
            enabled = true,
            -- Add the custom button key ('fun') to the active buttons list
            buttons = { "play", "step_into", "fun" }, 
            custom_buttons = {
                fun = {
                    render = function(session)
                        return "🎉"
                    end,
                    action = function(clicks, button, modifiers)
                        vim.print("🎊")
                    end,
                },
            },
        },
    },
}

  9. Enable Disassembly View in nvim-dap-view

    The Disassembly View is a custom view built on top of nvim-dap-disasm. To use it, you must first install the nvim-dap-disasm plugin. Once installed, enable the view by adding the disassembly keyword to the winbar.sections table in your configuration.
    return {
    winbar = {
        sections = {
            "disassembly",
            -- other sections
        },
    },
}

  10. Configure nvim-dap-view for session restoration

    To ensure nvim-dap-view successfully restores its state when using a session manager, the following configuration requirements must be met:

    1. Vim Session Options: The 'sessionoptions' setting must include the "global" flag.
    2. Loading Strategy: nvim-dap-view must NOT be manually lazy loaded. Because the plugin handles its own lazy loading, adding an external lazy load wrapper may prevent the session restoration hook from triggering.
    3. Session Manager Compatibility: Ensure your session manager plugin uses native Vim sessions as its backbone rather than a custom implementation.
    -- Ensure 'global' is in sessionoptions
vim.opt.sessionoptions:append('global')

  11. Start a debugging session in nvim-dap

    To begin debugging, ensure your program is compiled with debug symbols. Follow these steps:

    1. Set a breakpoint using :DapToggleBreakpoint (or a custom mapping) to prevent the program from finishing before you can inspect it.
    2. Start the session using :DapContinue.
    3. Refer to :help dap-user-commands for a full list of available commands.

  12. Register a custom view for plugin distribution

    Plugin authors can use the register_view function to automatically load a custom view. This removes the requirement for end-users to manually define the view in their configuration files.