GammaRay™Examine and manipulate the internals of Qt applications at runtime
Examine and manipulate the internals of Qt applications at runtime
GammaRay™ augments conventional debuggers by understanding the implementation of Qt, allowing it to visualize application behavior on a higher level, especially where complex frameworks like scene graphs, model/view or state machines are involved.
About GammaRay
GammaRay is a 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, an 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.
Why GammaRay?
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 you 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 you understand why it’s in a specific place. All relevant item properties are accessible and editable, allowing you to try out changes in-place. An event-tracing and focus-debugging feature supports analysis of 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. A visualization of item geometry, and access to shader code is included too.
State machines are another such example, without a graphical design tool they are extremely cumbersome to deal with. The same, of course, is also 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 of tracing 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.
Custom Builds
If you would like to have a custom plugin for GammaRay to visualize, profile or debug your own specific components or applications, get in touch with us. KDAB engineers have a lot of experience writing GammaRay plugins and can be contracted to help you get yours working and improve your development efficiency.
