Building Qt 5.12 LTS for Raspberry Pi on Raspbian

31/05/2020 - 21:22
Average: 4.7 (15 votes)

Raspberry Pi OS (aka Raspbian), based on Debian Buster, comes with an 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.

Even if this tutorial concentrates on the Qt 5.12.8 LTS, the Long Time Support release, the guide is tested to work on 5.14 and 5.15 too.

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.

Building Qt on the Raspberry Pi is pretty straightforward, there is one Pi specific configuration that needs to be made. In short it consist of the following steps:

  1. Downloading sources of Qt
  2. Checking the Qt source package integrity
  3. Preparing the sources for building
  4. Setup Qt mkspecs configuration for Raspberry Pi
  5. Installing required dependencies
  6. Installing optional dependencies
  7. Fix for EGL library detection (Not needed for Pi 4)
  8. Configuring the Qt build
  9. Compiling Qt
  10. Installing the Qt build

This tutorial is written for the full source of version 5.12.8, it is fully possible to build only parts using the split up Qt submodule sources 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.

Tutorial changelog

As this tutorial evolves over time, changes are logged here.

  • 10.12.2018 - Initial (beta) version for Qt 5.12 published
  • 29.01.2019 - Removed old fake cross compiled way. Added example Pi model specific CFLAGS & CXXFLAGS. Fixed download link URL.
  • 22.02.2019 - Reference to update version 5.12.1.
  • 23.04.2019 - Reference to update version 5.12.3.
  • 26.04.2019 - Use Qt mkspecs for configuration as configure overrides, even if it should work, does not work as documented
  • 25.09.2019 - Reference to update version 5.12.5
  • 06.02.2020 - Reference to update version 5.12.7
  • 11.02.2020 - Fix wrong version leftovers, add Pi 4 platform option.
  • 25.05.2020 - Reference to update version 5.17.8, use apt, add section about building webengine

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 disk space. The unpacked full Qt sources itself takes around 2.8GB, the build result around 625MB and the installation 155MB. A minimum of 8GB SD card is highly recommended. USB3 attached HDD or SDD is highly recommended on Pi 4 as it speeds up compiling. Running out of disk space after hours of compiling can be extremely annoying, trust me.

Qt build storage space requirements
Item Size Note
Qt source archive 483MB qt-everywhere-src-5.12.8.tar.xz
Unpacked Qt Sources 2.8GB qt-everywhere-src-5.12.8
Build result 745MB Depends on configuration options and enabled features
Install size 155MB - 300MB 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 recommened 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 or 4GB of memory, swap is not required. USB3 attached HDD or SSD is also highly recommended.

Build Qt for Raspberry Pi

Download the Qt 5.12.8 source archive

Download the single source tar file from download.qt.io, version 5.12.8. The package is quite large, 482MB, so depending on your bandwidth it might take some time to download, grab a coffe or continue with the dependecies while the Qt source archive is downloading.

wget http://download.qt.io/official_releases/qt/5.12/5.12.8/single/qt-everywhere-src-5.12.8.tar.xz

Check archive MD5 hash

Just to make sure the download was succesfull and is what it should be, check the MD5 hash of the archive with:

md5sum qt-everywhere-src-5.12.8.tar.xz

It should be:

8ec2a0458f3b8e9c995b03df05e006e4   qt-everywhere-src-5.12.8.tar.xz

Un-tar the source archive

Un-tar the source archive in a suitable location, with enough free space (~2.8GB). 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 coffe again. If you are on a Pi 4, then we highly recommend using USB 3 storage (HDD or SSD). You can of course start installation of the build dependecies while you wait.

tar xf qt-everywhere-src-5.12.8.tar.xz

Setup Qt mkspecs configuration files

Qt build is configured trough the configure script, but platform and device specifc settings are set in 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 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 github, 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.

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):

cd qt-raspberrypi-configuration && make install DESTDIR=../qt-everywhere-src-5.12.8

Install required build dependencies

You will need to install plenty of packages to be able to build Qt. Some of the Qt features are optional, for example support for various databases and if you don't need a specific feature you can skip building the support. Or the other way around, if you need a specific feature you might need to install more packages. 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 package cache so everything is fresh:

apt update

Then continue with required package installation.

Install the minimum required development packages

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 libraspberrypi-dev

Install optional 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. 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.

Optional features
Optional feature Packages to install Configure option
Bluetooth

bluez libbluetooth-dev

 
gstreamer multimedia framework support

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

 
Linux ALSA Audio support

libasound2-dev

 
Pulseaudio support

pulseaudio libpulse-dev

 
Support for various databases (PostgreSQL, MariaDB/MySQL)

libpq-dev libmariadbclient-dev

 

Printing support using CUPS

libcups2-dev

 
Wayland support

libwayland-dev

 
X11 support

libx11-dev libxcb1-dev libxkbcommon-x11-dev libx11-xcb-dev libxext-dev

 
Accessibility

libatspi-dev

 
SCTP [1][2]

libsctp-dev

-sctp
Using experimental VC4 driver instead of Broadcom EGL binary-blobs libgles2-mesa-dev libgbm-dev Experimental

Use -platform linux-rpi-vc4-g++

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 outside of the source tree, this way you can easily have different build version and easily also start over in case of any issues. You build location can be anywhere where there is enough space, for example an USB stick in case you are running out on your SD card. Remember to adjust any paths in the commands.

mkdir build
cd build

Configure the Qt build environment

We configure Qt 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 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 table for suitable CFLAGS & CXXFLAGS for your target board. Configure run takes ~10 minutes as it will first compile 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.12.8/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 \
-skip qtwayland \
-skip qtwebengine \
-no-feature-geoservices_mapboxgl \
-qt-pcre \
-no-pch \
-ssl \
-evdev \
-system-freetype \
-fontconfig \
-glib \
-prefix /opt/Qt5.12 \
-qpa eglfs

Building QtWebEngine support

Building the qtwebengine module takes a lot of time, the default configure example above disables it with -skip qtwebengine. The reason being that on older Pi versions with less memory it was pretty much impossible to build. Now with the 4GB Raspberry Pi 4 it is fully possible to build, but you do need to enable swap and also limit the amount of parallel build the ninja build tool (that qtwebengine uses internally for building) is allowed to use.

So, to build qtwebengine, remove the -skip qtwebengine line and when you invoke make for building add NINJAJOBS=-j1 to the command line.

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. Note that for a Raspberry Pi 4 you must use KMS, Broadcom EGL is not supported.

Model specific optimization
Raspberry Pi model ARM architecture version Platform option Compiler FLAGS that will be used
Raspberry Pi 4 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.

Raspberry Pi 3, models:

3+, A+, Compute Module 3, Compute Module 3+

Raspberry Pi 2, model:

B v1.2

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.

And remove -skip qtscript from configure 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.

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 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

 

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.

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.12.8 installed in /opt/Qt5.12 ready for use. To configure your Qt project(s) to build with this version run qmake from the installation directory:

/opt/Qt5.12/bin/qmake

You can of course also add it to your PATH, edit your users ".profile" or system wide in "/etc/profile" .

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.

Qt Platform option examples
Platform Parameter
X11 -platform xcb
VNC -platform vnc
WebGL -platform webgl

Enjoy Qt 5.12 on your Pi, Happy coding!

 

Changelog: 
10/12/2018 - 10:38
Keywords: 
Qt, Raspberry Pi