RaspberryPiWithQt6WebEngine

Introduction

This page describes how to set up self-compiled Qt6 with WebEngine on Raspberry Pi 4 running Raspberry Pi OS.

To see other guides visit:

• Qt5 WebEngine cross compilation guide for Raspbian
• Qt6 general cross compilation guide for Raspberry Pi OS
• Qt6 WebEngine general compilation quide for all platforms

Setup

To be able to cross compile Qt6 for Raspberry Pi OS, we need three things:

• Raspberry Pi OS sysroot for arm64 target
• Cross-Compile toolchain
• Qt6 host build

Qt6 uses cmake therefore to cross-compile we need to have actually two builds of Qt. One Qt6 host build, which is later used to cross-compile the arm64 Qt build.

In this guide we are going to cross compile Qt 6.5 with WebEngine coming from Qt 6.7

  Note: As shown here, we could do a 'top level build' of Qt6, but we are going to do 'prefix module build' just to show an alternative way of building Qt6.

We need fours repositories to have Qt 6WebEngine up and running: qtbase, shadertools, qtdeclarative and qtwebengine.

• Let's create our workspace:

  mkdir -p ~/workspaces/rpi/toolchain/sysroot
  mkdir -p ~/workspaces/rpi/toolchain/qt/build/host
  mkdir -p ~/workspaces/rpi/toolchain/qt/build/target
  mkdir -p ~/workspaces/rpi/target
  mkdir -p ~/workspaces/rpi/image
  

• Let's checkout qt source code and select branches:

  cd ~/workspaces/rpi/toolchain/qt
  git clone git://code.qt.io/qt/qtbase.git
  cd qtbase
  git checkout origin/6.5.3
  cd ..
  
  git clone git://code.qt.io/qt/qtshadertools.git
  cd qtshadertools
  git checkout origin/6.5.3
  cd ..
  
  git clone git://code.qt.io/qt/qtdeclarative.git
  cd qtdeclarative
  git checkout origin/6.5.3
  cd ..
  
  git clone git://code.qt.io/qt/qtwebengine.git
  cd qtwebengine
  git checkout origin/6.7
  git submodule update
  cd ..
  

  Note: QtWebEngine needs initialization of the submodule.

Sysroot

To be able to cross-compile, we need a part of arm64 target sysroot to be present on our build machine. As shown here, you could simply start your Rasberry Pi OS on the board and then rsync the required libs and includes to the host machine with SSH connection. However, in this guide we will mount the Raspberry Pi OS image via a loop device, use qemu to install build dependencies and than make a local copy.

  Note: We do need a local copy of 'libs' and 'headers' from the image, as we want to adjust the symlinks.

• Let's now download Raspberry Pi OS:

  cd ~/workspaces/rpi/image
  wget https://downloads.raspberrypi.com/raspios_arm64/images/raspios_arm64-2023-12-06/2023-12-05-raspios-bookworm-arm64.img.xz
  

• Let's extract the image:

  unxz --keep 2023-12-05-raspios-bookworm-arm64.img.xz
  

• We need add at least 2G space to the image to be able to fit qt build with debug info (see here instructions)
• Make loop devices for the image:

  losetup -fP 2023-12-05-raspios-bookworm-arm64.img
  losetup -a
  /dev/loop0: [66306]:2363198 (~/workspaces/rpi/image/2023-12-05-raspios-bookworm-arm64.img)
  

• Mount the root partition:

  mount /dev/loop0p2 -t ext4 ~/workspaces/rpi/target
  mount -t proc /proc ~/workspaces/rpi/target/proc
  mount -t sysfs /sys ~/workspaces/rpi/target/sys
  mount --bind /dev ~/workspaces/rpi/target/dev
  mount --bind /dev/pts ~/workspaces/rpi/target/dev/pts
  

• We need qemu on the image to able to execute command, therefore copy static qemu binary to image.

  cp /usr/bin/qemu-aarch64-static ~/workspaces/rpi/target/usr/bin/
  

  Note: Setup of qemu static interpreter is distribution specific. Please refer to your Linux distribution documentation.

• Chroot to arm64 target:

  cd ~/workspaces/rpi/target
  chroot .
  

• Let's upgrade the image (optional) and install Qt6 build dependencies:

  vi /etc/apt/sources.list
  # uncomment the deb-src lines
  apt update
  apt upgrade
  apt build-dep libqt6gui6
  exit
  

• rsync the parts that we need:

  cd ~/workspaces/rpi/toolchain
  rsync -av ~/workspaces/rpi/target/lib sysroot
  rsync -av ~/workspaces/rpi/target/usr/include sysroot/usr
  rsync -av ~/workspaces/rpi/target/usr/lib sysroot/usr
  

• Adjust symlinks to be relative:

  wget https://raw.githubusercontent.com/Kukkimonsuta/rpi-buildqt/master/scripts/utils/sysroot-relativelinks.py
  chmod +x sysroot-relativelinks.py
  ./sysroot-relativelinks.py sysroot
  

  Note: Command-line tool called symlinks should not be used instead as it creates dangling links.

• Umount no longer needed mounts:

  umount ~/workspaces/rpi/target/sys ~/workspaces/rpi/target/proc 
  umount ~/workspaces/rpi/target/dev/pts ~/workspaces/rpi/target/dev
  

• Detach loop device:

  losetup -d /dev/loop0
  

Toolchain

To cross-compile Qt, we need a cross-compiler toolchain. There are many excellent tools to compile a toolchain, such as crosstool-ng. We could also simply download ready 3dparty toolchain form the internet. However, this guide will use the official gcc cross compiler, which is shipped with Debian distribution, same as the one shipped with Raspberry Pi OS. In time of writing this quide latest Raspberry Pi OS is called 'Bookworm' and it is shipped with gcc 12.2 and Qt 6.4. Therefore we will use the gnu gcc cross compiler from Bookworm release. To setup the cross-compiler toolchain will use 'debootstrap' which is a very convenient tool to install Debian base system into a subdirectory of any other running Linux system. Most of distributions ship this tool therefore it was selected as most generic approach.

  Note: The other approach could be for example installing Debian distribution on VM.

• To setup Bookworm Debian release on your machine execute:

  debootstrap --arch amd64 bookworm ~/workspaces/rpi/toolchain http://ftp.uk.debian.org/debian
  

• Let's mount and chroot into newly created installation:

  mount -t proc /proc ~/workspaces/rpi/toolchain/proc
  mount -t sysfs /sys ~/workspaces/rpi/toolchain/sys
  mount --bind /dev ~/workspaces/rpi/toolchain/dev
  mount --bind /dev/pts ~/workspaces/rpi/toolchain/dev/pts
  
  chroot ~/workspaces/rpi/toolchain /bin/bash
  

• Let's install host and cross compiler:

  apt update
  apt install build-essential crossbuild-essential-arm64
  

Qt6 Host Build

  Note: After toolchain setup, we should be still chrooted into our host Debian root (~/workspaces/rpi/toolchain).

• Let's install dependencies for Qt host build using know dependencies for Qt 6.4:

  apt update
  apt build-dep libqt6gui6
  

  Note: You need 'deb-src http://deb.debian.org/debian bookworm main' line in '/etc/apt/sources.list' file

• Let's configure host build for Qt6 qtbase, build it and install into ~/workspaces/rpi/toolchain/opt/qt:

  cd /qt/build/host
  mkdir qtbase
  cd qtbase 
  /qt/qtbase/configure -release -nomake tests -nomake examples -linker lld -prefix /opt/qt
  cmake --build . --parallel
  cmake --install .
  

  Note: The path /qt/qtbase in chroot is really ~/workspaces/rpi/toolchain/qt/qtbase on the build machine.

• Let's configure and build remaining modules:

  cd /qt/build/host
  mkdir qtshadertools qtdeclarative qtwebengine
  
  cd qtshadertools
  /opt/qt/bin/qt-configure-module ../../../qtshadertools
  cmake --build . --parallel
  cmake --install .
  cd ..
  
  cd qtdeclarative
  /opt/qt/bin/qt-configure-module ../../../qtdeclarative
  cmake --build . --parallel
  cmake --install .
  cd ..
  
  cd qtwebengine
  /opt/qt/bin/qt-configure-module ../../../qtwebengine
  cmake --build . --parallel
  cmake --install .
  cd ..
  

Qt6 Target Cross Build

  Note: After toolchain setup, we should be still chrooted into our host Debian root (~/workspaces/rpi/toolchain).

We should have by now Qt6 host build, target arm64 sysroot and cross compilation toolchain. To setup now cmake build we still need to create 'rpi.toolchain.cmake' file which will provide information to cmake about our toolchian and sysroot setup.