Visualizers

Visualizers (aka "pretty printers" or "auto expanders") is a powerful feature allowing to view contents of complex data structures directly in the Locals window and other debugger windows. GDB has support for such functionality since version 7.0. It is based on Python interpreter built-in into GDB. WinGDB can utilise this mechanism, provided that the Python interpreter is present.

WinGDB comes with a set of predefined visualizer scripts. Some of those sripts are distributed by their authors under the terms of GNU Public License and are a free addition to the WinGDB installer. Currently there are visualizers for libstdc++ V6 STL data structures (string, vector, map, etc.) and some common Qt 4 and boost classes. You can add your own scripts as well.

The simplest usage of visualizers involves using just predefined visualizers. To configure them, choose the "Visualizer manager" option from WinGDB menu. The following dialog will appear:

The dialog has two tabs: Standard and Custom. Standard visualizers are included in the WinGDB installer. Custom visualizers are additional ones supplied by you. More details of the dialog are explained in the subsections below.

Profiles

An important concept is called a visualizer profile. During debugging particular application, you usually want to turn on visualizers for some data structures you use in that application, but not others. Turning on too many visualizers may slow down debugging. Also it's not always desirable to hide details of the structures. Profiles allow you to set which visualizers should be turned on, and which ones should not. Each profile has an unique name.

First of all, you select current profile from the list. Then, you can specify which visualizers to enable or disable in that profile, by clicking check marks next to names of these visualizers. WinGDB will remember your settings for that profile. You can also add new profiles or delete existing ones.

After you configure a profile, you can use it for debugging. The Launch, Attach, Examine Core and WinGDB Properties dialogs all have a "Visualizer profile" setting, where you can enter the name of the profile you want to use. Usually you will select desired name from a list, or a special value "None" to disable visualizers for current session. After selecting the profile you want, start the session as usual. You will see automatically processed structure contents in the Locals window as well as other debugging windows.

Standard visualizers

WinGDB comes with predefined set of visualizer scripts. Most of them however have not been written nor maintained by WinGDB.com. These scripts are publicly available under the terms of the GPL. WinGDB includes them in the install package "as is". Please see the files for respective copyright messages and author information. We can't guarantee that all of the scripts work in all conditions, especially different versions of libstdc++, Qt and boost. These libraries are subject to change, and the changes must be reflected in the scripts. It's up to maintainers of these scripts to do that. We will strive to include updated versions of the scripts in subsequent releases, if possible.

Custom visualizers

Since the visualizers are controlled by the Python interpreter embedded in GDB, you can modify their behaviour by modifying the Python code. However it's not recommended to modify the code of standard visualizers. Instead you can provide your own Python modules and register them on the "Custom" page of the "Visualizer manager" dialog.

To add new module, click "Add visualizer" button. A dialog will appear, prompting you for required information.

There are two parameters to enter: module name and registrator name. The first one is a name of the Python module in which the visualizer is contained. The module name can be nested (usually is) and consists of segments separated by a dot. It coresponds to directory structure of a module. For example, standard module named libstdc++.v6.printers has the following directory structure:

Please see the GDB documentation for detailed description of Python modules implementing visualizers.

The second parameter is a name of the function to call to register the module. This topic is also explained in the GDB docs.

After adding the visualizer, it will be displayed on the list. In the "Source path" column there will be a path to the common directory for custom scripts, where you should copy the files. These files should be contained in their own subdirectory, or even in some deeper subdirectory of it, e.g. when you want to provide several versions of the scripts in different subdirectories (visible as separate modules). Each subdirectory should contain an "__init__.py" file (even without any code), otherwise the Python interpreter won't recognize the directory as a module.

How do visualizers work

WinGDB does not very much for visualizers. Almost everything is done by GDB. WinGDB only transfers files to the remote machine and registers the visualizer. The files are placed in temporary directory (under /tmp/wingdb/visualizers). In order to register, WinGDB issues the following Python commands:

from [module name] import [registrator name]
[registrator name] ( None )

Where [module name] and [registrator name] are parameter values entered by the user.

Summary information for compound objects

Python visualizers work with compound objects by means of returning an iterator for children. In theory they also can provide a summary information string, to be displayed as a value of entire object. It's done by providing 'to_string' method. However, due to a bug in GDB 7.0, it does not work in the machine interpreter mode. GDB always returns a string '{...}' as a value. WinGDB provides a workaround for that. Besides the 'to_string' method, define another method called 'display_hint':

def display_hint(self):
    return "#" + self.to_string()

This is a WinGDB-specific convention. When WinGDB sees a display hint starting with '#' character, it will cut off that character and treat the rest as a forced value to display. The object returning such a value is also treated as a compound object (as if the display hint were 'array').

Pointer expansion helper

GDB provides automatic expansion of pointers. That means, for a meaningful pointer there is a '+' button next to the variable name, and you can look up the pointed object by expanding that node. Unfortunately in GDB 7.0 there is a bug and the visualizers don't work with the expanded node (e.g. if you have a pointer to std::string, you won't see the string value, only internal std::string fields). WinGDB comes with a visualizer script being a workaroud for that problem. To enable it, turn on "pointers.printers" visualizer on the Standard tab.

Autoloaded visualizers

GDB has also a feature allowing to load visualizers automatically. The scripts must reside in one of specific locations on the target machine. Please see the GDB docs for detailed description. WinGDB does not interfere with that process nor have any control over it.

Visualizers support in GDB

To check whether your GDB supports visualizers run below commands:
gdb --interpreter=mi
-list-features

The output should be similar to this one:
^done,features=["frozen-varobjs","pending-breakpoints","python"]

Visualizers are supported only by version which does return "python" among list of features. You need at least GDB 7.0. Sometimes it doesn't have python support enabled, then you can enable it and rebuild GDB on your host machine.

Table of Contents