Is there a way to step through LuaLaTeX macros using a remote debugger?

Question

Writing LaTeX macros has always been difficult, and it seems like writing a major package can only be accomplished by a Real Programmer.

Fortunately, LuaTeX is on its way, and writing Lua macros is arguably more human-friendly than programming in TeX. Still, it could get even friendlier if there was a way to couple LuaTeX with a remote debugger.

Therefore I ask: Is there a way to remotely debug LuaLaTeX macros?

This question is essentially a rewording of the post Debugging Lua in LuaLatex with LDT. The post was closed since it didn't really contain a question. An almost-complete solution was proposed in the post, but there were some issues, and I would like to know if these issues can be resolved.

Answer 1

Nowadays, you can get GUI debugging of Lua code right in the middle of LuaTeX processing of your document. With breakpoints, watch variables, stepping through the code, call stack, and even showing tooltips with variable content on mouse hover.

My environment for working with TeX is VS Code + LaTeX Workshop + LTeX. It's quite convenient: I can write and debug a C++ program and, in the same window, write a paper that describes it. LaTeX Workshop has so many features that anything like TeXstudio feels unnecessary.

You also can edit your TeX document and debug its Lua in the same environment of VS Code. To support and debug Lua inside your document, you need two extensions: Lua and Local Lua Debugger.

To debug, insert the following in your preamble:

\begin{luacode}
    require("lldebugger").start()
\end{luacode}

Then create the following launch configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Custom Lua Environment",
            "type": "lua-local",
            "request": "launch",
            "stopOnEntry": false,
            "program": {
                "command": "lualatex"
            },
            "args": ["mwe.tex"]
        }
    ]
}

Where mwe.tex above is the name of your document. That's it. You are ready to debug, just press F5. The only drawback so far is that it cannot place a breakpoint inside a .tex document; it has to be a Lua file.

Here is a screenshot of a debug session:

Answer 2

One simple, lightweight alternative is the command-line interface debugger debugger.lua by Scott Lembcke. This is not a remote debugging solution, but it is very easy to set up. On the downside, there is no GUI, so everything is done through the terminal. But it's way better than issuing print commands, which is probably the approach used by most LuaLaTeX package writers to date.

To get started:

1. Download debugger.lua and place it in your project folder.
2. Place the command local dbg = require("debugger") at the start of the .lua file you want to debug.
3. Place the command dbg() at places in your code where you want code execution to break.
4. Use terminal commands to inspect variables, execute custom code and more. Issue the command h to get a simple summary of available commands.