Getting Started Basic Operations

Contents

Installation

Overview

GammaRay consists of two parts, the client and the probe. The client is the graphical user interface you are going to interact with. The probe interacts very closely with the Qt application it analyzes, using a number of internal APIs of Qt. This makes it necessary that the probe is built for exactly your Qt.

All of the following affect the compatibility of the GammaRay probe with the target application:

  • Qt version
  • Qt configuration
  • system architecture (most prominently 32bit vs 64bit)
  • compiler vendor (particularly on Windows)
  • compiler settings (particularly debug or release mode, on Windows)

This tight coupling to Qt makes it unfortunately somewhat difficult to provide pre-compiled binaries for the GammaRay probe in all cases, the following instructions therefore also cover how to build GammaRay from source code, should no pre-built probe be available for your configuration.

Local Development

Pre-built packages

Pre-built GammaRay packages are available for the following systems:

  • Qt Automotive Suite contains everything needed as part of the standard SDK already.
  • For some Linux distributions KDAB provides packages via the Open Build Service here.

Build recipes

Build recipes for the following source-based software distribution systems are available:

Building manually

You can obtain the source code of GammaRay on Github. To build it you need the following requirements:

  • Qt 5.15 or newer
  • CMake 3.4 or newer
  • a C++11 compatible compiler

GammaRay is built using the normal CMake build process, you can find more information in the INSTALL.md file in the GammaRay source tree.

Embedded Targets

The Qt Automotive Suite contains pre-built GammaRay probes are included in the device images.

For the following source-based embedded Linux distributions, there are example build recipes included below. Note that these likely need to be adjusted for your specific setup.

  • Yocto
  • Buildroot

In all other cases, including non-Linux target systems, refer to the cross-compilation instructions below.

Yocto

A Yocto recipe for Qt Automotive Suite is available as part of the meta-boot2qt Yocto layer here. See the example below on how to customize this to your needs.

Example gammaray_git.bb:

SUMMARY = "GammaRay Qt introspection probe"
HOMEPAGE = "https://www.kdab.com/gammaray"

LICENSE = "GPL-2.0-or-later"
LIC_FILES_CHKSUM = "file://LICENSES/GPL-2.0-or-later.txt;md5=3d26203303a722dedc6bf909d95ba815"

inherit cmake_qt5

SRC_URI = "git://github.com/KDAB/GammaRay;branch=master"

SRCREV = "1728dff87163c370fa6903a6d739d1a132b4c62f"
PV = "2.7.0+git${SRCPV}"

DEPENDS = "qtdeclarative"

S = "${WORKDIR}/git"

EXTRA_OECMAKE += " -DGAMMARAY_BUILD_UI=OFF"

FILES_${PN}-dev += " \
    /usr/lib/cmake/* \
    /usr/mkspecs/modules/* \
"
FILES_${PN}-dbg += " \
    /usr/lib/.debug/* \
    /usr/lib/gammaray/*/*/.debug \
    /usr/lib/gammaray/*/*/styles/.debug \
"

The lines you probably want to adjust are:

  • SRCREV: to use newer versions
  • DEPENDS: to select the Qt modules you are using, in order to enable all relevant GammaRay features

Buildroot

Example Config.in:

config BR2_PACKAGE_GAMMARAY
        bool "gammaray"
        depends on BR2_PACKAGE_QT5
        help
        GammaRay Qt introspection probe.

Example gammaray.mk:

GAMMARAY_VERSION = 1728dff87163c370fa6903a6d739d1a132b4c62f
GAMMARAY_SITE = git://github.com/KDAB/GammaRay.git
GAMMARAY_INSTALL_STAGING = NO
GAMMARAY_INSTALL_TARGET = YES
GAMMARAY_LICENSE = GPLv2
GAMMARAY_LICENSE_FILES = LICENSE
GAMMARAY_DEPENDENCIES = qt5base

GAMMARAY_CONF_OPTS += -DGAMMARAY_BUILD_UI=OFF

$(eval $(cmake-package))

The lines you probably want to adjust are:

  • GAMMARAY_VERSION: to use newer versions
  • GAMMARAY_DEPENDENCIES: to select the Qt modules you are using, in order to enable all relevant GammaRay features

Manual cross-compilation

GammaRay can be cross-compiled using the normal cross-compilation mechanism of CMake, ie. passing CMake a toolchain file. The GammaRay source code contains a number of example toolchain files for Linux (generic Yocto, RaspberryPI, iMX6), QNX (6.5, 6.6, 7.0) and Android you can use or adjust.

The toolchain file is passed to CMake using the -DCMAKE_TOOLCHAIN_FILE command line option. Note that this only works on the very first CMake run, CMake doesn't like changing the toolchain file on an existing build directory. In that case, make sure to wipe the entire build directory first (just deleting CMakeCache.txt is not enough!).

Additionally you might need to pass one or more -DCMAKE_PREFIX_PATH=... command line options to point CMake to the location your sysroot has Qt (or any other dependency) installed in, just as during desktop builds.

A default build of GammaRay includes both the client and the probe, for cross-compiling you normally only want the probe, which can be achieved by setting the CMake option GAMMARAY_BUILD_UI to off.

Here's an example CMake invocation for building for RaspberryPI:

export SYSROOT=/where/your/rpi/sysroot/is/located
export PATH=<toolchain>:$PATH

cd <builddir>
cmake -DCMAKE_TOOLCHAIN_FILE=<srcdir>/cmake/Toolchain-RPI.cmake  -DCMAKE_PREFIX_PATH=$SYSROOT/usr/local/Qt-5.15.1 -DCMAKE_INSTALL_PREFIX=$SYSROOT/usr/ -DGAMMARAY_BUILD_UI=OFF

Getting Started Basic Operations