Building Qt 5.15 LTS for Raspberry Pi on Raspberry Pi OS
Building Qt 5.15 LTS for Raspberry Pi on Raspberry Pi OS rootThis tutorial provides you a step-by-step guide on how to build an up-to-date Qt 5.15 LTS release from source with proper hardware acceleration support for Raspberry Pi on Raspberry Pi OS, both 32-bit and 64-bit, Buster and Bullseye. Qt is a popular cross-platform application framework that enables developers to create user interfaces and applications that can run on various platforms, including the Raspberry Pi.
Current for version 5.15.12, released 20.12.2023.
Raspberry Pi OS (aka Raspbian), based on Debian Buster, comes with a very old version of Qt 5.11 that is already outdated. Afaik there are no up-to-date backports so the only way to get an up to date version of Qt with board specific features enabled for running on your Raspberry Pi is to build it yourself.
Note: These instructions are mostly written for the older Debian Buster based Raspberry Pi OS version. The Bullseye release of Raspberry Pi OS comes with Qt 5.15 in the repositories and will work fine under X11 but does not support running without it like for example plain eglfs. In case you would like to use plain eglfs you might still like to build your own customized version of Qt 5.15.
This tutorial concentrates on the Qt 5.15 LTS, the Long Time Support releases of 5.15, the last in the Qt 5 series. Unfortunately latest releases of Qt 5.15 are not available as Open Source immediately anymore but with a 1 year delay from commercial release. The latest open source release at this time is 5.15.12, released in 20.12.2023. KDE provides patches for the Qt 5.15 branch.
Note: Qt 5.15, and therefore Qt 5 branch, is going to be End-of-Life pretty soon, you should consider using Qt 6, especially for any new projects, there is a tutorial available for just that.
These instructions will build version of Qt that uses the eglfs interface by default and therefore runs applications fullscreen. You can optionally add X11 and/or Wayland support by installing the required development packages, they are described in the Optional features table below.
You can also choose what graphics drivers you will be using for eglfs, depending on what version of the Raspberry Pi you are using, either the proprietary Broadcom EGL or open source Mesa.
Building Qt for and on the Raspberry Pi is pretty straightforward, there are some Pi specific configurations that needs to be made, but in short it consist of the following steps:
- Downloading sources of Qt
- Checking the Qt source package integrity
- Preparing the sources for building
- Setup Qt mkspecs configuration for Raspberry Pi
- Installing required dependencies
- Installing optional dependencies
- Fix for EGL library detection (Not needed for Pi 4)
- Configuring the Qt build
- Compiling Qt
- Installing the Qt build
This tutorial is written for the full source of version 5.15.12, it is fully possible to build only parts using the split up Qt sub-module source packages, but this tutorial will not go into that at this time. Anyway, it is also very easy to skip building of modules that you don't need with the no-make options.
Note: These example builds have been verified to work on both 32-bit and 64-bit Raspberry Pi OS. Just make sure you choose the correct platform!
Tutorial changelog
As this tutorial evolves over time, changes are logged here.
- 04.04.2021 - 5.15.2 Specific guide, copied from latest 5.12.10 version
- 28.04.2021 - VC4 needs libdrm-drm, separete table for graphics options, preliminary 64-bit build option
- 07.05.2022 - Add mention of using no-feature-eglfs_brcm when building under 64-bit Bullseye
- 11.05.2022 - Bump version to 5.15.3
- 15.05.2022 - Bump version to 5.15.4
- 16.05.2022 - Looks like they renamed the source archive name, fixed download & tar examples.
- 28.06.2022 - Bump version to 5.15.5
- 26.10.2022 - Bump version to 5.15.6
- 05.11.2022 - Bump version to 5.15.7
- 07.01.2023 - Bump version to 5.15.8
- 02.05.2023 - Bump version to 5.15.9
- 03.08.2023 - Bump version to 5.15.10
- 17.10.2023 - Bump version to 5.15.11
- 31.12.2023 - Bump version to 5.15.12
Storage space and memory requirements
Make sure you have enough disk space free on your on your Pi as building Qt requires a lot of storage space. The unpacked full Qt sources itself takes around 3.7GB, the build result around 830MB and the installation from 232MB or more. A minimum of 8GB SD card is highly recommended. USB3 attached HDD or SDD is highly recommended on the Pi 4 as it speeds up compiling. Running out of disk space after hours of compiling can be extremely annoying, trust me.
Item | Size | Note |
---|---|---|
Qt source archive | 630MB | qt-everywhere-opensource-src-5.15.12.tar.xz |
Unpacked Qt Sources | 3.9GB | qt-everywhere-src-5.15.12 |
Build result | ~959MB | Typical, depends on configuration options and enabled features |
Install size | ~250MB | Typical, depends on configuration options and enabled features |
Enable swap and adjust CPU/GPU memory split
Compiling Qt takes quite a lot of memory, especially if trying to do a parallel build. Some parts take even too much memory and we need to disable building of them. It is highly recommended to enable at least 200MB of swap and also consider adjusting the Raspberry Pi CPU/GPU memory-split for the time of compilation, especially if parallel building or if you are using a model with limited amount of memory. On the new Raspberry Pi 4 models with 2GB, 4GB or 8GB of memory, swap is not required. If using swap, a USB3 attached HDD or SSD is also highly recommended as the swap device.
Build Qt for Raspberry Pi
Download the Qt 5.15.12 source archive
Download the single source tar file from download.qt.io, version 5.15.12, the package is relatively large, 630MB, so depending on your bandwidth it might take some time to download, grab a coffee or continue with the dependencies while the Qt source archive is downloading.
wget https://download.qt.io/official_releases/qt/5.15/5.15.12/single/qt-everywhere-opensource-src-5.15.12.tar.xz
Check archive MD5 hash
Just to make sure the download was successful and is what it should be, check the MD5 hash of the archive against the one in the official file with:
md5sum qt-everywhere-opensource-src-5.15.12.tar.xz
Un-tar the source archive
Un-tar the source archive in a suitable location, with enough free space (~4GB). This will take around 7-13 minutes on a Raspberry Pi 3+, depending on SD card speed, and even more on an older model, so go grab of coffee again. If you are on a Pi 4, then we highly recommend using fast USB 3 storage (HDD or SSD) for both sources and building. You can of course start installation of the build dependencies while you wait.
tar xf qt-everywhere-opensource-src-5.15.12.tar.xz
Setup Qt mkspecs configuration files
Qt build is configured trough the configure script, but platform and device specific settings are set in Qt specific mkspecs configuration files. Qt includes mkspecs for the Raspberry Pi but they are unfortunately setup for cross-compilation environments only and can not be used directly for native building without editing or the need for faking a cross compilation environment and that has its own issues.
Fortunately suitable mkspecs files for the various Pi versions are available in our Qt raspberrypi-configuration github repository, so the next step is to clone that repository and install the mkspecs files into the Qt source tree so that they can be used for the build.
Clone the configuration repository:
git clone https://github.com/oniongarlic/qt-raspberrypi-configuration.git
change into the cloned repository and run (adjust DESTDIR in case your Qt sources are extracted somewhere else), make sure QTVERSION match like in the example as the repository might not default to the latest version:
cd qt-raspberrypi-configuration && make install DESTDIR=../qt-everywhere-src-5.15.12 QTVERSION=5.15.12
Install required build dependencies
You will need to install plenty of packages to be able to build Qt 5.15. Some of the Qt 5.15 features are optional and can be either left our or included, depending on your particular needs. For example support for various databases (PostgreSQL, MySQL/MariaDB) and if you don't need a specific feature you can skip building the support (or build the from separate packages later). Or the other way around, if you need a specific feature you might need to install more development packages.
Some features are not strictly required but might still be nice to have, for example support for the webp image format is optional, but these days it is already widely used so might be good to include.
See the table below for a list of some optional features and the required development packages you need to install. But first, start by updating your apt package cache so everything is fresh:
apt update
Then continue with required package installation below.
Install the bare minimum required development packages for building Qt 5.15 with apt:
apt install build-essential libfontconfig1-dev libdbus-1-dev libfreetype6-dev libicu-dev libinput-dev libxkbcommon-dev libsqlite3-dev libssl-dev libpng-dev libjpeg-dev libglib2.0-dev
Graphics driver options
It is possible to use either the proprietary EGL blobs from Broadcom or the Mesa open source drivers. Broadcom drivers can be used on all older Pi variants, but not on any Pi 4 variants (Pi4, 400, Compute Module 4). For those you need to use Mesa.
Graphics driver | Required package(s) | Information |
---|---|---|
Broadcom EGL For vintage Pi, Zero, Pi 2, Pi 3, CM 1, CM3 32-bit only |
libraspberrypi-dev |
Required for all pre-Pi 4 boards if not using open source GL drivers. EGLFS Rasberry Pi .................... yes |
VC4 driver Mandatory on Raspberry Pi 4 Mandatory on 64-bit |
libgles2-mesa-dev libgbm-dev libdrm-dev |
Use -platform linux-rpi-vc4-g++ Under 64-bit Bullseye, make sure to use/add the option: to disable any usage of the old brcm libraries. Note: If you build with gstreamer support you must also install libwayland-dev |
Install optional Qt 5 feature development packages
Qt consist of many modules, depending on your needs you might like to install additional development packages to be able to enable support for these features in Qt 5. Check the table below for any optional features you might need and the required development packages that you need to install to support them. Also make sure that the optional feature you need is found and enabled by the configure script by checking the output of configure run (see config.summary).
Optional feature | Packages to install | Configure option |
---|---|---|
Bluetooth |
bluez libbluetooth-dev |
|
gstreamer multimedia framework support Wayland development packages is required as it is required by a gstreamer header that is used by Qt. |
libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly gstreamer1.0-plugins-bad libgstreamer-plugins-bad1.0-dev gstreamer1.0-pulseaudio gstreamer1.0-tools gstreamer1.0-alsa libwayland-dev |
Automatic, force with -gstreamer Optionally disable with -no-gstreamer |
Linux ALSA Audio support |
libasound2-dev |
Automatic, force with -alsa |
Pulseaudio support |
pulseaudio libpulse-dev |
Automatic, force with -pulseaudio |
Flite speech synthesis | flite1-dev | -flite -flite-alsa |
Support for various databases (PostgreSQL, MariaDB/MySQL) |
libpq-dev libmariadbclient-dev |
Automatic, force with -sql-psql -sql-mysql |
Printing support using CUPS |
libcups2-dev |
|
Wayland support |
libwayland-dev |
|
X11 support |
libx11-dev libxcb1-dev libxext-dev libxi-dev libxcomposite-dev libxcursor-dev libxtst-dev libxrandr-dev libfontconfig1-dev libfreetype6-dev libx11-xcb-dev libxext-dev libxfixes-dev libxi-dev libxrender-dev libxcb1-dev libxcb-glx0-dev libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev libxcb-sync-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev libxcb-render-util0-dev libxcb-util0-dev libxcb-xinerama0-dev libxcb-xkb-dev libxkbcommon-dev libxkbcommon-x11-dev |
|
QtWebEngine |
Required: flex bison gperf libre2-dev libnss3-dev libdrm-dev Optional: libxml2-dev libxslt1-dev libminizip-dev libjsoncpp-dev liblcms2-dev libevent-dev libprotobuf-dev protobuf-compiler Optional but unusable versions in raspbian: libopus-dev libvpx-dev Note: We highly recommend to build QtWebEngine separately from base Qt. |
|
libzstd | libzstd-dev | |
Accessibility |
libatspi-dev |
|
SCTP [1][2] |
libsctp-dev |
-sctp |
Install any package from the above table with apt install.
Broadcom EGL library filename fix
Note: This is NOT needed when building a Raspberry Pi 4 configuration.
On Raspbian Stretch/Buster the OpenGL library files have been renamed (1, 2) so that they wouldn't conflict with Mesa installed ones. Unfortunately Qt configure script is still looking for the old names. See QTBUG-62216 for details.
If you use the mkspecs configuration files provided in this tutorial you don't need to worry about this as they are setup to reference the libbrcm*.so library names.
Create a shadow build directory outside of the Qt source tree
We will build Qt 5 outside of the source tree, this way you can easily have different build version and easily also start over in case of any issues with configuration or the build itself. Your build location can be anywhere where there is enough space, for example an HDD, SDD or USB stick in case you are running out of spaec on your SD card. Remember to adjust any paths in the example commands.
mkdir build cd build
Configure the Qt 5 build environment
We configure Qt 5 for a native build and set device specific settings, like libraries, default QPA plugin to use, etc directly on the configure command line. Note that the below configuration is just an example, you might need to adjust it for your particular needs, for example if you do need wayland the remove the "-skip wayland" option. This makes it also easy to optimize for any specific Raspberry Pi board type, see the table for used CFLAGS & CXXFLAGS for your target board. Configure run takes ~10 minutes as it will first compile the Qt build tool qmake and then run various tests and feature checks.
PKG_CONFIG_LIBDIR=/usr/lib/arm-linux-gnueabihf/pkgconfig:/usr/share/pkgconfig \
../qt-everywhere-src-5.15.12/configure -platform linux-rpi-g++ \
-v \
-opengl es2 -eglfs \
-no-gtk \
-opensource -confirm-license -release \
-reduce-exports \
-force-pkg-config \
-nomake examples -no-compile-examples -nomake tests \
-skip qtwayland \
-skip qtwebengine \
-no-feature-geoservices_mapboxgl \
-qt-pcre \
-no-pch \
-ssl \
-evdev \
-system-freetype \
-fontconfig \
-glib \
-prefix /opt/Qt/5.15 \
-qpa eglfs
Configuration options explained
Wondering what the options do, let the below table explain:
Option | Description | Why is this option used |
---|---|---|
-v | Verbose configuration output | To see what is going on |
-opengl es2 -eglfs | Use OpenGL ES and use Qt EGLFS platform plugin | So we don't need to run X11 |
-no-gtk | Don't use GTK theme support | No need for GTK development libraries |
-opensource -confirm-license | Select open source license build, don't prompt for license | License needs to be set |
-release | Use release build options (optimized libraries and binaries) | For speed |
-nomake examples -no-compile-examples |
Skip building of example applications and tests. | Takes time and space |
-qt-pcre | Use Qt provided pcre library | |
-no-pch | Don't use pre-compiled C++ headers | Takes a lot of space |
-ssl | Use OpenSSL, required for crypot and for example https support in Qt networking code | Crypto is the new black |
-evdev | Use Linux generic input subsystem | |
-system-freetype | Use system provided version of freetype library instead of bundled version | Speed up compliation |
-fontconfig | Use fontconfig for font discovery | Fonts are nice to have |
-glib | Use glib compatible event loop | Integrates with glib based event loop users, for example gstreamer |
-prefix /opt/Qt/5.15 |
Installation prefix for the Qt framework. Running make install will install Qt at this location. If you like to have different versions installed then you can use the full version string. Note: Binaries will have hardcoded paths to the Qt libraries |
Qt needs to be installed somewhere where you can find it |
-qpa eglfs |
Default platform abstraction plugin to use for applications. |
Selects the default platform plugin, on Pi EGLS is nice so you don't need to run X11 |
About QtWebEngine
Building the qtwebengine module takes a lot of time and space, the default configure example above disables it with -skip qtwebengine. The reason being that on older Raspberry Pi models with a relatively tiny amount of memory it is pretty much impossible to build succesfully.
Building and adding QtWebEngine support
Now with the 4GB or 8GB Raspberry Pi 4 it is fully possible to build, but you might still need to enable swap and also limit the amount of parallel builds the ninja build tool (that qtwebengine uses internally for building) is allowed to use. You can either build qtwebengine at the same time as the rest of Qt, but in case it fails (and it probably will) your whole build has failed, so the recommended way is to first build the base Qt 5 separately, install it and then build qtwebengine separately. But if you so choose, you can enable building of qtwebengine by removing the -skip qtwebengine configure option. Make sure that when you invoke make for building, that you add NINJAJOBS=-j1 to the command line. (make -j4 NINJAJOBS=-j1)
Building QtWebEngine separately
It is highly recommended to build QtWebEngine separately,read the separate guide on how to build qtwebengine.
Raspberry Pi platform options
Select platform according to the Pi model you are going to run Qt on. You can build on a fast Pi 4/3+ and the move the files over to a slower version if needed, just make sure you build for the correct ARM architecture in that case.
Note: For a Qt 5.15 that will be run on a Raspberry Pi 4 you must use KMS as Broadcom EGL is not supported on that model and never will. Make sure you have installed the packages: libgles2-mesa-dev libgbm-dev
Raspberry Pi model | ARM architecture version | Platform option | Compiler FLAGS that will be used |
---|---|---|---|
Raspberry Pi 4 32-bit |
ARMv8 | -platform linux-rpi4-v3d-g++ |
-march=armv8-a -mtune=cortex-a72 -mfpu=crypto-neon-fp-armv8 Note: Will use VC4 DRM Mesa GL driver, not Broadcom EGL as it is not supported on the Pi 4. Note: Under Bullseye, make sure to add the option: -no-feature-eglfs_brcm so that brcm libraries are not used Note: You must install libgles2-mesa-dev libgbm-dev libdrm-dev |
Raspberry Pi 4 64-bit |
ARMv8 | -platform linux-rpi64-vc4-g++ |
Note: Preliminary, not tested properly yet but should work Note: Under Bullseye, make sure to add the option: -no-feature-eglfs_brcm so that brcm libraries are not used Note: You must install libgles2-mesa-dev libgbm-dev libdrm-dev |
Raspberry Pi 3, models: Raspberry Pi 2, model: |
ARMv8 | -platform linux-rpi3-g++ |
-march=armv8-a -mtune=cortex-a53 -mfpu=crypto-neon-fp-armv8 Note: QtScript won't build with these flags. If you need QtScript, then build with ARMv7 options. Note: If you will build Qt Creator you will need QtScript! |
Raspberry Pi 2, model: B |
ARMv7 | -platform linux-rpi2-g++ |
-march=armv7-a -mtune=cortex-a7 -mfpu=neon-vfpv4 |
Raspberry Pi 1, models: Original, Zero, Zero W, A, A+, B+, Compute Module 1 |
ARMv6 | -platform linux-rpi-g++ |
-march=armv6zk -mtune=arm1176jzf-s -mfpu=vfp |
Check the configure result
When the Qt configuration scripts has finnished succesfully it will print out a configuration summary and store the result in the config.summary file, also all the raw checks will be in the config.log file. Check that all options and features you needed are found and enabled in the summary output. If not, check the config.log file for a reason.
Example configuration summaries for
Broadcom EGLFS
Make sure that the configure script detects Raspberry Pi EGLFS when building for Raspberry Pi 1,2 or 3. Look for the following output or check the log file config.summary:
EGLFS .................................. yes EGLFS details: ... EGLFS Rasberry Pi .................... yes
Note: If it says "no", check the configuration run output for reasons. Make sure that you have all required build dependencies installed (check the above table) and fixed the EGLFS library references!
MesaGL
When building for Raspberry Pi 4, check for
EGLFS .................................. yes EGLFS details: ... EGLFS EGLDevice ...................... yes ... EGLFS Raspberry Pi ................... no
Note: If it says "no" for EGLDevice, check the configuration run output for reasons. Make sure that you have all required build dependencies installed (check the above table), especially the note about Pi 4 packages.
Compile Qt
Now Qt should be configured properly with all features enabled that we need. If you need some of the optional features, make sure to check the configure result that they where properly detected.
To compile Qt run:
make
or if you are using any of the quad-core Pis, append the -j4 parameter to build in parallel. Make sure you have proper cooling in this case, the 3+ this should run fine without getting throttled too much.
Build time
The compilation time depends on the Qt features being built, speed of your SD card, etc. Build time on a Raspberry Pi 3 with two parallel jobs (make -j2) takes roughly 8 hours.
System | Time |
---|---|
Raspberry Pi 400 (Bullseye, aarch64, -j4, SD) | ~274 minutes |
Raspberry Pi 3 (-j2,SD) | ~540 minutes |
Note: It might happen that parallel build needs too much memory and the compiler will crash. In this case try run with just one process or try -j3 or just -j2. Enabling swap will also help.
Optional: Speed up building with distcc
If you have many Raspberry Pi you can speed up the compilation by using distcc. In that case setup distcc on your machines and invoke make with:
make CC=distcc CXX=distcc -j[Machines in distcc cluster]
Install the build
The compilation should finnish without any errors, if it does not, double check that you have all the dependecies installed and run configure correctly.
If all is well, install Qt by running
make install
You should now have Qt 5.15.12 installed in /opt/Qt/5.15 ready for use. To configure your Qt project(s) to build with this version run qmake from the installation directory:
/opt/Qt/5.15/bin/qmake
You can of course also add it to your PATH, edit your users ".profile" or system wide in "/etc/profile" .
Common build issues
We have collected some common issues that might come up while building in the table below.
Problem | Solution |
---|---|
In function ‘EGLNativeWindowType createDispmanxLayer(const QPoint&, const QSize&, int, DISPMANX_FLAGS_ALPHA_T)’: |
You are trying to build with Broadcom BRCM libraries in a 64-bit environment. That will not work. Solution: Configure with -no-feature-eglfs_brcm |
Choosing platform
As explained in the introduction, this build will default to using the eglfs platform, meaning that no windowing environment is required to run GUI applications. You can choose the platform binaries will run against by suppling the "-platform" paramter when running them.
Platform | Parameter | Information |
---|---|---|
EGLFS | -platform eglfs | The default if example options are used (qpa eglfs) |
X11 | -platform xcb | |
VNC | -platform vnc | |
WebGL | -platform webgl |
Enjoy Qt 5.15 on your Pi, Happy coding!