8

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.

Community
  • 1
akvilas
  • 988
  • 6
  • 11
  • Could you explain 'remote' debugging for those of us without a formal programming background? – Joseph Wright Feb 23 '16 at 19:29
  • Basically, I want to write my macro in a file macro.lua, using a text editor with debugging capabilities (such as Emacs or Eclipse). When I compile the .tex document, I want LuaTeX to pass the control over to Emacs/Eclipse, where I can step through the macro line by line, examining (and possibly alter) the contents of macro variables as the program progresses. – akvilas Feb 23 '16 at 19:49
  • Lua's not a macro language (TeX is!): I don't follow. – Joseph Wright Feb 23 '16 at 19:58
  • 1
    @JosephWright debuggers let you single step through compiled languages like C or Fortran so could in principle do the same in lua. – David Carlisle Feb 23 '16 at 20:17
  • 2
    Basically can you access something like this from luatex: http://lua-users.org/wiki/DebuggingLuaCode – David Carlisle Feb 23 '16 at 20:20
  • 1
    I usually do printf debugging in combination with viz-nodelist (when appropriate, see for an example output http://tex.stackexchange.com/a/107398/243). My printf debug functions are here: https://github.com/speedata/publisher/blob/develop/src/lua/common/sd-debug.lua, especially w() and printtable(). – topskip Feb 23 '16 at 20:46

2 Answers2

4

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:

enter image description here

facetus
  • 837
  • 1
    Many thanks for the very helpful answer! I have one question though: Is is true that "mwe.tex" in "args": ["mwe.tex"] is the name of the lualatex file? If yes, then I suggest that you write that fact in your answer as initially this made it hard for me to follow your solution. – krfl Oct 10 '23 at 19:01
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.
akvilas
  • 988
  • 6
  • 11
  • If someone can give me a simple-to-set-up GUI debugging solution, I'll accept that anwer instead of my own... – akvilas Feb 24 '16 at 07:45