one-small-step-for-vimkind

one-small-step-for-vimkind a.k.a. osv is an adapter for the Neovim lua language. See the DAP protocol to know more about adapters. It allows you to debug any lua code running in a Neovim instance.

Install

Install using your prefered method.

Plug 'jbyuki/one-small-step-for-vimkind'

" You will also need a comptabile DAP client
Plug 'mfussenegger/nvim-dap'

{
  "mfussenegger/nvim-dap",
  dependencies = {
    "jbyuki/one-small-step-for-vimkind",
  },
  lazy = false,
  config = function()
    -- Put the suggested configuration here
  end,
}

Configuration

Add these lines to work with nvim-dap.

local dap = require"dap"
dap.configurations.lua = { 
  { 
    type = 'nlua', 
    request = 'attach',
    name = "Attach to running Neovim instance",
  }
}

dap.adapters.nlua = function(callback, config)
  callback({ type = 'server', host = config.host or "127.0.0.1", port = config.port or 8086 })
end

Set keybindings to interact with the nvim-dap client.

vim.keymap.set('n', '<leader>db', require"dap".toggle_breakpoint, { noremap = true })
vim.keymap.set('n', '<leader>dc', require"dap".continue, { noremap = true })
vim.keymap.set('n', '<leader>do', require"dap".step_over, { noremap = true })
vim.keymap.set('n', '<leader>di', require"dap".step_into, { noremap = true })

vim.keymap.set('n', '<leader>dl', function() 
  require"osv".launch({port = 8086}) 
end, { noremap = true })

vim.keymap.set('n', '<leader>dw', function()
  local widgets = require"dap.ui.widgets"
  widgets.hover()
end)

vim.keymap.set('n', '<leader>df', function()
  local widgets = require"dap.ui.widgets"
  widgets.centered_float(widgets.frames)
end)

Quickstart

• Launch the server in the debuggee using <leader>dl
• Open another Neovim instance with the source file
• Place breakpoint with <leader>db
• Connect using the DAP client with <leader>dc
• Run your script/plugin in the debuggee

See osv.txt for more detailed instructions.

Debug configuration files

It is now possible to debug configuration files (ex. init.lua). See the corresponding section in osv.txt.

Troubleshoot

flatten.nvim

Set nest_if_no_args to true. See this issue for more informations.

fzf-lua

Under special circumstances, the headless instance can fail. See this issue for more details.

Neovim messages and output

Currently, :redir is used in the debuggee to capture and report debuggee output. This was chosen because it is rarely used in neovim and has relatively few side-effects. However, vim/nvim only allows 1 redirection to be active at a time. If your program relies on this command working correctly, you may need to set output to false, otherwise your redirections will be overridden.

Debugging plugins

Breakpoints are path-sensitive so they should always be set in the executed file even though there might be multiple copies on the system.

This is the case for packer.nvim when developing local plugins. packer.nvim will create a symlink to the plugins files in the nvim-data directory ( it can be located using :echo stdpath('data')). Make sure to set the breakpoints inside the source files in the nvim-data directory and not the local copy. The plugin directory can be found in nvim-data/site/pack/packer/start/YOUR_PLUGIN.

See osv.txt for more detailed instructions.

Dropbox

If you're using a service like Dropbox to share your plugin file, there might be some issue arising with osv. The reason is that the path executed within Neovim and the path opened in dap doesn't match. Consequently, osv has no way to know if the current running script is the same file as the file opened inside the dap client. Try falling back to a local folder to see if this is the cause.

Neovim is waiting for input at startup. Aborting

This appears when the osv's spawned headless neovim instance has an error at startup. Vim will usually wait for an user input but in case of osv, the instance is simply blocked. Resolve any errors that you see at startup. If there are none, the error might be due to the "headlessness". Start using nvim --headless to see if there are any errors.

Breakpoint is not hit

Important : Make sure osv is not running.

1. Start tracing with :lua require"osv".start_trace()
2. Perform the action that should be debugged (for ex. calling a function in your plugin)
3. Stop tracing and display the results with :lua =require"osv".stop_trace() , the = will pretty print the resulting lua table.

Make sure that the path is correct and the breakpoint is set to a line which effectively gets executed.

100% CPU usage when stopped at a breakpoint

Set delay_frozen to 100. See this issue for more informations.

Status

Handlers:

• attach
• scope
• setBreakpoints
• stackTrace
• threads
• variables
• stepIn
• next
• stepOut
• continue
• evaluate
• pause
• terminate
• disconnect
• setVariable
• setFunctionBreakpoints
• setExceptionBreakpoints
• breakpointLocations

Events:

• initialized
• stopped
• terminated
• exited
• output
• exception

Capabilities:

• supportsConditionalBreakpoints
• supportsHitConditionalBreakpoints
• supportsSetVariable
• supportTerminateDebuggee
• supportsExceptionInfoRequest
• supportsExceptionOptions
• supportsConfigurationDoneRequest

Name

it's a debugger for the moon language. - @tjdevries

Plugin architecture

Please refer to ARCHITECTURE.md.

Credits

• mfussenegger/nvim-lua-debugger

Alternatives

• For an adapter limited to expression evaluation, see mfussenegger/nluarepl.

Contribute

See here.