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 our 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¹, 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 this is done, 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, print can be invoked with its /r option:

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

Finer control of pretty-printers is also possible: see GDB’s online documentation² for more information.