Building Qt 6.2 for Raspberry Pi on Raspberry Pi OS

Guide on how to build Qt 6.2 LTS (Release) for use on a Raspberry Pi running Raspberry Pi OS.

Updated as of Qt release 6.2.4

Raspberry Pi CPU closeup
14 July, 2021
Changed
24 November, 2022

Guide on how to build Qt 6.2 LTS components for use on a Raspberry Pi running Raspberry Pi OS. The configuration and build differs quite a lot from how Qt 5 was built as the build system is now using cmake and ninja, instead of the older qmake and make combo.

Note: This guide was written for Raspberry Pi OS Buster version but it works also with Bullseye.

The procedure is exactly the same for both 32-bit or 64-bit versions of Raspberry Pi OS, just adjust any architecture specific paths accordingly.

This tutorial is written for the split components version of Qt 6.2 instead of the all components one. This makes it much faster to get up and running with only the components you actually need. Building Qt 6 for and on the Raspberry Pi is still pretty straightforward, there are some Pi specific configurations that needs to be made, but in short it consist of the following steps:

  1. Configure Pi graphics system to use Mesa/Vulkan driver
  2. Installing all required build and runtime dependencies for Qt base
  3. Installing any optional build and runtime dependencies Qt base
  4. Downloading sources of Qt 6.2 base
  5. Checking the Qt 6.2 base source package integrity
  6. Extract the source
  7. Configuring the Qt 6.2 base build
  8. Compiling Qt 6.2 base
  9. Installing the Qt 6.2 base
  10. Continue to installing any submodules

And for any Qt submodules it is basically a matter of:

  1. Install required build and runtime dependencies
  2. Install optional build and runtime dependencies
  3. Download submodule source archive
  4. Check integrity of submodule source archive
  5. Extract submodule source archive
  6. Configure submodule for building
  7. Build submodule
  8. Install submodule
  9. Select another submoule and goto step 1

Prepare build tools

Build essentials

As we need to be able to build software, make sure all the essential build tools are installed with:

apt install build-essential

Installing cmake from source

Note: Building a custom cmake is not required on Raspberry Pi OS Bullseye. It contains a new enough version.

The build system has changed in Qt 6 and instead of qmake and make, that was used with Qt 5, it now uses cmake and ninja. We will need need to install cmake from source, as the one provided in the Raspberry Pi OS, pre Bullseye, package repository (surprise!) is too old. Building cmake is quite easy, it needs to first bootstrap itself and then we can build and install it. We will install our own cmake in a custom location so that it won't conflict with the distribution provided one. Just remember to call it using the full path so the correct version gets used.

Luckily the version available of the ninja build tool is good enough for our needs.

Install cmake from package on Bullseye

If you are on Bullseye then you don't need to build cmake as the distrubution comes with a new enough version. Just install with apt.

apt install cmake

Build and install cmake from sources

The build process of cmake is straightforward, download, untar, build and install. We are using the cmake 3.22 release branch as that has been tested to fully build Qt 6 successfully.

wget https://github.com/Kitware/CMake/releases/download/v3.22.2/cmake-3.22.2.tar.gz
tar xf cmake-3.22.2.tar.gz
mkdir cbuild && cd cbuild
../cmake-3.22.2/bootstrap --prefix=/opt/cmake --parallel=4 && make -j4 && make install

Now we have a new enough cmake installed that we can use for building Qt 6.2!

Install required build dependencies

You will need to install plenty of packages to be able to build Qt 6.2. Some of the Qt 6.2 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 the other way around, if you need a specific feature you might need to install more development packages.

First, start by updating your apt package cache so everything is fresh:

apt update

Then continue with required package installation below.

Minimum required development packages
Development package Information
ninja-build Minimal build system, similar to make
libfontconfig1-dev Font configuration library
libdbus-1-dev D-Bus library
libfreetype6-dev Font engine library
libicu-dev Unicode library
libinput-dev Input device handling
libxkbcommon-dev XKB compiler library
libsqlite3-dev sqlite3 database driver
libpng-dev PNG Image support
libssl-dev OpenSSL support
libjpeg-dev JPEG Image support
libglib2.0-dev glib mainloop support

Install all the required development packages with:

apt install ninja-build 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 options
Graphics driver Required package(s) Information

Broadcom EGL

For vintage Pi, Zero, Pi 2, Pi 3, CM 1, CM3

32-bit only

libraspberrypi-dev

Note: Incomplete, This has not been properly tested yet

Note: Support for is currently disabled in the Qt build system, so this can not be used at this time.

Required for all pre-Pi 4 boards if not using open source GL drivers.
 

VC4 driver

Mandatory on Raspberry Pi 4

Mandatory on 64-bit

libgles2-mesa-dev libgbm-dev libdrm-dev

QT_FEATURE_kms=ON
QT_FEATURE_opengles2=ON
QT_FEATURE_opengles3=ON

Vulkan driver

Only on Raspberry Pi 4

libvulkan-dev vulkan-tools vulkan-utils

Note: Requires building of Mesa Vulkan driver. Guide TBA later.

QT_FEATURE_vulkan=ON

Optional base feature dependencies

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.

Optional features for base Qt
Optional feature Packages to install Configure option
     
Support for various databases (PostgreSQL, MariaDB/MySQL, etc)

libpq-dev libmariadbclient-dev

 

Printing support using CUPS

libcups2-dev

 
X11 support

libx11-dev libxcb1-dev libxext-dev libxi-dev libxcomposite-dev libxcursor-dev libxtst-dev libxrandr-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 libxcb-xinput-dev

 
libzstd libzstd-dev Note: System version causes issues. Needs to be removed.
Accessibility

libatspi-dev

 
SCTP [1][2]

libsctp-dev

-sctp

Install any package from the above table with apt install.

Remove libzstd-dev

This might sound strange at first, but just in case, make sure that you DON'T have libzstd development package installed. Qt 6 will use the system provided one if installed and it will lead to problems as the rcc tool will fail with a Bus Error inside of the distribution provided libzstd. So to get around this issue, remove libztsd-dev if it is installed:

apt remove libzstd-dev

Building Qt 6.2 base

Qt Base provides the core parts of Qt and needs to be built and installed before anything else.

Download Qt 6.2 base sources

wget https://download.qt.io/official_releases/qt/6.2/6.2.4/submodules/qtbase-everywhere-src-6.2.4.tar.xz

Configure, build and install Qt 6.2 base

Extract the sources:

tar xf qtbase-everywhere-src-6.2.4.tar.xz

Create a build directory:

mkdir qtbasebuild && cd qtbasebuild

Optional: Create a cmake toolchain file

You might need to make a cmake toolchain file in case you are building for some other type of architecture than the one you are building on, for example you are going to run Qt on the armv6 based Pis but build on something faster (arvmv7 or armv8).

Note: This is not needed if the Qt build will be run on the same architecture as the building. For example, you are building on 32-bit armv7 Pi and intend to run Qt on armv7 or above then toolchain file is not required.

To create a cmake toolchain file, tc.cmake, fire up your favorite editor. Create the file somewhere that does not get deleted, for example in the install prefix you use, as it will be referenced by the Qt build files when installed. The contents for the file is, depending on target architecture (Note: only armv7 has been tested):

CMAKE_TOOLCHAIN_FILE Examples
Architecture Toolchain file contents

For armv6

set(CMAKE_CROSSCOMPILING FALSE)
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR armv6)
set(TARGET armv6-linux-eabi)
For armv7
set(CMAKE_CROSSCOMPILING FALSE)
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR armv7)
set(TARGET armv7-linux-eabi)
For armv8
set(CMAKE_CROSSCOMPILING FALSE)
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR armv8)
set(TARGET armv8-linux-eabi)
For aarch64

 

TBA

 

 

Configuration options

Qt can be customized in many ways when building, this table shows some options that you can use when configuring the  build.

Option Description
QT_FEATURE_opengles2=ON Use OpenGL ES 2.0
QT_FEATURE_opengles3=ON Use OpenGL ES 3.0
QT_FEATURE_kms=ON Use Kernel Mode Setting
QT_FEATURE_vulkan=ON Use Vulkan driver
QT_QPA_DEFAULT_PLATFORM=eglfs Set default platform plugin to eglfs
BUILD_WITH_PCH=OFF Disable precompiled headers

 

Configure the Qt 6.2 build

Then run the configuration (adjusting prefix if needed, add/remove any configuration options as needed, remove CMAKE_TOOLCHAIN_FILE parameter if not used):

/opt/cmake/bin/cmake -G Ninja \
-DCMAKE_INSTALL_PREFIX=/opt/Qt/6.2.4-armv7l \
-DQT_FEATURE_opengles2=ON \
-DQT_FEATURE_opengles3=ON \
-DCMAKE_TOOLCHAIN_FILE=tc.cmake \
-DQT_AVOID_CMAKE_ARCHIVING_API=ON ../qtbase-everywhere-src-6.2.4

Check the configuration summary output that everything required was succesfully detected, and if so, you can start the build.

Build Qt 6.2 base

Next up is actually building the sources, that we will do with the following command, adjust the example parallel build (4) as you see fit.

/opt/cmake/bin/cmake --build . --parallel 4

Install Qt 6.2 base

When the build has successfully finnished, the next step is to install the result to the system. To do that run:

/opt/cmake/bin/cmake --install .

Building Qt Documentation

QDoc is required for building and installing documentation for use in various GUI tools. QDoc is part of the qttools submodule and obviously requires Qt itself to build. Documentation can be built afterwards from the build tree so if you do need documentation then don't remove any build results just yet.

Documentation is built with:

/opt/cmake/bin/cmake --build . --parallel 4 --target docs

And installed with:

/opt/cmake/bin/cmake --build . --target install_docs

Building Qt submodules

Qt submodules contains various extra features not included in the base package, for example QtQuick, support for Wayland, CAN-BUS and so forth. For most parts, building the submodules is quite straightforward:

  1. download the source for the submodule you require
  2. extract the archive
    tar xf submodule-version.tar.xz
     
  3. configure sources
    /opt/Qt/6.2.4-armv7l/bin/qt-configure-module .
     
  4. build the sources
    /opt/cmake/bin/cmake --build . --parallel 4
     
  5. install the result
    /opt/cmake/bin/cmake --install .
     

The only thing you need to keep in mind is to build them in the correct order to satisfy various dependencies. The following (incomplete at this time) table describes the required dependency submodules and any development packages that are needed and also the build time on various systems.

 

Development and Qt Submodule dependencies
Module Required submodules Development packages required Description

Build time

Pi 4

Build time

Pine 64

Build time

Pi 3

Build time

AMD Ryzen 3600X

qtbase     Qt core, start with this ~50m 184m    
qtimageformats   libmng-dev libjasper-dev Support for loading various extra image formats        
qtsvg     Support for SVG vector graphics        
qtshadertools     Tools for the cross-platform Qt shader pipeline     ~12m  
qttools qtdeclarative

QDoc requires clang to be installed (See section about documentation above):

clang-9 libclang-9-dev

Various Qt tools:

       
qtserialbus     Serial bus (CAN bus, ModBus) support ~2m      
qtserialport qtserialbus   Serial port support < 1m      
qtlocation qtserialport   Positioning (GPS) and location (Map) services < 3m      
qtdeclarative qtshadertools   Qt Quick / QML ~85m     ~6m
qtmultimedia qtdeclarative

For gstreamer backend:
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

For pulseaudio support:
pulseaudio libpulse-dev

For plain ALSA:
libasound2-dev

Multimedia (audio/video) support

  • Audio playback/recording
  • Video playback
  • Camera picture/video
       
qtsensors qtmultimedia   Support for various device sensors        
qtnetworkauth     Network authentication protocol support (OAuth) < 1m      
qtconnectivity   bluez libbluetooth-dev Bluetooth and NFC connectivity support        
qtwebsockets qtdeclarative   Websockets support ~1m      
qtwebchannel qtwebsockets            
qtcharts qtdeclarative   Charting controls ~10m      
qtwayland   libwayland-dev Wayland support ~10m      
qtvirtualkeyboard qtsvg   Provides on-screen keyboard ~4m      
qtwebengine qtdeclarative flex bison gperf libre2-dev libnss3-dev nodejs libdrm-dev libxdamage-dev libsnappy-dev WebEngine.
Has build issues with old gcc versions.
N/A      
qt5compat     Unsupported Qt 5 compatibility code. ~2m      

TL;DR Building submodules

You can quickly configure, build and install the Qt submodules with (why not do it in simple for loop, I'll leave that as an excerise for the reader!):

/opt/Qt/6.2.4-armv7l/bin/qt-configure-module . && /opt/cmake/bin/cmake --build . --parallel 4 && /opt/cmake/bin/cmake --install .