Building Qt 6.6 for Raspberry Pi on Raspberry Pi OS

Guide on how to build Qt 6.6 for use on a Raspberry Pi running Raspberry Pi OS based on Debian 12 Bookworm.

Note: If you are coming from Qt 5, note that 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: 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 sources version of Qt 6.6 release, instead of the all sources in 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 a couple Pi specific configurations that needs to be made, but in short it consist of the following simple steps:

1. Configure Raspberry 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 for Qt base
4. Prepare Qt 6.6 base sources
   1. Downloading Qt 6.6 base sources
   2. Checking the Qt 6.6 base source package integrity
   3. Extract the base sources
5. Configuring the Qt 6.6base build
6. Compiling Qt 6.6 base
7. Installing the Qt 6.6 base
8. Continue to installing any Qt submodules

And for any Qt 6.6 submodules the procedure is about the same as for the base package:

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

Prepare the build tools required

Essentials build packages

As we need to be able to compile and build software from source, make sure all the essential build & compiler tools, cmake and ninja are installed with:

apt install build-essential cmake ninja-build

Install required build dependencies

You will need to install plenty of packages to be able to build Qt 6.6. Some of the Qt 6.6 features are optional and can be either left out 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.

Install all the required development packages with:

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

With Qt 6 you will be using the Mesa and the V3D, VC4 drivers only as support for the proprietary EGL blobs from Broadcom has been dropped in both Raspberry Pi OS and Qt 6.

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.

Install any required packages for the feature you require from the above table with apt install.

Building Qt 6.6 base

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

Download Qt 6.6 base sources

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

Extract the sources:

tar xf qtbase-everywhere-src-6.6.3.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 (armv7 or armv8).

Note: This is not needed if the Qt 6 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):

set(CMAKE_CROSSCOMPILING FALSE)

                                set(CMAKE_SYSTEM_NAME Linux)
                                set(CMAKE_SYSTEM_PROCESSOR armv6)
                                set(TARGET armv6-linux-eabi)

set(CMAKE_CROSSCOMPILING FALSE)
                                set(CMAKE_SYSTEM_NAME Linux)
                                set(CMAKE_SYSTEM_PROCESSOR armv7)
                                set(TARGET armv7-linux-eabi)

set(CMAKE_CROSSCOMPILING FALSE)
                                set(CMAKE_SYSTEM_NAME Linux)
                                set(CMAKE_SYSTEM_PROCESSOR armv8)
                                set(TARGET armv8-linux-eabi)

Configuration options

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

Configure the Qt 6.6 build

Then run the configuration (adjusting prefix if 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 that everything required was successfully detected, and if so, you can start the build of Qt.

Build Qt 6.6 base

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

Note: On the 1 core or low memory systems a parallel build is not recommended.

cmake --build . --parallel 4

Install Qt 6.6 base

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

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:

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

And installed with:

cmake --build . --target install_docs

Building Qt 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.6/bin/qt-configure-module . && cmake --build . --parallel 4 && cmake --install .

For a more in-depth tutorial on building sub-modules, see the Qt sub-module building tutorial.