Question: Planned debugging support?

[AMSwift73]

We begin with a question often asked in the Nim forum, in reddit r/Nim, and elsewhere: How to debug Nim code?

The poster has usually discovered that
a) they can't see the data they're looking for entirely (non-trivial data type), or
b) the variable is visible but garbled (trivial data type), or
c) it is listed alongside a bunch of low-level things like registers and frames.

What they're expecting - based on their experience with other programming languages - is the unmangled and automatic display of in-scope variables, including that organized in non-trivial data types. Nim, as best as I can tell from reading way too many posts and guides dating back to 2017, is that the Nim toolchain doesn't deliver this, and doesn't plan to deliver this. The Official Answer is "use print-outs".

Additionally, as experienced in post #6 in the thread https://forum.nim-lang.org/t/12704 (warning: post is lengthy), while Nim does provide step-by-step debugging, the way the compiler is implemented means that a debugger tracks destructors, stack winding and unwinding, and other highly granular actions triggered by, but not expressed by, the Nim code itself. This is ... quite a surprise to those expecting a debugger to track code more nearly as it is written.

For both issues, the result is the same: What Nim gives in simplicity of syntax, it too often takes away in complexity of tool usage. What it gives in readable code, it in part takes away in the lack of ability to efficiently debug that code.

So, the question! What are the plans and current state of debugging in Nimskull?

[alaviss]

Nimskull debugging is very similar to Nim at the moment, save for slightly worse procedure names as we don't use C++-style mangling.

There are no concrete plans to improve debugging at the moment. We are mostly focused on improving language stability and performance, so debugging is on the back seat. I do have plans to work on that eventually.

One of the reasons why Nim(skull) debugging story is so bad is due to the fact C is used as an intermediary. All C compilers that we target do not allow for fine grained control over debug information, so there is a hard cap on what we can do. The best that can be done right now is to write debugger plugins to recognize our codegen patterns and internal structures to prettify them.

Eventually we might port Nimskull to a proper code generator (i.e. LLVM), which then would give us full control over debug information and improve it further.

For now, if you need to use a debugger, these flags would help with reducing weird jumps: --debugger:native --stacktrace:off -d:noSignalHandler, as well as recognizing the name of some the internal runtime functions to skip over during debugging.

[AMSwift73]

Many thanks for your informative response. :-)

Re: debugger plugins: I can definitely see that helping to prettify variables, at the very least. A GCC plugin is, in fact, one of the things I've looked for hard in Nim-land, but "those who know how, haven't shared (that I can find), and those who need, don't know how.". Long term, LLVM seems a real step up.

Great tips about debugger flags. I've tested with them and the number of weird jumps has dropped markedly.

[saem]

First off thanks for starting this discussion.

I worked on the nim-gdb.py script (here) quite significantly in the past. I haven't used it in a while though, but it does have tests (here), so it's relatively easy to verify how well it works. I also put up a settings for gdb launch configuration for the vscode plugin (here, it's for debugging nimsuggest, but you should be able to work off it).

If you wanted to contribute to the area let me know, I can layout some concrete tasks with a focus on quick wins.

[AMSwift73]

Gentlemen,

I've decided I Really Want to Make This Work (as well as it can for now). Any info shared with me will be shared with others (and I'm already workshopping how). Saem, Your offer of taking on some concrete tasks is happily accepted.

That said, I do need to set things up on VSCode on WIndows to use gdb and nim-gdb.py like you have. Right now:

1. I have launch.json set up similarly to your nim-compiler.code-workspace. In particular, the gdb "setupCommands" are identical.

2. I have gdb 16.2, compiled with python script support. It is confirmed to function with Nim on VSCode (with the issues noted earlier in this thread).

3. However, I do not know how to get gdb to run nim-gdb.py automatically when called from VSCode. I've tried keeping that file in /tools/debug. I've also tried copying it to /python/gdb, and even putting it in the directory of the program to be debugged.
   In short: I cannot get gdb to show the nim-gdb.py confirmation message "Loading Nim Runtime support." or to noticeably change its behavior (displaying strings, in particular).

May I ask for a how-to?

[saem]

zerbina and saem, With the help of your instructions (modified where something in my setup didn't allow me to use them directly), I have gotten GDB to use nim-gdb.py, emitting the "Loading Nim Runtime support." in the log. (note: for zerbina's post, step #3, use saem's launch.json entry "logging": { "engineLogging": true," } ).

Congrats, that's great progress!

I am not, however, able to get the debugger to recognize a test string. If nim-gdb.py is making a difference, I am not able to see it yet. The string "clue" does not show up in either the automatic display of variables, or when specifically requested.

Can you check T2_ and T3_? Not sure if things are being renamed/mangled/etc and being hidden. Since you got "Loading Nim Runtime support." that means the script did load and is being used -- working is a different matter, for that I would try to get the test to run, it'll tell you if it is at least starting to pretty print correctly.

Question:

1. Regarding what nim-gdb.py can currently do, what should my expectations be? I will then attempt to find a codebase that, when run through the debugger setup, tests these expectations.

You should be able to do the following with the current debugger:

• set breakpoints, and for the most part they should get caught, return can get funky
• you should be able to step and for the most part this should be sequential
• it should pretty print arrays, objects, tuples, strings, sequences, and enums (sometimes)

saem, I was able to understand the first half of your most recent post. I placed "nim-gdb.py" and "nim-gdb.bat" into "nim root directory"/bin. This, as you said, enabled gdb to find nim-gdb.py.

However, I was not able to copy your launch.json, "miDebuggerPath" setting. What eventually worked was to provide the full path to nim-gdb.bat.

My nim-gdb script is on the path, so I don't need to fully qualify it, since you're on windows this should be the batch file and if it's not on the path you should fully qualify it, you did both of those things, so looks good to me.

[AMSwift73]

Checked T2_and T3_. Both are simple types:The first stores the value "2"; the second the value "W" (which is clue[0]). Similar stories for the other garbled variables.

Now, turning to the request to get the tests running:
While I'm still struggling on getting the tests running on the mingw bash command line (among other issues, mingw bash (deliberately) doesn't look at the windows PATH), I was able to, through VS Code, compile the test nim program (gdb_pretty_printer_test_program.nim) and debug it. This yielded extremely promising results:

The hard work already put into nim-gdb.py now clearly shows.

---

I then attempted to get the gdb_pretty_printer_test.py test running, this time using a .bat file instead of the .sh file. Cutting a long, long story short, I think I'm firing both the python scripts, but failing to get the expected output.

bat file contains:

@echo off
for %%i in (nim.exe) do (set NIM_BIN=%%~dp$PATH:i)

for %%i in ("%NIM_BIN%\..\") do (set NIM_ROOT=%%~fi)

set @GDB_PYTHON_MODULE_PATH=%NIM_ROOT%\tools\debug\nim-gdb.py
set @NIM_GDB=gdb.exe

@echo source %@GDB_PYTHON_MODULE_PATH%> wingdbcommand.txt
%@NIM_GDB% --command="wingdbcommand.txt" -x gdb_pretty_printer_test.py --batch-silent --args gdbNew  %*
del wingdbcommand.txt /f /q

EXIT /B %ERRORLEVEL%
@echo on

Messages received from GDB are:

1) expecting: meTwo:  (MyEnum(1)) != expected: (meTwo)

F:\Coding\nim\nim-current\tests\untestable\gdb>nim-gdb-test.bat
Loading Nim Runtime support.
gdb_pretty_printer_test.py:35: SyntaxWarning: invalid escape sequence '\$'
  argRegex = re.compile("^.* = (?:No suitable Nim \$ operator found for type: \w+\s*)*(.*)$")
gdb_pretty_printer_test.py:37: SyntaxWarning: invalid escape sequence '\$'
  noSuitableRegex = re.compile("(No suitable Nim \$ operator found for type: \w+\s*)")
Loading Nim Runtime support.
No suitable Nim $ operator found for type: MyEnum

�[38;5;105m1) expecting: meTwo: �[0m (MyEnum(1)) != expected: (meTwo)

---

At this point, I am minded to focus on what works - debugging the example program via VS Code.

saem, you mentioned some action items. While I've never written a line of Python in my life, I'd love to hear tales of potential quick wins - and try to help make them happen.

[saem]

Checked T2_and T3_. Both are simple types:The first stores the value "2"; the second the value "W" (which is clue[0]). Similar stories for the other garbled variables.

Hmm, maybe things are being optimized out, that does occasionally happen.

Now, turning to the request to get the tests running: While I'm still struggling on getting the tests running on the mingw bash command line (among other issues, mingw bash (deliberately) doesn't look at the windows PATH)

If you update the path to wherever nim is, and as long as nim_gdb is beside it, then you'll probably able to get it to work under mingw bash.

... I was able to, through VS Code, compile the test nim program (gdb_pretty_printer_test_program.nim) and debug it. This yielded extremely promising results
...
The hard work already put into nim-gdb.py now clearly shows.

Hell yeah, those results are promising, that means we're not at square one when it comes to things like arrays and other aggregate structures.

I then attempted to get the gdb_pretty_printer_test.py test running, this time using a .bat file instead of the .sh file. Cutting a long, long story short, I think I'm firing both the python scripts, but failing to get the expected output.

...

I think you've got it working based on a cursory look and the output below, congrats! I think a goal should be adding this gdb stuff to CI, and then including it as part of Windows CI if that's feasible. That way we can make sure things stay working across operating systems.

Messages received from GDB are:

1) expecting: meTwo:  (MyEnum(1)) != expected: (meTwo)

F:\Coding\nim\nim-current\tests\untestable\gdb>nim-gdb-test.bat
Loading Nim Runtime support.
gdb_pretty_printer_test.py:35: SyntaxWarning: invalid escape sequence '\$'
  argRegex = re.compile("^.* = (?:No suitable Nim \$ operator found for type: \w+\s*)*(.*)$")
gdb_pretty_printer_test.py:37: SyntaxWarning: invalid escape sequence '\$'
  noSuitableRegex = re.compile("(No suitable Nim \$ operator found for type: \w+\s*)")
Loading Nim Runtime support.
No suitable Nim $ operator found for type: MyEnum

�[38;5;105m1) expecting: meTwo: �[0m (MyEnum(1)) != expected: (meTwo)

This is actually not the worst news, it's working more than you might think. So meTwo was expected, but we got the enum constructor MyEnum(1), this could be for a few reasons, you'll need to poke at things a bit to determine what's up (manually debug the test program and look in the environment to see what the enum lookup provides).

If you look inside the pretty printing script on line 390 you have the NimEnumPrinter, it's failing to lookup information in the nim type information (nti, I think I got the acronym right) for the enum value's name. It goes to the fallback method see the else condition in the to_string method.

There are two reasons I can think of for this:

1. the lookup logic is no longer current with the way data is arranged (or there is new/different data to lookup elsewhere)
2. sometimes, due to certain optimizations/reasons the enum metadata doesn't get populated for some enums, I forget the exact reason but it was some weird lazy processing/cgen related thing

I'm hoping with a bit of poking around the data is there, you can update the lookup of that information and you'll get that test to pass, because it'll find the enum field name. Don't worry if this feels daunting, it'll get easier with a tiny bit of practice. It's mostly cross referencing things in the generated C source (which are saved to disk), what's in the running environment (vscode let's you play around and query this via the debugger), and then some python/gdb api incantations to get it to do the thing you want.

At this point, I am minded to focus on what works - debugging the example program via VS Code.

This will be key to be able to inspect the test program and look through the environment to see what things are called, what metadata is available, etc. I'm really glad this is working.

saem, you mentioned some action items. While I've never written a line of Python in my life, I'd love to hear tales of potential quick wins - and try to help make them happen.

I've written maybe 100-1000 lines of python in my entire life and the majority of that is in the pretty printers you're looking at, so don't fret, it's pretty easy to pickup enough to get work done.

The first thing I would do is try to get the enum test working, it might be a bit slow in the beginning but it'll get you familiarized with various data lookup and lots of things will be much easier afterwards -- at least that's how my journey began.

Here are some reference links that you'll want if you don't already have, you don't have to consume it all at once, just slowly nibble on them as you poke at things, maybe look through the first one as a whole:

1. a basic tutorial for writing pretty printers with python + gdb: https://developers.redhat.com/blog/2017/11/10/gdb-python-api#
2. api docs for the python mdi interface: https://sourceware.org/gdb/current/onlinedocs/gdb.html/Python-API.html
3. working/tested/documented implementation of pretty printing of boost: https://github.com/ruediger/Boost-Pretty-Printer/tree/master

[saem]

Hi @AMSwift73 just checking in to see how you were doing?

FYI: if you need a more interactive discussion there is also our matrix chat (see the readme)

[AMSwift73]

Hi @AMSwift73 just checking in to see how you were doing?

FYI: if you need a more interactive discussion there is also our matrix chat (see the readme)

Sorry for the delay in responding. A bunch of community work's come up, and I haven't been able to get to hobby coding. May be a while, regretfully.

[zerbina]

Separate from what was discussed already, there is another approach to improve the debugging experience: implementing a simple debugger integration ourselves.

At the core, this isn't overly complex. It boils down to:

1. having the compiler emit calls to the debugger runtime at every relevant statement, expression, routine entry, and routine exit
2. having the compiler emit calls to the debugger runtime when a non-temporary variables comes into or goes out of scope

Every call to a debugger runtime procedure not about variables is associated with source information, such as line/column number, source module, routine name, etc. . Variables would be associated with names and run-time type information.

Both the database holding the aforementioned data and the debugger runtime would be embedded in the to-be-debugged executable itself. The debugger runtime handles external communication (e.g., listening on a socket) and command execution (e.g., step into, step over, show stack-trace, etc.).

Debugger features possible with this approach are:

• breakpoints
• stepping (step in, step out, step over)
• stack-traces
• frame inspection
• and maybe some more that I'm currently not thinking of

[alaviss]

That reminds me of the embedded debugger removed some time ago: nim-lang/Nim#12095

This is the last trace of the rendered docs on the net: https://nim-doc.readthedocs.io/en/latest/endb.html

[AMSwift73]

While I cannot speak to the details, I will say as a potential user that:

1. Any solution that reduces the number of tools and scripts to juggle separately can be a real win for effective usability. Much missing functionality can be forgiven something that Just Works.
2. The two basic things I personally hope for from a debugger is:
   a) the automatic display of unmangled variables local to, or relevant to, the current code block, and
   b) step-by-step debugging, ideally in the steps given by the code itself (by default, anyway).
   (Suppressing things like registers and auto-generated code artifacts would also be nice.)