---

6.1.15 Pretty-Printers for the GNAT runtime ¶

As discussed in Calling User-Defined Subprograms, GDB’s print command only knows about the physical layout of program data structures and therefore normally displays only low-level dumps, which are often hard to understand.

An example of this is when trying to display the contents of an Ada standard container, such as Ada.Containers.Ordered_Maps.Map:

with Ada.Containers.Ordered_Maps;

procedure PP is
   package Int_To_Nat is
      new Ada.Containers.Ordered_Maps (Integer, Natural);

   Map : Int_To_Nat.Map;
begin
   Map.Insert (1, 10);
   Map.Insert (2, 20);
   Map.Insert (3, 30);

   Map.Clear; --  BREAK HERE
end PP;

When this program is built with debugging information and run under GDB up to the Map.Clear statement, trying to print Map will yield information that is only relevant to the developers of the standard containers:

(gdb) print map
$1 = (
  tree => (
    first => 0x64e010,
    last => 0x64e070,
    root => 0x64e040,
    length => 3,
    tc => (
      busy => 0,
      lock => 0
    )
  )
)

Fortunately, GDB ``has a feature called `pretty-printers <http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty-Printer-Introduction>`_, which allows customizing how ``GDB displays data structures. The GDB shipped with GNAT embeds such pretty-printers for the most common containers in the standard library. To enable them, either run the following command manually under GDB or add it to your .gdbinit file:

python import gnatdbg; gnatdbg.setup()

Once you’ve done this, GDB’s print command will automatically use these pretty-printers when appropriate. Using the previous example:

(gdb) print map
$1 = pp.int_to_nat.map of length 3 = {
  [1] = 10,
  [2] = 20,
  [3] = 30
}

Pretty-printers are invoked each time GDB tries to display a value, including when displaying the arguments of a called subprogram (in GDB’s backtrace command) or when printing the value returned by a function (in GDB’s finish command).

To display a value without involving pretty-printers, you can invoke print with its /r option:

(gdb) print/r map
$1 = (
  tree => (...

You can also obtain finer control of pretty-printers: see GDB’s online documentation¹ for more information.