DOCSEARCHbyAlgolia
Submit Docs

GammaRay Documentation

repository·master·Indexed 23 days ago

https://github.com/kdab/gammaray

A software introspection tool for Qt applications that allows developers to observe and manipulate applications at runtime using high-level Qt concepts. Key capabilities include QObject tree inspection, UI and graphics analysis for QWidget and QtQuick2, model and state machine inspection, and JavaScript debugging for QScriptEngine. The tool supports local workstation use and remote connections to embedded targets, including Android.

Tokens
5K
Snippets
10
Records
27
Agent score
83%

What's inside GammaRay

  1. Overview of GammaRay capabilities

    master

    GammaRay is a software introspection tool for Qt applications that leverages the QObject introspection mechanism to observe and manipulate applications at runtime. It works both locally on a workstation and remotely on embedded targets. It is designed to augment instruction-level debuggers by providing high-level inspection of complex Qt frameworks.

    Key capabilities include:

    • Object Inspection: Browse the QObject tree with live updates, view/edit object properties, and monitor signals/slots (including inbound/outbound connections).
    • UI & Graphics: Provide layout information overlays for QWidget and QtQuick2; inspect QPainter operations, QtQuick2 item trees, scenegraphs, shaders, and geometry data; browse QGraphicsView scenes and item trees.
    • Models & State: Browse QAbstractProxyModel hierarchies and inspect intermediate results; perform visual live inspection of QStateMachines.
    • Web & Scripting: Act as a JavaScript debugger for QScriptEngine; perform HTML/CSS/DOM/JS introspection/editing/profiling on QWebPage via QWebInspector.
    • System & Resources: Browse the QResource tree; show registered meta types, installed fonts, available codecs, and QTimer statistics.
    • Document Inspection: Browse and edit QTextDocument internal structures.

  2. Understand Trace and ResolvedTrace data structures

    master

    Backward-cpp uses a hierarchy of trace objects to manage memory efficiency:

    Trace

    A minimal structure containing only the address and index.

    • addr: The address of the trace.
    • idx: The index (0 is the most recent).

    ResolvedTrace

    Extends Trace with detailed source information. Fields may be empty if debug information is unavailable.

    • object_filename: The binary object containing the trace.
    • object_function: The function in the object (may differ from source function due to inlining).
    • source: A SourceLoc struct containing:
      • function: The source function name.
      • filename: The source filename.
      • line: The source line number.
      • col: The source column.
    • inliners: A std::vector<SourceLoc> containing locations where functions were inlined.

  3. Install Backward-cpp

    master

    Backward is a header-only library for pretty-printing C++ stack traces.

    Header-only usage

    To use the basic functionality, simply include backward.hpp in your project. You can manage this via git submodules or by manually copying the file into your source tree.

    Automatic signal handling

    To enable automatic stack trace printing on fatal errors (such as segfaults, aborts, or unhandled exceptions), you must also add backward.cpp to your project and ensure it is compiled as part of your build system.

    Note for folly users: You must define backward::SignalHandling sh; immediately after calling folly::init(&argc, &argv);.

  4. Integrate Backward-cpp with CMake

    master

    Depending on how you have obtained the library, use one of the following three methods to integrate it with CMake:

    1. As a subdirectory (e.g., via git submodule)

    Use add_subdirectory and the provided add_backward helper function.

    2. Using CMAKE_MODULE_PATH

    If Backward is installed as a subdirectory, add its path to CMAKE_MODULE_PATH and use find_package to create an imported target.

    3. Via a package manager (e.g., conda-forge)

    Use find_package to link against the Backward::Backward imported target.

    ### As a subdirectory
```cmake
add_subdirectory(/path/to/backward-cpp)
add_executable(mytarget mysource.cpp ${BACKWARD_ENABLE})
add_backward(mytarget)

    Modifying CMAKE_MODULE_PATH

    list(APPEND CMAKE_MODULE_PATH /path/to/backward-cpp)
find_package(Backward)
target_link_libraries(mytarget PUBLIC Backward::Backward)

    Through a regular package manager

    find_package(Backward)
target_link_libraries(mytarget PUBLIC Backward::Backward)

  5. Build GammaRay from source

    master

    To build GammaRay, ensure cmake, ninja, your compiler, and Qt are in your PATH. Use the following standard workflow to create a build directory, configure with CMake, and install. You can specify a custom installation directory using -DCMAKE_INSTALL_PREFIX.

        mkdir build && cd build/
    cmake -G Ninja -DCMAKE_INSTALL_PREFIX=/path/where/to/install ..
    cmake --build .
    cmake --build . --target install

  6. Specify a specific Qt version for building

    master

    By default, GammaRay uses the system's Qt installation. To build against a specific Qt version, use the CMAKE_PREFIX_PATH CMake option pointing to your Qt installation folder.

        # Linux/macOS example
    cmake -DCMAKE_PREFIX_PATH=$HOME/Qt/6.6.0/gcc_64 ..

    # Windows example
    set CMAKE_PREFIX_PATH=c:\Qt\6.6.0\msvc2019_64
    cmake...

  7. Force a probe-only build

    master

    If you have an existing GammaRay installation and want to support a new Qt version, you can build only the GammaRay probe instead of the entire suite. This is faster and allows you to install the new probe into your existing prefix.

        cmake \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_PREFIX_PATH=/path/to/Qt/version/ \
        -DGAMMARAY_PROBE_ONLY_BUILD=true \
        -DGAMMARAY_BUILD_UI=false  \
        -DCMAKE_INSTALL_PREFIX=/path/to/your/previous/gammaray/prefix \
        /path/to/gammaray/sources

  9. Build GammaRay for Android

    master

    To build GammaRay for Android, use the Android NDK toolchain file. You must provide the path to your NDK and the installation path of your Qt for Android.

    Using GammaRay on Android

    1. Add the GammaRayProbe to your Android .pro file:
    myproject.pro
....
android: QT += GammaRayProbe
...
    1. Build and deploy your project.
    2. Forward the GammaRay socket using adb:
    # Forward the socket from the device to your local machine
adb forward tcp:11732 localfilesystem:/data/data/YOUR_ANDROID_PACKAGE_NAME/files/+gammaray_socket

    1. Run the GammaRay GUI and connect to localhost:11732.

    2. Clean up the forward when finished:

    # Remove a specific forward
adb forward --remove tcp:11732

# Or remove all forwards
adb forward --remove-all
        mkdir android-build
    cd android-build
    export ANDROID_NDK=/path/to/android-ndk
    cmake -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
          -DCMAKE_FIND_ROOT_PATH=/android/qt6/install/path \
          -DCMAKE_INSTALL_PREFIX=/install/path ..
    make [-j CPU_NUMBER+2]
    make install

  10. GammaRay Build Requirements

    master

    To build GammaRay, ensure your environment meets these minimum requirements:

    • CMake: 3.16.0 or higher
    • Compiler: C++ compiler with C++17 support
    • Qt: 6.5 or higher (Note: GammaRay v3.2.0 was the last version to support Qt < 6.5)

    Important: Qt Private Headers GammaRay requires Qt private headers. If you are using a distribution-provided Qt, you must install the corresponding private development packages:

    DistributionRequired Packages
    Redhat/Fedoraqt6-qtbase-private-devel
    Debian/Ubuntuqt6-base-private-dev, qt6-declarative-private-dev, qt6-documentation-tools
    SUSElibqt6-qtbase-private-headers-devel, libqt6-qtdeclarative-private-headers-devel

  12. Configure RPATH settings (Linux only)

    master

    By default, GammaRay uses absolute RPATHs for its dependencies. For creating installers or system packages, you may want to adjust this using these CMake options:

    • CMAKE_INSTALL_RPATH_USE_LINK_PATH=OFF: Disables setting RPATH to the location of dependencies, but maintains relative RPATHs between GammaRay components. Recommended for Linux distributions.
    • CMAKE_INSTALL_RPATH=<path(s)>: Adds specific absolute paths to the RPATH in addition to the relative paths between GammaRay components.