Debugging the language server in Neovim

[itsfrank]

The Developing page on the wiki has debugging instructions, but they are specific to VSCode. Lua-ls has a large number of users who use neovim and having debugger instructions for neovim might encourage more folks to contribute.

I just went through the process of setting up debugging the lua-ls unit tests and wanted to share the process here. I don't think the content in this issue is ready to add to the developing page, but hopefully is helps someone get set up :)

Setting up debugging for lua-ls with neovim

Requirements

1. Configure neovim for debugging with nvim-dap by installing & setting up the following plugins:
   • nvim-dap (required)
   • nvim-dap-ui (suggested)
2. install local-lua-debugger-vscode somewhere on your file system
   • git clone https://github.com/tomblind/local-lua-debugger-vscode
   • cd local-lua-debugger-vscode
   • npm install
   • npm run build
3. Copy the local-lua-debugger-vscode lldebugger.lua script into the ./script folder
   • cp /path/to/local-lua-debugger-vscode/debugger/lldebugger.lua /path/to/lua-language-server/script
4. Add a call to lldebugger.start somewhere before the line where you want to start debugging from
   • I am debugging the tests, so I added the following to line 1 of test.lua
   • require("lldebugger").start()

Setting up nvim-dap for debugging lua ls

I put all the the code snippets below in the lazy.nvim plugin file for dap-nvim (~/.config/nvim/lua/plugins/dap.lua).

1. Create a debug adapter config for local-lua-debugger-vscode

nvim-dap instructions can be found here

in my config I have:

local local_lua_adapter = {
    type = "executable",
    command = "node",
    args = {
        "/absolute/path/to/local-lua-debugger-vscode/extension/debugAdapter.js",
    },
    enrich_config = function(config, on_config)
        if not config["extensionPath"] then
            local c = vim.deepcopy(config)
            c.extensionPath = "/absolute/path/to/local-lua-debugger-vscode/"
            on_config(c)
        else
            on_config(config)
        end
    end,
}

Then, in your config function for dap-nvim put:

local dap = require("dap")
require("nvim-dap-virtual-text").setup({})

2. Make a function to create a lua-ls debug config

local make_luals_debug_config = function(args)
    local config = {
        name = "Debug LuaLS test",
        type = "lua-local",
        request = "launch",
        program = {
            command = "/absolute/path/to/lua-language-server/bin/lua-language-server",
        },
        args = args,
        cwd = "${workspaceFolder}",
    }
    return config
end

3. Add a way to launch a lua-ls debug session

In my config I create a user command, I have only used it to debug the tests so it looks like this:

vim.api.nvim_create_user_command("LaunchDebuggerLuaLs", function()
    require("dap").run(make_luals_debug_config({"test.lua"}))
end, {})

Debug!

With the above, I can set breakpoints in the test lua files, launch the debugger, and walk through the code, screenshot of my config showing dap-ui after hitting a breakpoint and stepping over a few lines:

[nospam2998]

Why wouldn't the wiki be a suitable place for this? Keeping the information among hundreds of issues not only makes it hard for the intended audience to find it, such misfiled documentation pieces makes it harder for an understaffed team to work on real issues and resolve bugs.