Help with default config for local-lua-debugger-vscode

[cprn]

Hi. I'm trying to make a PR for mason-nvim-dap, so it'd provide a default config for local-lua-debugger-vscode out of the box, but I'm "missing a feature", so to speak.

The mason-nvim-dap addon provides configs for debug adapters installed via Mason - local-lua-debugger-vscode is the only entry in Mason's DAP tab after filtering for Lua. But it requires more than just setting up adapters and configurations entries, and now I'm stuck. For the debugger to attach, the debugged process needs to call require('lldebugger').start(). What's worse, lldebugger is a package within local-lua-debugger-vscode directory, and the debugged process is a separate instance of whatever is interpreting Lua at a time, so that path is unknown in that context. Any idea how to solve that sensibly? I asked the mason-nvim-dap people as well, but I feel it's something that'll require coordination from nvim-dap, or maybe even Mason.

As I said, a config is required, e.g.:

local dap = require('dap')

dap.adapters.llua = {
    type = "executable",
    command = "node",
    args = {
        vim.fn.expand('$MASON/share/local-lua-debugger-vscode/extension/debugAdapter.js')
    }
}

dap.configurations.lua = {
    {
        name = "Local Lua Debugger: Run Love Project",
        type = "llua",
        request = 'launch',
        cwd = "${workspaceFolder}",
        program = { command = "love" },
        args = { "." },
        scriptRoots = { "game" }
    },
}

...but also the project has to require the lldebugger package. I was thinking it could be solved by providing an extra script alongside the default configuration:

-- lldebug.lua

local home = os.getenv("HOME") or os.getenv("USERPROFILE") -- USERPROFILE is used on Windows

local debugger_path
if package.config:sub(1,1) == '\\' then -- Windows
    debugger_path = home .. "\\AppData\\Local\\nvim\\mason\\share\\local-lua-debugger-vscode\\debugger\\?.lua"
else                                    -- Linux
    debugger_path = home .. "/.local/share/nvim/mason/share/local-lua-debugger-vscode/debugger/?.lua"
end

package.path = package.path .. ";" .. debugger_path

if os.getenv("LOCAL_LUA_DEBUGGER_VSCODE") == "1" then
    local ok, lldebugger = pcall(require, "lldebugger")
    if ok and lldebugger and lldebugger.start then
        lldebugger.start()
    end
end

...but even then, the user will have to know to copy that script into their project, and add require('lldebug') at the beginning of their main.lua:

Have a necessity for extra steps like that ever come up before?

[miroshQa]

This works for me:

local dap = require("dap")
dap.adapters["local-lua"] = {
  type = "executable",
  command = "node",
  args = {
    vim.fs.joinpath(vim.fn.stdpath("data"), "mason/share/local-lua-debugger-vscode/extension/debugAdapter.js"),
  },
}

dap.configurations.lua = {
  {
    name = "Launch current file debugging",
    type = 'local-lua',
    request = 'launch',
    cwd = '${workspaceFolder}',
    extensionPath = vim.fs.joinpath(vim.fn.stdpath("data"), "mason/share/local-lua-debugger-vscode/"),
    program = function()
      return {
        lua = "lua",
        file = vim.api.nvim_buf_get_name(0),
      }
    end,
    verbose = true,
    args = {},
  },
}

localluadebug.mp4

relevant:
https://github.com/mfussenegger/nvim-dap/wiki/Debug-Adapter-installation#local-lua-debugger-vscode
https://github.com/tomblind/local-lua-debugger-vscode

[cprn]

TL;DR

It seems extensionPath taking care of the package.path might be enough... kind of? 🤔 In the majority of cases, the user will still need that require('lldebugger').start() call in their project, and they won't know about it after straight-up installing the debugger via Mason. But now at least the big, ugly script isn't needed - thanks for that! ❤️

Whole thing

If it's still unclear - you didn't need the require, because you're starting the script using Lua interpreter. The main purpose of Lua, though, is to be a scripting language for precompiled binaries (like game engines). So normally, that code would be in a context of another process, not evaluated by lua directly. AFAIU, in such case, there's simply no way (without major hacks, like binary patching) for the debugger to inject its hooks into that separate process. That's why in my example I used Love2D, a popular Lua game engine (i.e. dap.configurations.lua.program.command = 'love').

Since the extra file (script) doesn't have to be distributed with the config, though, I've come to think it's okay to leave it to the end-user to find out they need an extra call in their project. If anything, there could be a custom message (from the adapter's config) displayed in Neovim during the 1st debugger run... But I think it's the extent of what's sensible.

My lovely voice

Video explanation to prove I'm not making things up 😆

2025-05-15.14-18-10.mp4

Minimal example

Your proposed config won't start Love2D projects, so if you want to reproduce it, use mine (again, because love, not lua). It either requires love executable in $PATH, or absolute path in dap.configurations.lua.program.command.

File system structure:

test-app # this has to be CWD
└── main.lua

1 directory, 1 file

main.lua:

-- require('lldebugger').start()

function love.draw()
    print('breakpoint here')
    love.graphics.print("Hello World", 300, 200)
end

[miroshQa]

When using the default Lua interpreter as the command, the debug adapter takes care of executing "lldebugger.start()" for you by passing this command using the -e flag. You can even see logs about that in the REPL. (probably you need verbose = true to see it)

You need to figure out how to pass the same to love in a similar way.

[cprn]

Yeah, I know, but when running something else than an interpreter, e.g. when starting a Love2D project, you'd do it like so:

cd test-app
love .

AFAIK, there's no way to pass arbitrary Lua code to the engine. Love itself is written in C++ and only runs the interpreter on main.lua entry point.

Besides, I used Love2D as an example. Even if it had some kind of -e equivalent, there's no guarantee all apps using Lua as scripting language would support the same launch parameter. So a general solution is less and less likely.

[cprn]

I asked in multiple Love2D communities. There's not enough interest to add extra runners, a.k.a. complicate this repo's code. Closing. Have a good one!