GDB pretty printing support

[aaaaaaaaargh]

Debugging JSON objects with GDB is very tedious and in some cases (e.g. from within CLion) not even possible due to the complexity of the type. I've created a small pretty printer that takes care of this issue by utilising the libraries .dump() method.

I hope some of you may find that useful. Feel free to use this any way you like, including incorporation in the library codebase :)

# Pretty printing support for nlohmann::basic_json objects.

import gdb.printing

class NlohmannJsonPrinter(object):
    "Print a json"
    
    def __init__(self, val):
        self.val = val
        
    def to_string(self):
        eval_string = "(*("+str(self.val.type)+"*)("+str(self.val.address)+")).dump(2, ' ', false, nlohmann::detail::error_handler_t::strict).c_str()"
        result = gdb.parse_and_eval(eval_string)
        
        return result.string()
        
    def display_hint(self):
        return 'JSON'
        
def build_pretty_printer():
    pp = gdb.printing.RegexpCollectionPrettyPrinter(
        "nlohmann::basic_json")
    pp.add_printer('JSON', '^nlohmann::basic_json<.*>$', NlohmannJsonPrinter)
    return pp
 
def register_json_printer():
    gdb.printing.register_pretty_printer(
        gdb.current_objfile(),
        build_pretty_printer())

How to use:

• Save the code in a file somewhere. The exact location isn't that important, I use ~/Dev/.gdb.
• Add the path to your .gdbinit system paths, import and register the printer as usual:

sys.path.append('/home/your/path/to/the-file.gdb')

from nlohmannjson import register_json_printer
register_json_printer()

Have fun!

[abrownsword]

O.M.G., thank you!!!

(btw, I notice that in CLion it seems to include a bolded \n after each would-be line that gets pretty-printed... my python-fu is weak and I don't know how to eliminate the newlines from the Python's output?)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[aaaaaaaaargh]

You are very welcome! :)

[nlohmann]

Hi @aaaaaaaaargh! Sorry for not checking back sooner.

I tried to use the approach you described, but it seems my gdb knowledge is not sufficient.

What I tried:

$ cat ~/.gdbinit 
sys.path.append('/home/vagrant/foo/nlohmann-json.py')

from nlohmannjson import register_json_printer
register_json_printer()

/home/vagrant/foo/nlohmann-json.py is your script above.

Then I run gdb:

$ gdb ./main

GNU gdb (Ubuntu 8.3-0ubuntu1) 8.3
Copyright (C) 2019 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word"...
/home/vagrant/.gdbinit:1: Error in sourced command file:
Undefined command: "sys".  Try "help".
Reading symbols from ./main...
(gdb) run
Starting program: /home/vagrant/foo/main 
terminate called after throwing an instance of 'nlohmann::detail::type_error'
  what():  [json.exception.type_error.305] cannot use operator[] with a string argument with number

Program received signal SIGABRT, Aborted.
__GI_raise (sig=sig@entry=6) at ../sysdeps/unix/sysv/linux/raise.c:50
50	../sysdeps/unix/sysv/linux/raise.c: No such file or directory.
(gdb) print main::j
$1 = {m_type = nlohmann::detail::value_t::number_integer, m_value = {object = 0x1, array = 0x1, string = 0x1, boolean = true, number_integer = 1, 
    number_unsigned = 1, number_float = 4.9406564584124654e-324}}
(gdb) 

Any idea how to make this work?

[aaaaaaaaargh]

Hi Niels,

I think you need to do a couple of things.
First, you should import the 'sys' module. Also, I am not 100% sure about that, but I think you need to import the module directory, not the module itself.

Below is a copypasta of my very own .gdbinit, I hope this will help you get things running :)

$ cat ~/.gdbinit
python 
import sys

# This is where the python file lives
sys.path.append('/home/xyz/foo')

# JSON pretty printing.
from nlohmannjson import register_json_printer
register_json_printer()

[nlohmann]

Thanks for the quick response! I am still struggling though. Is there some kind of beginner's guide?

What I tried:

$ cat ~/.gdbinit 

python
import sys
sys.path.append('/home/vagrant/foo')

from nlohmannjson import register_json_printer
register_json_printer()

$ cat /home/vagrant/foo/nlohmannjson.py

# Pretty printing support for nlohmann::basic_json objects.

import gdb.printing

class NlohmannJsonPrinter(object):
    "Print a json"
    
    def __init__(self, val):
        self.val = val
        
    def to_string(self):
        eval_string = "(*("+str(self.val.type)+"*)("+str(self.val.address)+")).dump(2, ' ', false, nlohmann::detail::error_handler_t::strict).c_str()"
        result = gdb.parse_and_eval(eval_string)
        
        return result.string()
        
    def display_hint(self):
        return 'JSON'
        
def build_pretty_printer():
    pp = gdb.printing.RegexpCollectionPrettyPrinter(
        "nlohmann::basic_json")
    pp.add_printer('JSON', '^nlohmann::basic_json<.*>$', NlohmannJsonPrinter)
    return pp
 
def register_json_printer():
    gdb.printing.register_pretty_printer(
        gdb.current_objfile(),
        build_pretty_printer())

Yet I now get the following error in gdb:

(gdb) print main::j
Python Exception <class 'gdb.error'> No symbol "false" in current context.: 
$1 = 

[aaaaaaaaargh]

Huh.. that looks really strange. Can you please show the main method you use for testing?

I'm afraid as with GDB related things there isn't a ton of documentation about this. I did learn about this by a bit by looking at the Unreal Engine pretty printer and the ones shipped with GCC. But I'm sure we can find a way to solve this.

[aaaaaaaaargh]

Also please let me know what compiler you are using and whether you have any kind of optimization enabled (-O flags in GCC).

[abrownsword]

The only difference I see between your gdbinit and mine (for the pretty printing) is that I also register the stdc++ library pretty printers. Otherwise mine is working fine using gdb 8.2.1 and gcc 8.3 (although I do build those tools locally and there are more than a few available build config options on them).

[nlohmann]

Sure:

main.cpp

#include "json.hpp"

using json = nlohmann::json;

int main()
{
  json j = 1;
  j["foo"] = 2;
}

Compiled with

g++ -g -std=c++11    main.cpp   -o main

g++ (Ubuntu 9.2.1-9ubuntu2) 9.2.1 20191008
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

GNU gdb (Ubuntu 8.3-0ubuntu1) 8.3
Copyright (C) 2019 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.```

[aaaaaaaaargh]

Thank you for sharing so quickly. Luckily this one was not too hard to track down.

The reason this is not working is simply because j is being optimized out in code since it is not being used anywhere. Try putting something after j["foo"]=2; that is actually using j and I'm confident you will see 1 as a result in your debugger. GDB can only inspect variables that are present in the debugging information and the default behaviour of GCC is -O2 i think which already does a bit of optimization. Another approach would be to disable it entirely which is also my preferable choice when it comes to debugging.

For reference, I changed your main.cpp to look like this and it worked:

#include "json.hpp"
#include <iostream>

using json = nlohmann::json;

int main()
{
  json j = 1;
  j["foo"] = 2;
  std::cout << j.dump() << std::endl;
}

[nlohmann]

Same error:

Program received signal SIGABRT, Aborted.
__GI_raise (sig=sig@entry=6) at ../sysdeps/unix/sysv/linux/raise.c:50
50	../sysdeps/unix/sysv/linux/raise.c: No such file or directory.
(gdb) p main::j
Python Exception <class 'gdb.error'> No symbol "false" in current context.: 
$1 = 

[LoneWanderer-GH]

Hi,

I gave a shot to this a while a go on SO, see https://stackoverflow.com/questions/55316620/c-debug-print-custom-type-with-gdb-the-case-of-nlohmann-json-library

I ended up defining a simple gdb macro that calls the dump().
Python or GDB script, both ways are almost identical, both rely on a live inferior process, and were pretty much described in the post. AFAICT It wont work with a core dump as someone pointed out on SO.
I prefer the gdb script, which is much simpler to define and use, considering the current state of this issue python is not that much straightforward as you can see :=)

---

I'm currently working on a 100% python printer, but that is a huge task (coding a RB-tree-stl-map memory explorer in python blindly iterating with gdb tests is just a pain ... and I'm not aware yet if what I do will allow to use a core dump or be better than the dump() call in any way... but since I'm locked at home, I'll play around a bit).

I basically managed to print simple data (i.e. using the Ada-like variant record definition m_type for strings, floats, ints etc.). Nested structures are a bit more tricky for me.

[LoneWanderer-GH]

For what its worth, I finally got something not requiring the call to the dump() method using a python gdb script. See the SO post for details.

There are lots of things that could be improved, but that's a first step.

I did not print the memory addresses of each field, since I focused on the JSON readable stuff, but we can definitly improve prints to include the addresses of the objects (I suspec that it is what #1554 was refereing to)

standalone github repo https://github.com/LoneWanderer-GH/nlohmann-json-gdb

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[aaaaaaaaargh]

Niels, sorry for not answering before, I was pretty busy with other stuff.
I guess @LoneWanderer-GH approach looks far more advanced than the simple one I was taking, so you might be willing to give that a try instead. Otherwise I'd be glad to help where I could.

[ssbssa]

I've made a simple json pretty printer that just reuses the libstdc++ pretty printers for std::string/vector/map (obviously they have to be available in gdb already).

[nlohmann]

@ssbssa Thanks for reporting. I would love to include such a pretty printer in the library, but I always failed to use it, let alone describe how to use it. Could you please add a small step-by-step description how to use the pretty printer when debugging a program with gdb?

[ssbssa]

Simplest way is to source the py file in your .gdbinit file:
source /path/to/nlohmann-json.py

[nlohmann]

@ssbssa Sorry, but I still can't get it to work. I'm using Ubuntu. Here is what I tried:

• Stored https://gist.github.com/ssbssa/60da5339c6e6036b2afce17de06050ea#file-nlohmann-json-py as /home/niels/nlohmann-json.py.
• Added source /home/niels/nlohmann-json.py to ~/.gdbinit (in fact, the file was not there and now only contains this line).
• Wrote a small program like this:

#include "single_include/nlohmann/json.hpp"

int main()
{
    nlohmann::json j;
    j["foo"] = 1;
    std::string s = j["foo"];
}

• Compiled the program with GCC: g++ -O0 -g program.cc -std=c++11
• Start gdb: gdb ./a.out
• Set a breakpoint: break program.cc:7
• Run the program: run
• Tried what you described in https://gist.github.com/ssbssa/60da5339c6e6036b2afce17de06050ea#file-gistfile1-txt: p -pretty on -array on -- j

This is my output:

$1 = {
  m_type = nlohmann::detail::value_t::null,
  m_value = {
    object = 0x0,
    array = 0x0,
    string = 0x0,
    binary = 0x0,
    boolean = false,
    number_integer = 0,
    number_unsigned = 0,
    number_float = 0
  },
  m_parent = 0x0
}

---

$ gdb --version
GNU gdb (Ubuntu 9.2-0ubuntu1~20.04) 9.2
Copyright (C) 2020 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

$ g++ --version
g++ (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

What do I do wrong?

[nlohmann]

Now it works. Maybe I messed up something in between. Thanks so much!

Would it be OK to add the pretty-printer to this repo? It would be MIT licensed, but I would of course mention your name in the README.

[ssbssa]

Yes, that's fine.

[LoneWanderer-GH]

@ssbssa I would be glad if you could provide any feedback concerning my solution.

I tried to make it STL-gdb-scripts independent. It is very different from the merged gist, but since it seems you reused some of the C++ code samples I guess you had a look at it (the "Jean-Baptiste Emmanuel Zorg" part is pretty much my signature, taken from Fifth Element movie :) and in my 2019 stackoverflow post).

And since you seem to be pretty active in the GDB community, I would appreciate any feedback : it was the first time I digged into serious GDB stuff, and had no feedback yet.

[ssbssa]

@LoneWanderer-GH Yes, I used your json example code, since it showed all json types.

As for your pretty printer, since your goal was to make the output look the same as the dump() function, it's doing its job nicely.
The one thing I would change, instead of re-implementing the rather complex vector and map pretty printers, you could reuse the existing ones (like I do, with gdb.default_visualizer()).

[nlohmann]

Should I reopen the issue? Anything left to do here?

[eliasdaler]

I've tried GDB printer from here and it only worked for me when I replaced this line:

if re.search("^nlohmann::basic_json<.*>$", val.type.strip_typedefs().name):

with this:

if re.search("^nlohmann::basic_json<.*>$", str(val.type.strip_typedefs().name)):

Otherwise GDB (9.2) has said this to me:

Python Exception <class 'TypeError'> expected string or bytes-like object

[nlohmann]

@eliasdaler Would you mind opening a PR for that change?

[eliasdaler]

Sure, I'll do it soon.
I'm just wondering if something is wrong with my setup or something in GDB's API changed and it's reproducible for others.

[leha-bot]

I had this error too on Fedora 33, GCC 10.2 (and GDB 10.2)

[jasonabuzzell]

Hi @aaaaaaaaargh! Thank you for posting this code, this makes debugging so much easier than dropping dumps everywhere.

I did want to ask if this works for VSCode, or if I messed something up along the way. For reference, I'm on Windows 10 OS, and I have the gdb environment HOME set to C:\Users\jason, where I put the .gdbinit file. I then appended the path all the way back to my working directory, where I have the python script (I used backslash instead of forward slash for the filepath just for sake of Windows). Unfortunately, in VSCode's gdb debugger, I cannot get the json objects to report anything other than m_value, which contains the addresses of each type.

I would greatly appreciate any guidance on this! In the meantime, I'm going to go back to dropping dumps.

[falbrechtskirchinger]

@jasonabuzzell You can source your .gdbinit file by adding a setupCommand to your launch.json see https://code.visualstudio.com/docs/cpp/launch-json-reference#_setupcommands

Also, reminder to myself: Fix the GDB pretty printer in #3590.

For anyone else finding this thread: Please use the pretty printer from here as the code posted in this thread won't work with 3.11.0+.

[jasonabuzzell]

Thank you for the quick response, @falbrechtskirchinger! This does help clear up a lot. I added "text": "source ${workspaceFolder/.gdbinit" to "setupCommands" in launch.json, and I think it is now finding .gdbinit. If you don't mind me following up, I am seeing this though now, and I think it's not understanding that it's looking at a python file:

C:\Users\jason/.gdbinit:1: Error in sourced command file: Undefined command: "import". Try "help". warning: File "C:\Users\jason\Desktop\Artitalk-2\Artitalk 2\.gdbinit" auto-loading has been declined by your 'auto-load safe-path' set to "$debugdir:$datadir/auto-load".auto-load safe-path' set to "$debugdir:$datadir/auto-load". To enable execution of this file add add-auto-load-safe-path C:\Users\jason\Desktop\Artitalk-2\Artitalk 2\.gdbinit line to your configuration file "C:\Users\jason/.gdbinit". To completely disable this security protection add set auto-load safe-path / line to your configuration file "C:\Users\jason/.gdbinit". For more information about this security protection see the --Type <RET> for more, q to quit, c to continue without paging-- "Auto-loading safe path" section in the GDB manual. E.g., run from the shell: info "(gdb)Auto-loading safe path"

And also this:
(gdb) p -pretty on -array on -- converse No symbol table is loaded. Use the "file" command.
(converse being the name of a json object that does exist at the time of the command).

This may be unrelated, but I did add the execution line add-auto-load-safe-path C:\Users\jason\Desktop\Artitalk-2\Artitalk 2\.gdbinit to the path, and it still ignored it, so I think I still have something setup improperly there.

Also, let me know if I should jump into a different thread for this, thank you!

[falbrechtskirchinger]

You need to source your Python file from .gdbinit.

Check the README of the pretty printer here:
https://github.com/nlohmann/json/tree/develop/tools/gdb_pretty_printer/

[jasonabuzzell]

Ah sorry, I forgot to mention that! I added simply source nlohmann-json.py to .gdbinit, as I assume it's relative, and they are in the same folder. Is that where everything is falling apart?

[falbrechtskirchinger]

Hm. I'm not sure. I'll be working on the pretty printer code soon and will have to set it up in VSCode as well. Maybe I can help you then.

[jasonabuzzell]

Sounds good, no rush! I'll keep an eye on this thread.

[falbrechtskirchinger]

You don't actually need the local .gdbinit unless you don't want to enable pretty printing globally. That way you can avoid having to deal with the auto-loading security features. If you're curious, you can read more about the security restrictions here.

The source command searches the "current directory" first – I don't know if that refers to the current working directory or the directory of the current command file (e.g., .gdbinit).

C:\Users\jason/.gdbinit:1: Error in sourced command file: Undefined command: "import".

This indicates that GDB is not recognizing the sourced file as a Python script or has been built without Python support. The file should have a .py extension and by adding set script-extension strict to your .gdbinit (before the source command) you might get a more definitive error message.

You mentioned you added source nlohmann-json.py to your global .gdbinit, which should work if your GDB has Python support.

I don't know where you get your GDB executable from. I assume it's automatically downloaded by the vscode-cpptools extension? Maybe that doesn't support Python.

[LorenzoBalducci96]

Hello, I've being trying the example but I think for my knowledge i'm missing something.
When I try to start GDB I have this error

GNU gdb (Ubuntu 12.1-0ubuntu1~22.04) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word".
Traceback (most recent call last):
  File "<string>", line 5, in <module>
ModuleNotFoundError: No module named 'nlohmannjson'
/home/user/.gdbinit:8: Error in sourced command file:
Error while executing Python code.

I'm using eclipse for c/c++ for developing and I have just placed the json.hpp file in the source directory of my eclipse project.

[payemo]

Hi. I am using Clion as my main IDE for writing C++. All running configurations are adopted to be working on WSL. So I've added the /home/<user_name>/.gdbinit file with a source command to start the script. When I run one of my tests within Debug mode I can see that gdb actually tries to run the script but I am getting the following error:

Traceback (most recent call last):
  File "/home/<user_name>/scripts/nlohmann-json.py", line 20, in json_lookup_function
    m = ns_pattern.fullmatch(str(val['m_type']))
gdb.error: There is no member or method named m_type.
The target architecture is set to "auto" (currently "i386:x86-64").
Traceback (most recent call last):
  File "/home/<user_name>/scripts/nlohmann-json.py", line 20, in json_lookup_function
    m = ns_pattern.fullmatch(str(val['m_type']))
gdb.error: There is no member or method named m_type.
Traceback (most recent call last):
  File "/home/<user_name>/scripts/nlohmann-json.py", line 20, in json_lookup_function
    m = ns_pattern.fullmatch(str(val['m_type']))

Will be appreaciate to get any idea about that error. If there is need to bring more information just let me know. Thanks :)

[ssbssa]

Hi. I am using Clion as my main IDE for writing C++. All running configurations are adopted to be working on WSL. So I've added the /home/<user_name>/.gdbinit file with a source command to start the script. When I run one of my tests within Debug mode I can see that gdb actually tries to run the script but I am getting the following error:

Traceback (most recent call last):
  File "/home/<user_name>/scripts/nlohmann-json.py", line 20, in json_lookup_function
    m = ns_pattern.fullmatch(str(val['m_type']))
gdb.error: There is no member or method named m_type.
The target architecture is set to "auto" (currently "i386:x86-64").
Traceback (most recent call last):
  File "/home/<user_name>/scripts/nlohmann-json.py", line 20, in json_lookup_function
    m = ns_pattern.fullmatch(str(val['m_type']))
gdb.error: There is no member or method named m_type.
Traceback (most recent call last):
  File "/home/<user_name>/scripts/nlohmann-json.py", line 20, in json_lookup_function
    m = ns_pattern.fullmatch(str(val['m_type']))

Will be appreaciate to get any idea about that error. If there is need to bring more information just let me know. Thanks :)

Looks like this was broken by bbe337c, since it moved both m_type and m_value into m_data.

[payemo]

Thanks for replying. After reviewing your response, I have come to the realization that I do not have enough knowledge to fix the issue myself. Based on your feedback, it seems like the bug is reasonably fixable or at least reportable. Will appreciate any advice on it or at least to create a detailed report of the issue, including any relevant information that may help in resolving it.

[gregmarr]

any relevant information that may help in resolving it.

Replace m_type and m_value with m_data.m_type and m_data.m_value respectively.