Table of Contents
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.
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.
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.
from [module name] import [registrator name] [registrator name] ( None )Where [module name] and [registrator name] are parameter values entered by the user.
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').
Table of Contents