GammaRay is a tool for examining and manipulating the internals of a Qt application at runtime. GammaRay augments conventional debuggers by understanding the implementation of Qt, allowing it to visualize application behavior on a higher level, especially with complex frameworks like scene graphs, model/view or state machines being involved.
GammaRay is a free software introspection tool for Qt applications developed by KDAB. Leveraging the QObject introspection mechanism it allows you to observe and manipulate your application at runtime. This works both locally on your workstation and remotely on an embedded target.
Augmenting your instruction-level debugger, GammaRay allows you to work on a much higher level, with the same concepts as the frameworks you use. This is especially useful for the more complex Qt frameworks such as model/view, state machines or scene graphs.
When trying to analyze bugs in your application, a instruction-level debugger is usually your first tool of choice, and rightfully so. Debuggers allow you to follow the program flow and allow you to inspect the state of objects or variables. When using a debugger with proper Qt integration, such as in QtCreator, it will also handle Qt’s own data types correctly. However, when dealing with complex frameworks this level of detail is often too low-level. Keeping an overview in a large scene graph or following the complex interactions between models and views can quickly become a cumbersome task this way.
GammaRay addresses this by providing domain-specific debugging aids on a much higher level. It provides easy ways of navigating through the complex internal structures you find in some Qt frameworks, such as the QtQuick scene graphs, model/view, QTextDocument, state machines and more. Unlike the debugger, GammaRay understands those internal structures and can present them in a meaningful way, making it a tool that should not be missing in any Qt developer’s toolbox.
GammaRay is available for all major platforms and can inspect applications right from the start or attach to an already running one at runtime. It also supports remote debugging, which is especially valuable when working on embedded systems.
There are several other QObject introspection tools available, and of course the usual browsing of object properties, signals, slots and connections is also available in GammaRay, just like in-line displaying of widget boundaries and layouts. However, its real strength comes into play when looking at some of the more complex frameworks provided by Qt.
This is most apparent when working with highly visual frameworks, such as QtQuick2. GammarRay helps you to keep an overview by allowing to browse the QtQuick item tree. In-app item picking allows quick navigation to an item of interest, and a dedicated layout overlay view helps understanding why it’s in a specific place. All relevant item properties are accessible and editable, allowing you to try out changes in-place. A event tracing and focus debugging feature support analyzing key event handling issues. For more advanced cases, GammaRay also provides a view on the internal QtQuick2 scene graph, which is especially useful when working on custom items. It also includes a visualization of item geometry, and access to shader code.
State machines are another such example, without a graphical design tool they are extremely cumbersome to deal with. The same of course also is true at runtime, while debugging generated state machine code. Therefore GammaRay is able to visualize a QStateMachine in an UML-like fashion, and show you the state it’s currently in live. It’s also capable to trace all transitions of the state machine, supporting you in analyzing misbehavior.
Despite the introduction of QtQuick, QPainter-based technologies such as QtWidgets or QGraphicsView will still be relevant in many fields for years to come, and GammaRay provides a wide range of tools to support work with those frameworks. These include layout overlays for QtWidgets, a browser for all QStyle primitives and a scene graph view for QGraphicsView. For more advanced problems, it’s also possible to break down rendering and individually step through all QPainter operations.
The Qt model/view framework is another system that benefits immensely from a domain-specific debugging tool. GammaRay allows you to browse the content of any QAbstractItemModel found in your application, no matter if it’s visible in any view or not. It can also display the hierarchy of proxy models as well as any intermediate result in a proxy model chain. Finally, it also allows you to inspect all selection models that are in use on top of any of your models.
That’s not the end though, GammaRay comes with a document object model browser for QTextDocument, an integrated debugger for QtScript and QtWebKit, a Qt resource browser and many more. In total there are over 20 different tools shipped with GammaRay today. And if that doesn’t cover your specific needs, GammaRay is available in source code and is designed to be extendable by plug-ins for adding even more domain-specific debugging aids, be it for another framework provided by Qt, a component from another vendor or your own classes.
KDAB hosts the following mailing lists which are available to anyone interested in GammaRay development.
The lists are:
for anyone who wants to discuss anything related to GammaRay
for anyone who wants to follow commits into the GammaRay git repository