Skip to content

GammaRay™ Examine and manipulate the internals of Qt applications at runtime

, <span class="entry-title-primary">GammaRay™</span> <span class="entry-subtitle">Examine and manipulate the internals of Qt applications at runtime</span>

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.

gammaray-object-inspector

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.

gammaray-qq2-geometry

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.

gammaray-qsm-debugger-neptune-climate

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.

gammaray-style-inspector

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.

gammaray-widget-inspector

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.

Get GammaRay

GammaRay is available under a GPL licence and can be downloaded from: https://github.com/KDAB/GammaRay/wiki/Getting-GammaRay

GammaRay on Qt Marketplace

Get GammaRay for your commercial projects, with full support…

GammaRay User Manual

Now online – view the GammaRay User Manual…

GammaRay Tutorials

What can GammaRay do for us? This video shows GammaRay in action, introducing the main aspects of its user interface.
To understand the benefits of a tool like GammaRay, we are going to show you how it can be used to fix a problem in a state machine. State machines in Qt can be created with a few lines of code. If there is something wrong, we have to resort to a regular debugger...or we can fire up GammaRay, which is able to reconstruct the state machine graphically and let us reason about it and quickly identify the problem.

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more.  https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/
GammaRay Tutorials (Part 1) - GammaRay Introduction

What can GammaRay do for us? This video shows GammaRay in action, introducing the main aspects of its user interface.
To understand the benefits of a tool like GammaRay, we are going to show you how it can be used to fix a problem in a state machine. State machines in Qt can be created with a few lines of code. If there is something wrong, we have to resort to a regular debugger...or we can fire up GammaRay, which is able to reconstruct the state machine graphically and let us reason about it and quickly identify the problem.

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more. https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/

9 0

YouTube Video UEw2Q0pZbjQwZ042aXR5YmVTSmI1RnZSV094Vlc1UENVWC41NkI0NEY2RDEwNTU3Q0M2

GammaRay Tutorials (Part 1) - GammaRay Introduction

GammaRay™ is distributed in source form; you can freely download it from https://www.kdab.com/development-resources/qt-tools/gammaray/.

Of course, the first thing we need to do is build GammaRay for your system. This is actually very easy to do; just follow the instructions in this video, which shows you how to build GammaRay on Windows.

GammaRay's build instructions are here: https://github.com/KDAB/GammaRay/wiki/Getting-GammaRay.
If you need to cross-compile it, follow the steps documented here: https://github.com/KDAB/GammaRay/wiki/Cross-compiling-GammaRay.

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv.

This video is presented by Milian Wolff, who is a Senior software engineer at KDAB. Milian leads the R&D in tooling and profiling, in which he has a special interest. He created Massif-Visualizer and heaptrack, both of which are now used regularly to improve the performance of C++ and Qt applications. When not applying his knowledge to improving code base performance for KDAB’s customers, Milian maintains QtWebChannel for the Qt Project and is co-maintainer of the KDevelop IDE. In 2015, Milian won KDE’s Akademy Award for his work on Clang integration.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more.  https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/
GammaRay Tutorials (Part 2) - How to set up GammaRay on Windows

GammaRay™ is distributed in source form; you can freely download it from https://www.kdab.com/development-resources/qt-tools/gammaray/.

Of course, the first thing we need to do is build GammaRay for your system. This is actually very easy to do; just follow the instructions in this video, which shows you how to build GammaRay on Windows.

GammaRay's build instructions are here: https://github.com/KDAB/GammaRay/wiki/Getting-GammaRay.
If you need to cross-compile it, follow the steps documented here: https://github.com/KDAB/GammaRay/wiki/Cross-compiling-GammaRay.

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv.

This video is presented by Milian Wolff, who is a Senior software engineer at KDAB. Milian leads the R&D in tooling and profiling, in which he has a special interest. He created Massif-Visualizer and heaptrack, both of which are now used regularly to improve the performance of C++ and Qt applications. When not applying his knowledge to improving code base performance for KDAB’s customers, Milian maintains QtWebChannel for the Qt Project and is co-maintainer of the KDevelop IDE. In 2015, Milian won KDE’s Akademy Award for his work on Clang integration.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more. https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/

7 8

YouTube Video UEw2Q0pZbjQwZ042aXR5YmVTSmI1RnZSV094Vlc1UENVWC4yODlGNEE0NkRGMEEzMEQy

GammaRay Tutorials (Part 2) - How to set up GammaRay on Windows

When facing a problem in a Qt application it is very convenient to be able to quickly launch a debugger and try to understand what is going wrong. 
You can say the same about GammaRay – it is extremely advantageous to have a way to launch it right from within Qt Creator! This short video explains what to do to be able to launch GammaRay with a simple combination of keys.

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more.  https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/
We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/
GammaRay Tutorials (Part 3) - Add Gammaray Shortcut in Qt Creator

When facing a problem in a Qt application it is very convenient to be able to quickly launch a debugger and try to understand what is going wrong.
You can say the same about GammaRay – it is extremely advantageous to have a way to launch it right from within Qt Creator! This short video explains what to do to be able to launch GammaRay with a simple combination of keys.

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more. https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/
We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/

4 1

YouTube Video UEw2Q0pZbjQwZ042aXR5YmVTSmI1RnZSV094Vlc1UENVWC4wMTcyMDhGQUE4NTIzM0Y5

GammaRay Tutorials (Part 3) - Add Gammaray Shortcut in Qt Creator

How does GammaRay inspect a Qt application, exactly? The answer is that there are multiple ways for GammaRay to inject itself in a Qt application. 
It depends on whether or not the application is already running and if the application is local or remote (yes, GammaRay can attach itself to an application running on another system, such as an embedded board or a mobile phone!).

This video explains the differences between the different ways of launching an application under GammaRay.

To know more about the syntax required to do remote debugging, check out the documentation available here: https://docs.kdab.com/gammaray-manual/latest/gammaray-command-line.html

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more.  https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/
GammaRay Tutorials (Part 4) - Launch an Application Under GammaRay

How does GammaRay inspect a Qt application, exactly? The answer is that there are multiple ways for GammaRay to inject itself in a Qt application.
It depends on whether or not the application is already running and if the application is local or remote (yes, GammaRay can attach itself to an application running on another system, such as an embedded board or a mobile phone!).

This video explains the differences between the different ways of launching an application under GammaRay.

To know more about the syntax required to do remote debugging, check out the documentation available here: https://docs.kdab.com/gammaray-manual/latest/gammaray-command-line.html

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more. https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/

4 1

YouTube Video UEw2Q0pZbjQwZ042aXR5YmVTSmI1RnZSV094Vlc1UENVWC41MjE1MkI0OTQ2QzJGNzNG

GammaRay Tutorials (Part 4) - Launch an Application Under GammaRay

One of the most important inspectors available in GammaRay is the Qt Quick Scenes inspector. It allows you to visualize the object tree of a QML scene, the visual positioning of the items, and much more. In this video, we are going to show you how to use GammaRay to solve a practical problem in Qt Quick: why is my element not visible? 

There are many possible reasons, and the non-imperative nature of QML makes it harder than usual to try and debug such a problem. However, GammaRay makes it possible to fix the mistake in a matter of seconds.

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more.  https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/
GammaRay Tutorials (Part 5) - Why isn't my QtQuick Element visible

One of the most important inspectors available in GammaRay is the Qt Quick Scenes inspector. It allows you to visualize the object tree of a QML scene, the visual positioning of the items, and much more. In this video, we are going to show you how to use GammaRay to solve a practical problem in Qt Quick: why is my element not visible?

There are many possible reasons, and the non-imperative nature of QML makes it harder than usual to try and debug such a problem. However, GammaRay makes it possible to fix the mistake in a matter of seconds.

You can freely download GammaRay from here: https://www.kdab.com/development-resources/qt-tools/gammaray/

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more. https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/

0 0

YouTube Video UEw2Q0pZbjQwZ042aXR5YmVTSmI1RnZSV094Vlc1UENVWC4wOTA3OTZBNzVEMTUzOTMy

GammaRay Tutorials (Part 5) - Why isn't my QtQuick Element visible

Let's explore GammaRay's Qt Quick Scenes inspector in more detail. In this video, we are going to explain some of the many tools available when debugging a QML/Qt Quick application, for instance how to visually pick the element we want to get a closer look at or how to visualize pixel metrics.

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more.  https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/
GammaRay Tutorials (Part 6) - GammaRay Quick Scenes Introduction

Let's explore GammaRay's Qt Quick Scenes inspector in more detail. In this video, we are going to explain some of the many tools available when debugging a QML/Qt Quick application, for instance how to visually pick the element we want to get a closer look at or how to visualize pixel metrics.

The example code showcased in this video is available here: https://github.com/KDAB/kdabtv

This video is presented by Giuseppe D'Angelo, who is a Senior Software Engineer at KDAB. He has used Qt for almost two decades, is an active contributor to Qt, and regularly teaches Qt and C++.

About KDAB:
KDAB offers experienced software experts to help you deliver functional, high-performing and innovative software across embedded, mobile and desktop platforms for projects using C++, Qt, QML/Qt Quick, OpenGL, Qt 3D and more. https://www.kdab.com/software-services

KDAB experts regularly take time out to deliver KDAB’s world class training, in-house or at open enrollment courses around the world. We are the market leaders for training in Qt, OpenGL and C++.

Contact us to find out more at training@kdab.com or visit our website: https://www.kdab.com/software-services/scheduled-training/

We are about 90 people, located all around the world. Our Head Office is in Sweden and we have other offices in Germany, France, the UK and the USA. https://www.kdab.com/about/contact/

0 0

YouTube Video UEw2Q0pZbjQwZ042aXR5YmVTSmI1RnZSV094Vlc1UENVWC4xMkVGQjNCMUM1N0RFNEUx

GammaRay Tutorials (Part 6) - GammaRay Quick Scenes Introduction

Mailing lists

KDAB hosts the following mailing lists which are available to anyone interested in GammaRay development.

The lists are: gammaray-interest https://mail.kdab.com/mailman/listinfo/gammaray-interest for anyone who wants to discuss anything related to GammaRay

gammaray-commits https://mail.kdab.com/mailman/listinfo/gammaray-commits for anyone who wants to follow commits into the GammaRay git repository

For tailored support options

Contact us
FacebookTwitterLinkedInEmail