Skip to content

Latest commit

 

History

History
295 lines (236 loc) · 12.5 KB

HACKING.md

File metadata and controls

295 lines (236 loc) · 12.5 KB
Raw

Developing Hotspot - the Linux perf GUI for performance analysis

Table of Contents

Building Hotspot

Building hotspot from source gives you the latest and greatest, but you'll have to make sure all its dependencies are available. Most users should probably install hotspot from the distro package manager or as an AppImage.

Required Dependencies

As of now, you will need the following dependencies to build this project:

  • CMake 3.1.0 or higher
  • any C++11 enabled compiler
  • Qt 5.15.0 or higher
  • libelf
  • libelfutils
  • gettext
  • extra-cmake-modules
  • KDE Frameworks 5 (packages are usually called libkf5-*-devel):
    • threadweaver
    • i18n
    • configwidgets
    • coreaddons
    • itemviews
    • itemmodels
    • kio
    • solid
    • windowsystem
    • notifications
    • iconthemes
    • parts
    • archive (optional)
  • KDDockWidgets
    • this library is not yet packaged on most distributions, you'll have to compile it yourself from source

On Debian/Ubuntu

add-apt-repository ppa:kubuntu-ppa/backports
apt-get update
apt-get install libkf5threadweaver-dev libkf5i18n-dev libkf5configwidgets-dev libkf5syntaxhighlighting-dev \
    libkf5coreaddons-dev libkf5itemviews-dev libkf5itemmodels-dev libkf5kio-dev libkf5parts-dev \
    libkf5solid-dev libkf5windowsystem-dev libkf5notifications-dev libkf5iconthemes-dev libelf-dev \
    libdw-dev cmake extra-cmake-modules gettext libqt5svg5-dev

Note: Ubuntu 20.04 does not provide the minimal version of QT, if you use this old Ubuntu version then you'd need to additionally install it from a version outside of the distro repository. The automatic builds via GitHub actions use the following for that:

    sudo add-apt-repository ppa:beineri/opt-qt-5.15.4-focal
    sudo apt-get update
    sudo apt-get install -y qt515base qt515svg qt515x11extras \
        libqt5x11extras5-dev   # this one is optional for Hotspot, but required for KDDockWidgets

On Fedora

dnf install cmake gcc glibc-static gcc-c++ libstdc++-static qt5-qtbase qt5-qtbase-devel qt5-qtsvg-devel \
    extra-cmake-modules elfutils-devel kf5-threadweaver-devel \
    kf5-kconfigwidgets-devel kf5-kitemviews-devel kf5-kitemmodels-devel kf5-syntax-highlighting-devel \
    kf5-kio-devel kf5-solid-devel kf5-kwindowsystem-devel kf5-kiconthemes-devel \
    kf5-knotifications-devel kf5-kparts-devel

Arch Linux

pacman -Syu
pacman -S cmake gcc extra-cmake-modules threadweaver kconfigwidgets knotifications syntax-highlighting \
    kiconthemes kitemviews kitemmodels kwindowsystem kio kparts solid libelf gettext qt5-base

OpenSUSE

zypper in cmake gcc-c++ extra-cmake-modules threadweaver-devel kio-devel \
    solid-devel kcoreaddons-devel threadweaver-devel kconfigwidgets-devel \
    kitemmodels-devel kitemviews-devel kwindowsystem-devel kparts-devel syntax-highlighting-devel \
    libqt5-qtbase-devel libqt5-qtsvg-devel libelf-devel libdw-devel gettext glibc-devel-static \
    knotifications-devel kiconthemes-devel libzstd-devel binutils

Building Hotspot itself

git clone --recurse-submodules https://github.com/KDAB/hotspot.git
mkdir build-hotspot
cd build-hotspot
cmake ../hotspot
make
# now you can run hotspot from the build folder:
./bin/hotspot
# or `make install` it and launch it from your $PATH

If you need help building this project for your platform, contact us for help.

Online

Instead of installing all dependencies and building Hotspot locally you may do so online with the following link: Open in Gitpod This environment uses a clean, pre-configured Ubuntu 22.04 LTS environment. Just open, possibly have a look at the multiple building tasks, wait a bit until building is finished which is done as soon as a hotspot window opens in the preview and you can start coding / debugging hotspot.

Notes:

  • This Gitpod setup is maintained by @GitMensch and not used by @KDAB directly.
  • Building may take a while as we don't use pre-builts or a special docker container in this environment yet.

Debugging the AppImage

When the AppImage crashes or is excessively slow, please provide a usable backtrace or profile run.

If you're building Hotspot yourself you have the debugging symbols availalbe, when using a distro version you can check with your distribution documentation how to install the debug symbols.

But debugging is also possible when using the AppImage using debuginfod or manual symbol loading.

To do that, you will need to download the debuginfo artifact that matches the AppImage you downloaded.

AppImage-Debugging using manual symbol loading

For using this approach you need to first unpack the debug information downloaded from the release:

$ tar -xvf hotspot-debuginfo-*.tar.bz2
hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot
hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/lib64/libexec/hotspot-perfparser

Starting the debugger is possible directly with executing the AppImage as follows:

$ ./hotspot-v1.2.3-45-g02fd82c-x86_64.AppImage &
$ gdb -q -p $(pidof hotspot) -ex "add-symbol-file hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot"
Attaching to process 123456

with a GDB session of

Reading symbols from /tmp/.mount_hotspoBCRbef/squashfs-root/usr/bin/hotspot...

(No debugging symbols found in /tmp/.mount_hotspoBCRbef/squashfs-root/usr/bin/hotspot)
Reading symbols from /tmp/.mount_hotspoBCRbef/squashfs-root/usr/bin/../lib/libKF5ThreadWeaver.so.5...
(No debugging symbols found in /tmp/.mount_hotspoBCRbef/squashfs-root/usr/bin/../lib/libKF5ThreadWeaver.so.5)
...
0x00007fea98ae0a38 in poll () from /usr/lib64/libc.so.6
add symbol table from file "hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot"
(y or n) y
Reading symbols from hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot...
(gdb) bt
#0  0x00007ff72544ca38 in poll () from /usr/lib64/libc.so.6
#1  0x00007ff7246777d7 in _xcb_in_read_block () from /usr/lib64/libxcb.so.1
#2  0x00007ff7246754e9 in xcb_connect_to_fd () from /usr/lib64/libxcb.so.1
#3  0x00007ff72467943c in xcb_connect_to_display_with_auth_info () from /usr/lib64/libxcb.so.1
#4  0x00007ff7283a95ea in _XConnectXCB () from /usr/lib64/libX11.so.6
#5  0x00007ff728399d89 in XOpenDisplay () from /usr/lib64/libX11.so.6
#6  0x00007ff70f181527 in QXcbBasicConnection::QXcbBasicConnection(char const*) () from /tmp/squashfs-root/usr/plugins/platforms/../../lib/libQt5XcbQpa.so.5
#7  0x00007ff70f15b072 in QXcbConnection::QXcbConnection(QXcbNativeInterface*, bool, unsigned int, char const*) ()
   from /tmp/squashfs-root/usr/plugins/platforms/../../lib/libQt5XcbQpa.so.5
#8  0x00007ff70f15e588 in QXcbIntegration::QXcbIntegration(QStringList const&, int&, char**) ()
   from /tmp/squashfs-root/usr/plugins/platforms/../../lib/libQt5XcbQpa.so.5
#9  0x00007ff7286ad41f in ?? () from /tmp/squashfs-root/usr/plugins/platforms/libqxcb.so
#10 0x00007ff7267686cf in QGuiApplicationPrivate::createPlatformIntegration() () from /tmp/squashfs-root/usr/bin/../lib/libQt5Gui.so.5
#11 0x00007ff726769c40 in QGuiApplicationPrivate::createEventDispatcher() () from /tmp/squashfs-root/usr/bin/../lib/libQt5Gui.so.5
#12 0x00007ff72630c0d7 in QCoreApplicationPrivate::init() () from /tmp/squashfs-root/usr/bin/../lib/libQt5Core.so.5
#13 0x00007ff72676c639 in QGuiApplicationPrivate::init() () from /tmp/squashfs-root/usr/bin/../lib/libQt5Gui.so.5
#14 0x00007ff726e12a69 in QApplicationPrivate::init() () from /tmp/squashfs-root/usr/bin/../lib/libQt5Widgets.so.5
#15 0x000000000043a929 in main (argc=<optimized out>, argv=<optimized out>) at /__w/hotspot/hotspot/src/main.cpp:69
(gdb) continue

or with an extracted image:

$ ./hotspot-v1.2.3-45-g02fd82c-x86_64.AppImage --appimage-extract
$ PATH=./squashfs-root/usr/bin:$PATH LD_LIBRARY_PATH=./squashfs-root/usr/lib64:/usr/local/lib64:/usr/lib64:./squashfs-root/usr/lib:$LD_LIBRARY_PATH gdb -q --exec=hotspot --symbols hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot -ex run
Reading symbols from hotspot-debuginfo-v1.2.3-45-g02fd82c/usr/bin/hotspot...
Starting program: /tmp/squashfs-root/usr/bin/hotspot

Note that source files matching the commit the AppImage was created from needs to be manually downloaded or inspected in the git repo for this approach. Also note that you cannot debug any QT (or other system) parts this way, only Hotspot itself.

AppImage-Debugging using debuginfod

To use debuginfod, you will need to additionally download the docker image from ghcr.io/kdab/kdesrc-build:latest. For that you need to authenticate yourself to GitHub. If you have a ghcr.io authentication token and use pass, you can do that with

$ scripts/appimage/download_docker.sh
downloading docker image from ghcr.io
Login Succeeded
latest: Pulling from kdab/kdesrc-build
Digest: sha256:1be0cdbeff1c8c796b77a4244a1f257e02c4a896fd6add93b7b00a9d76db8727
...
ghcr.io/kdab/kdesrc-build:latest
Removing login credentials for ghcr.io

Once that is done, you can run the scripts/appimage/run_debuginfod_in_docker.sh script as such:

$ ./scripts/appimage/run_debuginfod_in_docker ~/Downloads/debuginfo.zip
unpacking debuginfo...
hotspot-debuginfo-v1.3.0-391-g590f810/usr/bin/hotspot
hotspot-debuginfo-v1.3.0-391-g590f810/usr/lib64/libexec/hotspot-perfparser
starting debuginfod in docker...
to use it on your host system, set:

    export DEBUGINFOD_URLS="127.0.0.1:12345 https://debuginfod.centos.org/ https://debuginfod.archlinux.org"

[Fri May 24 19:58:56 2024] (16/16): opened database /opt/app-root/src/.debuginfod.sqlite
[Fri May 24 19:58:56 2024] (16/16): sqlite version 3.7.17
[Fri May 24 19:58:56 2024] (16/16): started http server on IPv4 IPv6 port=12345
...

Keep that debuginfod process running. You can now start using the local debuginfod in combination with the official Centos instance to get debug information for all the dependencies and build artifacts of hotspot. Here is one example for that using GDB:

$ ./hotspot-v1.2.3-45-g02fd82c-x86_64.AppImage &
$ export DEBUGINFOD_URLS="127.0.0.1:12345 https://debuginfod.centos.org/ https://debuginfod.archlinux.org"
$ gdb -q -p $(pidof hotspot)
Attaching to process 123456
...

with a GDB session of

...
This GDB supports auto-downloading debuginfo from the following URLs:
127.0.0.1:12345 https://debuginfod.centos.org/ https://debuginfod.archlinux.org
Enable debuginfod for this session? (y or [n]) y
Debuginfod has been enabled.
To make this setting permanent, add 'set debuginfod enabled on' to .gdbinit.
Downloading 37.95 MB separate debug info for /home/user/Downloads/squashfs-root/usr/bin/hotspot
...
(gdb) bt
#0  0x00007f70bd5140bf in __GI___poll (fds=0x2c83f40, nfds=5, timeout=0) at ../sysdeps/unix/sysv/linux/poll.c:29
#1  0x00007f70b7a4c3fc in g_main_context_iterate.isra () from /tmp/.mount_hotspoBCRbef/usr/lib/libglib-2.0.so.0
#2  0x00007f70b7a4c52c in g_main_context_iteration () from /tmp/.mount_hotspoBCRbef/usr/lib/libglib-2.0.so.0
#3  0x00007f70bdd08aa4 in QEventDispatcherGlib::processEvents(QFlags<QEventLoop::ProcessEventsFlag>) ()
   from /tmp/.mount_hotspoBCRbef/usr/lib/libQt5Core.so.5
#4  0x00007f70bdcb361b in QEventLoop::exec(QFlags<QEventLoop::ProcessEventsFlag>) ()
   from /tmp/.mount_hotspoBCRbef/usr/lib/libQt5Core.so.5
#5  0x00007f70bdcbb26c in QCoreApplication::exec() () from /tmp/.mount_hotspoBCRbef/usr/lib/libQt5Core.so.5
#6  0x000000000043a23e in main (argc=<optimized out>, argv=<optimized out>) at /__w/hotspot/hotspot/src/main.cpp:194
(gdb) continue

Note that source files are not supported in this way yet, as that would blow up the size of the docker image and thereby slow down our CI.