Guidelines and HOWTOs/Gammaray

KDAB GammaRay is a GUI app that allows you to inspect a running GUI app that uses Qt widgets or Qt QML. See https://github.com/KDAB/GammaRay and https://www.kdab.com/gammaray.

Some video tutorials are available at https://www.youtube.com/watch?v=gjX8vFlur3g and https://www.youtube.com/watch?v=W6dVfn1nAzI.

Both gammaray and the app that you want to inspect should use the exact same version of Qt. E.g. install both gammaray and the app that you want to inspect from your Linux OS' packages. If you have built Qt using kdesrc-build or if you have installed Qt using the app "Qt online installer", you should build gammaray using kdesrc-build by appending to kdesrc-buildrc file the lines:

module gammaray
    repository https://github.com/KDAB/GammaRay.git
end module

E.g. we have built using kdesrc-build Qt6, kcalc and gammaray. We run in Konsole tab:

kdesrc-build --run kcalc

In another Konsole tab:

source ~/kde/build/kconfig/prefix.sh
gammaray

The window "GammaRay Launcher" is shown. From the "Attach" tab, select "/home/user/kde/usr/bin/kcalc".

At this point, gammaray might fail to connect to the process kcalc and show the error dialog:

Launcher Error
gdb: Yama security extension is blocking runtime attaching, see /proc/sys/kernel/yama/ptrace_scope
lldb: The debugger executable 'lldb' could not be found
Uh-oh, there is no default attach injector on this platform.
See https://github.com/KDAB/GammaRay/wiki/Known-Issues for troubleshooting

As per https://github.com/KDAB/GammaRay/wiki/Known-Issues#gdb-method-fails-to-attach-to-running-process run:

sudo cp /etc/sysctl.d/10-ptrace.conf /etc/sysctl.d/10-ptrace.conf~orig
sudo nano /etc/sysctl.d/10-ptrace.conf

Replace:

kernel.yama.ptrace_scope = 1

with:

kernel.yama.ptrace_scope = 0

Then, reboot your computer.

The window "GammaRay (kcalc)" will be shown. If your application uses Qt widgets, you should start from the main gammaray tab "Widgets". If your application uses Qt QML, you should start from the main gammaray tab "Quick Scenes".

An example Qt widget KDE app is kcalc. An example Qt QML KDE app is kalk.

Inspect a GUI app that uses Qt QML

In gammaray, the top level tab "Quick Scenes" is for inspecting QML and Qt Quick. The top level tab "Models" is for the model objects that are provided to QML objects. "Problems" is for QML warnings such as binding loops or QML objects that are outside of the view.

In "Quick Scenes" in the top of the window the is a combobox that allows you to select the QML window that you want to inspect. E.g. if an application has both a main window and a settings window.

You can right click on a QML object and select "Show in "Quick Scenes" tool", "Show in "Objects" tool", "Show in "Meta Objects" tool", "Show in "Signals" tool".