Cross-compile and deploy Qt 5.12 for Raspberry Pi

Helpful? spread the word!

• Author
• Recent Posts

Javier Bonilla

Researcher at CIEMAT - PSA

PhD. in Computer Science / Solar Thermal Energy Researcher

Latest posts by Javier Bonilla (see all)

• Flutter on Raspberry Pi with flutter-pi - 26 November, 2019
• ESP8266 NodeMCU pinout for Arduino IDE - 19 November, 2019
• Cross-compile and deploy Qt 5.12 for Raspberry Pi - 17 November, 2019

Qt 5.12 is a long-term support (LTS) release of the popular Qt framework. If you are not familiar with it, Qt is a rich framework with plenty of ready-to-use multi-platform components for diverse areas such as multimedia, network, connectivity, graphics, and much more.

In this tutorial, you will learn how to cross-compile Qt 5.12 for Raspberry Pi in your computer and install it in your Raspberry. This will allow you to design and build your Raspberry Pi apps in your computer thanks to Qt Creator and, execute and debug them directly in your Raspberry Pi. Qt creator is a powerful multi-platform Integrated Development Environment (IDE) to create and deploy your Qt apps and it is available for Linux, macOS and Windows.

Article updates

Hardware

This tutorial considers Raspberry Pi 3 model B+ and Qt 5.12 branch, however these instructions should be similar for new Qt releases, as well as other Raspberry Pi board versions. The desktop Operating System (OS) is Linux (it works in most common Linux distributions: Ubuntu, openSUSE, Debian, Fedora, etc.) and the Raspberry Pi OS is Raspbian Buster, any version works (Raspbian Stretch is also supported). Again, the tutorial steps should be quite similar in other configurations.

• Raspberry PI 3 Model B+
• Raspberry Pi Zero WH (WiFi and pre-soldered header)

These are affiliate links. This means if you click on the link and purchase the promoted item, we will receive a small affiliate commission at no extra cost to you, the price of the product is the same. We would really appreciate your support to our work and website if this is fine for you.

Note: this tutorial works for Qt 5.12 and 5.12.2 to 5.12.5 (it doesn’t for 5.12.1 due to some bugs). For Qt 5.12.2 to 5.12.5, the build configuration file must be set to linux-rasp-pi-g++ instead of linux-rasp-pi3-g++ in the -device argument. This is also mentioned below in the step 6. Stay tuned for updates about new versions. Also, have a look at the comments below for new findings.

It is assumed that you have a SD card with Raspbian strech installed in your Raspberry Pi, otherwise download it and follow the installation guide. Also, check that you have the latest firmware, or install it and reboot the system. Execute the following command in the Raspberry Pi command-line interface for updating the firmware.

sudo rpi-update
reboot

Make sure that you have activated the Secure Shell (SSH) protocol in Raspbian. We will need it later to comunicate Qt Creator with your Raspbery Pi.

 sudo raspi-config

Select Interfacing Options, select ssh, choose yes and finish.

The following list summarizes the main steps to cross-compile Qt 5.12 for Raspberry Pi, we will be describing each of them in this post. The [Pi] label means this action is done in the Raspberry Pi, whereas [Co] means it has to be performed in you computer.

1. Install development libraries – [Pi]
2. Prepare target folder – [Pi]
3. Create working folder and set a toolchain – [Co]
4. Create and configure a sysroot – [Co]
5. Download Qt – [Co]
6. Configure Qt for cross compilation – [Co]
7. Compile, install and deploy Qt – [Co]
8. Setup Qt Creator for Raspberry Pi cross compilation – [Co]

1. Install development libraries – [Pi]

We need to install some development libraries, so the first thing to do is to allow the system to install source packages, for this you only have to uncomment the deb-src line in the /etc/apt/sources.list file, which configures the system repositories. Use your favorite text editor for this, we are using nano in this example.

sudo nano /etc/apt/sources.list

The next step is to update and install the required development packages.

sudo apt-get update
sudo apt-get build-dep qt4-x11
sudo apt-get build-dep libqt5gui5
sudo apt-get install libudev-dev libinput-dev libts-dev libxcb-xinerama0-dev libxcb-xinerama0

2. Prepare target folder – [Pi]

This step just involves creating a folder in our Raspberry Pi for the pi user. This folder (/usr/local/qt5pi) will be used to deploy Qt from our computer to the Raspberry Pi.

sudo mkdir /usr/local/qt5pi
sudo chown pi:pi /usr/local/qt5pi

3. Create working folder and set a toolchain – [Co]

Create a working folder in your computer and download the toolchain.

mkdir ~/raspi
cd ~/raspi
git clone https://github.com/raspberrypi/tools

4. Create and configure a sysroot – [Co]

A sysroot is a directory structure that includes all the folders needed to run a particular system. We are creating here a sysroot for Raspberry Pi cross compilation in our computer.

mkdir sysroot sysroot/usr sysroot/opt

We can use rsync to synchronize our computer sysroot and the Raspberry Pi. So, if we make changes in our computer sysroot, they can be easily transferred to our Raspberry Pi; raspberrypi_ip is the network interface name or IP address of your Raspberry Pi.

rsync -avz pi@raspberrypi_ip:/lib sysroot
rsync -avz pi@raspberrypi_ip:/usr/include sysroot/usr
rsync -avz pi@raspberrypi_ip:/usr/lib sysroot/usr
rsync -avz pi@raspberrypi_ip:/opt/vc sysroot/opt

Next, we need to adjust our symbolic links in sysroot to be relative since this folder structure is in both our computer and Raspberry Pi.

wget https://raw.githubusercontent.com/riscv/riscv-poky/master/scripts/sysroot-relativelinks.py
chmod +x sysroot-relativelinks.py
./sysroot-relativelinks.py sysroot

5. Download Qt – [Co]

Download and untar Qt 5.12.5 or any other version you want to use.

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

6. Configure Qt for cross compilation – [Co]

Note: In new Raspbian versions, EGL libraries have different names than those assumed in Qt configuration files, so edit the ./qtbase/mkspecs/devices/linux-rasp-pi-g++/qmake.conf file and substitute all references to -lEGL and -LGLESv2 for -lbrcmEGL and -lbrcmGLESv2, respectively.

The linux-rasp-pi3-g++ (Qt 5.12) or linux-rasp-pi-g++ (Qt 5.12.2 to Qt 5.12.5) folder applies to Raspberry Pi 3 version, if you have a different board version check the list of compatible devices which can be found in ./qtbase/mkspecs/devices and in the table below (summarized from the table in the tutorial to build Qt 5.12 for Raspbian directly on Raspberry Pi).

An alternative way to fix the issue with the EGL libraries (copying and moving them) is given at Qt Wiki – RaspberryPi2EGLFS – step 14.

The following command configure the open-source Qt version for cross compilation. Again, the particular device is set by the -device argument in this case linux-rasp-pi-g++, set the appropriate value for your board version. You can omit the compilation of problematic or time consuming modules using the -skip argument. In this case, we have omitted the compilation of the qtwayland, qtlocation and qtscript modules.

Note: For Qt 5.12.2 to 5.12.5, the build configuration file must be set to linux-rasp-pi-g++ instead of linux-rasp-pi3-g++ in the -device argument.

./configure -release -opengl es2 -device linux-rasp-pi-g++ -device-option CROSS_COMPILE=~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin/arm-linux-gnueabihf- -sysroot ~/raspi/sysroot -opensource -confirm-license -skip qtwayland -skip qtlocation -skip qtscript -make libs -prefix /usr/local/qt5pi -extprefix ~/raspi/qt5pi -hostprefix ~/raspi/qt5 -no-use-gold-linker -v -no-gbm

For a successful configuration, verify that the build options includes EGFLS for Raspberry Pi.

Build options:
......
QPA backends:
  ......
  EGLFS .................................. yes
  EGLFS details:
    ......
    EGLFS Raspberry Pi ................... yes
    ......

7. Compile, install and deploy Qt – [Co]

The exact compilation time depends on your computer performance. This process can take up to 2 or 3 hours in nowadays common computers. Compiler processes can be executed in parallel by means of the j flag. For four make processes, execute: make -j 4.

make
make install

Once Qt is compiled, it can be deployed to your Raspberry Pi using the rsync command.

rsync -avz qt5pi pi@raspberrypi_ip:/usr/local

Note: You may face some errors during the compilation the Qt 5.12 process due to some bugs. They have been already patched in Qt 5.12.1, but this tutorial currently doesn’t work for this version. You may prefer to compile the newest Qt 5.12.2 to Qt 5.12.5 versions to avoid these bugs.

The procedure to fix these bugs for Qt 5.12 consists in downloading Qt 5.12.1 and overwriting the same files in your Qt 5.12.0 source folder. You can find a list of the bugs you may face below together with the files you need to update.

qendian – QTBUG-71945

• qtbase/src/corelib/global/qendian.cpp
• qtbase/src/corelib/global/qendian.h

qquicktableview – QTBUG-71998

• qtdeclarative/src/quick/items/qquicktableview.cpp

qconnectionfactories – QTBUG-72991

• qtremoteobjects/src/remoteobjects/qconnectionfactories.cpp

qquickcontrol – QTBUG-73308

• qtquickcontrols2/src/quicktemplates2/qquickcontrol.cpp

qvirtualkeyboardselectionlistmodel – Qt bug?

• qtvirtualkeyboard/src/virtualkeyboard/qvirtualkeyboardselectionlistmodel.cpp

8. Setup Qt Creator for Raspberry Pi cross compilation – [Co]

If you do not have installed Qt Creator, follow the instructions in the Qt download page to download and install it. Then, follow these instructions to configure cross-compilation support.

First, open Qt Creator, go to the Tools -> Options menu, select the Devices section and Devices tab. Add a new Generic Linux Device.

Set a name for the configuration (Raspberry Pi), the network name or IP, the username (pi) and password (by default raspberry).

Before you finish the wizard, the connection to your Raspberry Pi will be verified and you will have then a new device configured in Qt Creator.

Next, go to the Kits section and Compilers tab, Add GCC C and C++ cross compilers for Raspberry Pi.

The path for the GCC C Raspberry Pi compiler is ~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/arm-linux-gnueabihf/bin/gcc.

The path for the GCC C++ Raspberry Pi compiler is the same as for the GCC C compiler.

Next, go to the Debuggers tab, and Add a debugger, set its path to ~/raspi/tools/arm-bcm2708/arm-rpi-4.9.3-linux-gnueabihf/bin/arm-linux-gnueabihf-gdb.

Go to the Qt Versions tab and Add a new version: Qt 5.12 (Raspberry Pi), set the qmake path to ~/raspi/qt5/bin/qmake.

Finally, go to the Kits tab, Add a new kit, set the name and icon you prefer, and pay attention to the following configuration:

• Device type: Generic Linux Device
• Device: Raspberry Pi (defaut for Generic Linux)
• Sysroot: ~/raspi/sysroot
• Compiler C: GCC (Raspberry Pi)
• Compiler C++: GCC (Raspberry Pi)
• Debugger: GDB (Raspberry Pi)
• Qt version: Qt 5.12 (Raspberry Pi)

All the configuration is already done. You can test your configuration by creating anew project and selecting the previously defined kit configuration: Raspberry Pi.

Congratulations! You can now design, build and deploy your Qt Raspberry Pi apps in you computer and, execute and debug them directly in your Raspberry Pi.