Debugging of expl3 code

Question

I've been programming quite a bit in expl3 for the last weeks, and while I really like the expressiveness of the provided API, what often is incredibly painful is debugging larger programs.

In many circumstances, I find the various \xxx_show: functions very useful to query the values of variables and see what's going on at execution. For more readable debugging output \iow_term:x and other I/O functions can be used. l3basics also provides some built-in debugging facilities to check for assignments to undeclared variables, wrong arithmetic expressions and a few other things, which I never felt pretty useful, though.

Sometimes all those do not help anymore when things like expansions go wrong and TeX aborts with an utterly unhelpful low-level error message. In TeX or LaTeX2e using \tracingmacros or \tracingcommands often reveals the problem quickly.

In expl3, however, the tracing output is almost always too verbose to be actually helpful. For example, if I enable macro tracing in the example document from my question about parsing balanced groups only outside of all cctab functions, I get about 7600 lines of log output. If the few cctab function calls are included into the tracing, the log file blows up to 120k lines! Similar things happen for seemingly innocent functions like the \xxx_show: functions. It's no fun to scroll around in hundreds and hundreds of lines of code just to locate one of the functions you actually called in your program.

So are there other tools to aid in debugging of, in particular, expl3 programs/package code? Or is there a way to selectively mute the tracing output for specific sets of functions, e.g. all kernel functions? If not, what plans are there to support more debugging facilities in future expl3 versions?

Answer 1

Too long for a comment, and too vague for an answer; feel free to downvote ;-)

Unfortunately, no. The options you listed are more or less all there's available. One option, which you didn't mention, is to use \traceon/\traceoff from the trace package, which allows you to selectively turn off tracing for uninteresting bits of code (l3msg functions are notoriously log-y, so they are wrapped in \conditionally@traceoff and \conditionally@traceon to work well with trace). So if you are debugging some code and you know for a fact that some part of it is working (say, starting a catcode table), you can do something like this:

% with \usepackage{trace}
\traceon
% some code to be debugged
\conditionally@traceoff
% log-exhaustive code which you are sure it's working
\conditionally@traceon
% more code to be debugged
\traceoff

but then, there's no much improvement on the overall because few functions actually support trace (that I remember: NFSS, calc, xparse, and l3msg).

The kernel could have more occurrences of \conditionally@traceoff and \conditionally@traceon here and there to improve the situation, but this comes at the price of some performance. Another major drawback is that with functions which work with expansion only, you simply can't start or stop tracing.

---

This deficiency of a good debugging tool is unlikely to be solved (at the l3kernel level or else) because the underlying TeX engine provides either no debug or far too many debug, and the information it shows is only (easily) available at the engine level.

Also, slightly different from "usual" languages, what you are debugging impacts on what the debugging tool should look like. If you are debugging some text which is passed around in non-expandable code, usually \showtokens or something like that is really helpful, if you know where to look for the problem. If not, then you're back at \tracingall.

---

When I am trying to debug some code I usually try to isolate the problem to the smallest possible part of the code to get the smallest possible logging. In this process I usually end up removing all code that is not mine (usually I am to blame for the problem), so this shortens the log by a lot. Even within my own parts of the code, I try to pinpoint the problem to a single macro call when possible.

When I can't narrow the problem down anymore I usually use \showtokens on the arguments of a macro or \show in control sequences to inspect their contents. If I'm in an expansion-only context, then I use a trick similar to \msg_expandable_error:nn to make an expandable \showtokens:

\def\eshow#1{\expandafter\@gobble\expandafter{\ERROR <#1>}}

If none of this works, then I go for \traceon plus some regex searching through the log (don't try to debug looking at the logs in the terminal: you'll find yourself hopelessly scrolling up and down and forgetting what you were searching to begin with :-).

Finally, if the problem depends on expansion tricks (mainly if you rely on manipulating the input token stream) then \traceon will also be useless, most of the time, because it doesn't show the token stream at all. In those cases, when all hope is lost, I resort to unravel (I'm not implying it's bad, on the contrary, it's too good, and small pieces of code take thousands of steps to complete). \unravel will usually show you clearly where something went wrong, but it will test your patience first ;-)

---

If nothing else works, stop writing macros and just write some paragraphs of text for a change ;-)