Debugger Setup

AstroNvim v2.9 introduced debugging support with AstroNvim. We use a combination of nvim-dap for the debugger, mason-nvim-dap for interoperability with the Mason package manager, and nvim-dap-ui for a nice user interface while debugging.

Installing Debuggers With Mason

By default there are a few debuggers that can be automatically installed and configured just through Mason (with the help of mason-nvim-dap). This can be done using either the :DapInstall command or through the Mason UI with :Mason. For details on configuring mason-nvim-dap as well as which debuggers are supported, please check their README and documentation. It provides a function for setting up custom handlers for when a recognizable debugger is installed, this can be configured by extending the config function of the plugin:

return {
  "jay-babu/mason-nvim-dap.nvim",
  opts = {
    handlers = {
      python = function(source_name)
        local dap = require("dap")
        dap.adapters.python = {
          type = "executable",
          command = "/usr/bin/python3",
          args = {
            "-m",
            "debugpy.adapter",
          },
        }

        dap.configurations.python = {
          {
            type = "python",
            request = "launch",
            name = "Launch file",
            program = "${file}", -- This configuration will launch the current file if used.
          },
        }
      end,
    },
  },
}

Automatically Install Debuggers

mason-nvim-dap also allows you to automatically install debuggers that you may want. This can be configured by extending the mason-nvim-dap plugin options:

return {
  "jay-babu/mason-nvim-dap.nvim",
  opts = {
    ensure_installed = { "python" },
  },
}

Setting Up Custom Debuggers

Not all debugging adapters are supported by mason-nvim-dap or to be installed with Mason itself. For these it may be necessary for manually configuring adapters and configurations for dap directly. For details on configuring debuggers manually, please refer to the nvim-dap wiki. Here is an example of configuring nvim-dap directly to add the python debugger:

return {
  "mfussenegger/nvim-dap",
  config = function()
    local dap = require("dap")
    dap.adapters.python = {
      type = "executable",
      command = "path/to/virtualenvs/debugpy/bin/python",
      args = { "-m", "debugpy.adapter" },
    }

    dap.configurations.python = {
      {
        -- The first three options are required by nvim-dap
        type = "python", -- the type here established the link to the adapter definition: `dap.adapters.python`
        request = "launch",
        name = "Launch file",

        -- Options below are for debugpy, see https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings for supported options

        program = "${file}", -- This configuration will launch the current file if used.
        pythonPath = function()
          -- debugpy supports launching an application with a different interpreter then the one used to launch debugpy itself.
          -- The code below looks for a `venv` or `.venv` folder in the current directly and uses the python within.
          -- You could adapt this - to for example use the `VIRTUAL_ENV` environment variable.
          local cwd = vim.fn.getcwd()
          if vim.fn.executable(cwd .. "/venv/bin/python") == 1 then
            return cwd .. "/venv/bin/python"
          elseif vim.fn.executable(cwd .. "/.venv/bin/python") == 1 then
            return cwd .. "/.venv/bin/python"
          else
            return "/usr/bin/python"
          end
        end,
      },
    }
  end,
}

Disabling Auto Debugging UI

By default, AstroNvim sets up event listeners with nvim-dap to automatically open and close the nvim-dap-ui. This can be disabled by overriding the require("dapui").setup({...}) call with the function override method:

return {
  "rcarriga/nvim-dap-ui",
  config = function(plugin, opts)
    -- run default AstroNvim nvim-dap-ui configuration function
    require("astronvim.plugins.configs.nvim-dap-ui")(plugin, opts)

    -- disable dap events that are created
    local dap = require("dap")
    dap.listeners.after.event_initialized.dapui_config = nil
    dap.listeners.before.event_terminated.dapui_config = nil
    dap.listeners.before.event_exited.dapui_config = nil
  end,
}

Add parsing of JSON5

By default nvim-dap will attempt to parse and load .vscode/launch.json files in a project to load debugging targets. By default this uses the built in vim.json.decode function. This function doesn’t support JSON5 which adds compatibility for trailing commas and comments. If you need support for these JSON syntaxes you can add the lua-json5 plugin to your configuration:

return {
  "Joakker/lua-json5",
  lazy = true,
  build = vim.fn.has("win32") == 1 and "powershell ./install.ps1"
    or "./install.sh",
}