Building QT6 from Source on Raspberry Pi

This article will guide you through building QT6 from source on Raspberry Pi. QT is a cross-platform application framework that allows developers to create user interfaces and applications that run on various platforms, including Raspberry Pi.

Preparation

Hardware Requirements

You need to prepare the following hardware:

• A Raspberry Pi (32-bit or 64-bit)

• An SD card with Raspberry Pi OS installed

• An Ethernet cable or Wi-Fi connection

• A computer that can access the Raspberry Pi

Software Requirements

You need to install the following software on Raspberry Pi:

• Raspberry Pi OS (based on Debian 12 Bookworm)

• Build tools and compiler tools (cmake and ninja-build)

You can install these packages using the following commands:

sudo apt update
sudo apt install build-essential cmake ninja-build

Installing Required Build Dependencies

You need to install a large number of packages to build QT 6.6. Some QT 6.6 features are optional and can be included or excluded based on your specific needs.

First, update your apt package cache:

sudo apt update

Then proceed to install the following required packages:

Development Package	Description
libfontconfig1-dev	Font configuration library
libharfbuzz-dev	OpenType text shaping engine
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 main loop support

You can install all required development packages using the following command:

sudo apt install libfontconfig1-dev libharfbuzz-dev libdbus-1-dev libfreetype6-dev libicu-dev libinput-dev libxkbcommon-dev libsqlite3-dev libssl-dev libpng-dev libjpeg-dev libglib2.0-dev

Raspberry Pi Graphics Environment and Driver Options

In QT 6, you will only be able to use Mesa and V3D, VC4 drivers, as both Raspberry Pi OS and QT 6 have dropped support for Broadcom’s proprietary EGL blob.

Graphics Driver Options

Graphics Driver	Required Packages	Description
V3D and VC4 drivers	libgles2-mesa-dev libgbm-dev libdrm-dev	QT_FEATURE_kms=ON ** QT_FEATURE_opengles2=ON
QT_FEATURE_opengles3=ON
Vulkan support for V3D driver only on Raspberry Pi 4 and 5	libvulkan-dev vulkan-tools	QT_FEATURE_vulkan=ON
X11	See below	QT_FEATURE_xcb=ON
Wayland	See below	Please note that Wayland support is located in the qtwayland submodule.

Optional Basic Feature Dependencies

Some features are not strictly required but may still be practical, such as support for webp image format is optional, but it is now widely used, so it may be best to include it.

The following table lists some optional features and the required development packages to install.

Optional features for basic QT**

Optional Feature	Packages to Install	Configuration Options
PostgreSQL database support	libpq-dev
MariaDB /MySQL database support	libmariadb-dev libmariadb-dev-compat
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 libxcb-cursor-dev	QT_FEATURE_xcb=ON
Wayland	libwayland-dev
	libzstd libzstd-dev
GTK 3 theme support	libgtk-3-dev
Accessibility	libatspi2.0-dev
SCTP** Stream Control Transmission Protocol	libsctp-dev	QT_FEATURE_LABEL_sctp

Use apt install to install any packages needed for the features you require from the table above.

Building QT 6.6 Base Modules

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

Download QT 6.6 Base Source Code

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

Configure, Build and Install QT 6.6 Base Modules

Extract the source code:

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

Create a build directory:

mkdir qtbasebuild && cd qtbasebuild

Optional: Create a cmake toolchain file

If you are building for a different architecture type than the build system, for example, you will run QT on an armv6-based Pi but build on a faster device (armv7 or armv8), you may need to create a cmake toolchain file.

Note: ** This is not needed if the QT 6 build will run on the same architecture as the build. For example, if you are building on a 32-bit armv7 Pi and intend to run QT on armv7 or later, you don’t need a toolchain file.

To create a cmake toolchain file named tc.cmake, start your preferred editor. Create the file somewhere that won’t be deleted, such as in the install prefix you use, because it will be referenced by QT build files during installation. The file contents depend on the 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	TBD

Configuration Options

QT can be customized in various ways when building, the following table shows some options that can be used 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 QT 6.6 Build

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

cmake -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX= */opt/Qt/6.6*  \
-DQT_FEATURE_opengles2=ON \
-DQT_FEATURE_opengles3=ON \
-DQT_FEATURE_kms=ON \
-DQT_FEATURE_xcb=ON \
-DQT_FEATURE_vulkan=ON \
*-DCMAKE_TOOLCHAIN_FILE=tc.cmake*  \
-DQT_AVOID_CMAKE_ARCHIVING_API=ON ../qtbase-everywhere-src-6.6.3

Check the configuration summary output to ensure all required items have been successfully detected, and if successful, you can start building QT.

Build QT 6.6 Base Modules

Next is the actual compilation of the source code, we will use the following command to do this, adjusting the example parallel build (4) as needed.

Note: ** Parallel builds are not recommended on single-core or low-memory systems.

cmake --build . --parallel 4

Install QT 6.6 Base Modules

After the build completes successfully, the next step is to install the results into your system. To install the compiled QT, run:

cmake --install .

Building QT Documentation

QDoc is an essential tool for building and installing documentation for use by various GUI tools. QDoc is part of the qttools submodule and obviously requires QT itself to build. Documentation can be built from the build tree later, so if you do need documentation, don’t delete any build results for now.

Build the documentation using the following command:

cmake --build . --parallel 4 --target docs

And install using the following command:

cmake --build . --target install_docs

Build Time for QT Base Modules

Comparison of build times for QT base modules on various systems

Module	Pi 5	Pi 4	32-bit RISC-V SoC	Rockchip RK3328	Pi 3	AMD Ryzen 3600X
qtbase	~40 minutes	~50 minutes	~3 hours			~6 minutes

Building QT Submodules

You can quickly configure, build and install QT submodules using the following command (why not do it in a simple for loop, I’ll leave that as an exercise for the reader!):

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

For a more in-depth tutorial on building submodules, see the QT Submodule Build Tutorial.

Conclusion

In this tutorial, we learned how to build QT 6.6 from source on Raspberry Pi. We covered installing necessary dependencies, configuring the build process, and building and installing QT base modules and submodules. You should now be able to develop and run QT-based applications on Raspberry Pi.