From Qt Wiki
Jump to: navigation, search

Raspberry Pi (BCM2835): Device Information

Architecture ARMv6
RAM 256MB OR 512MB since October 2012 (shared with GPU)
GPU VideoCore IV
OpenGL OpenGL ES 2.0
Multimedia OpenMax IL 1.1.2
Qt 5.0 (eglfs/QPA) Supported, with OpenGL ES 2.0

Qt 5 port functional state (against Raspbian Wheezy (primary reference platform))

Feature State Additional info
Hardware accelerated cursor Done upstream
Wayland support Done upstream
Hardware decoding of images To Do
Scenegraph tailoring To Do
HardFP support Done Requires v8 patch
Qt Multimedia Done Requires gst-omx
Webkit integration To Do webgl, tex mapper

Additional information

  • "The Raspberry Pi is a credit-card sized computer that plugs into your TV and a keyboard. It’s a capable little PC which can be used for many of the things that your desktop PC does, like spreadsheets, word-processing and games. It also plays high-definition video. We want to see it being used by kids all over the world to learn programming."

Hardware Details

Low end ARM11 CPU running at ~700 BogoMIPS.
VideoCore IV GPU is capable of running QtQuick2/SceneGraph at high resolutions.
Both CPU and GPU share main memory.

Linux Platform

If you are not interested in building everything yourself then consider:

  • the pre-built Raspbian snapshots

The Raspberry Pi Foundation provides a few different distributions which can be downloaded here

Please note: Not all platforms are created equal: The Raspbian Wheezy image is a very functional distro with piping hot firmware and good support on the OS vendor side, so that is the first class citizen when following these instructions. Deviating from its usage will probably introduce additional complexity and will carry you away from the primary testing platform

Raspbian "Wheezy" image (First class citizen)

My home rolled Linaro (crosstool-ng generated) toolchain

Since the Linaro toolchain is an order of magnitude more charismatic when cross compiling, you will probably want to be reading our notes on using it. Since I have to bleed profusely in order to get a functioning Linaro toolchain on my Arch install, I have provided it here


Required changes (Rolling, should be empty)

v8 ARMv6 hardfp support:


Undo crippling GL defaults, possibly stemming from my incorrect indication in the Pi hooks that the GLESv2 impl support GL buffer queuing. One thing is for certain, the consistent timer below is not something you want in affect on your Pi. (On the stage at Qt CS, infront of a crowd, one of whom is whistling the Kill Bill theme)

[sirspudd@bb|:qt5/qtdeclarative]$ git show
commit 82c9f3187ce79e1aef57479b0cc7b7274c0bd85e
Author: Donald Carr <donald.carr@nokia.com>
Date: Wed Aug 8 09:52:34 2012 0000

Disable fixed animation step before it disables me diff —git a/src/quick/items/qquickwindowmanager.cpp
index 3cced7a..90c2dc9 100644
— a/src/quick/items/qquickwindowmanager.cpp
++++ b/src/quick/items/qquickwindowmanager.cpp

137,16 +137,6

QQuickWindowManager *QQuickWindowManager::instance()

 else if (qmlForceThreadedRenderer())
 fancy = true;
- // Enable fixed animation steps…
- QByteArray fixed = qgetenv("QML_FIXED_ANIMATION_STEP");
- bool fixedAnimationSteps = bufferQueuing;
- if (fixed == "no")
- fixedAnimationSteps = false;
- else if (fixed.length())
- fixedAnimationSteps = true;
- if (fixedAnimationSteps)
- QUnifiedTimer::instance(true)->setConsistentTiming(true);
 if (!theInstance) {
 theInstance = fancy
 ? (QQuickWindowManager''') new QQuickRenderThreadSingleContextWindowManager

Toolchain considerations

This is bleeding edge and carries the latest snapshot of the firmware. Anyone doing active development against the BCM libraries will probably want to be living in this realm. Targeting this system requires a Linaro (Raspbian multiarch cognizant) compiler. Without this, you will find yourself scrambling to indicate that relevant libraries are lurking in $lib/arm-linux-gnueabi paths. If you know how to make this play nice, please feel free to edumicate me (Donald Carr) on the niceties.

I built my toolchain by following these instructions:


and an Ubuntu 10.04 schroot. There is no point fighting it, before stooping to this behavior, I was facing spurious build failures all over the show.

Known issues

For qtjsbackend the following patch is needed: usingHardFloat automatic detection faux pas

Arch Linux

Arch has been tested and sommer (just) works. The firmware tends to be bleeding edge, so the Wheezy images firmware notes will possibly be of relevance.


One of our engineers has been investing time in a home rolled hardfp distribution based on Buildroot. The recipe is available here:


Given the preponderance of hardfp performance over its register ignorant peers, this will be useful in eking every last drop of performance out of the hardware.

Building Qt from scratch

Helper scripts

These scripts will be cited at relevant sections and are intended as a rough guide as to the automation of labourious tasks.

Use when prompted at your own discretion.

We generate the nightly Qt snapshots using the following "scripts":git://gitorious.org/packaging-scripts/packaging-scripts.git

These are filthy and exist purely to get the job done with as little effort/time expenditure on our part possible.

Adjusting the root filesystem for development

Qt 5 has a hard dependency on libudev for hot pluggable hardware detection/support. This mandates the installation of the libudev-devel package. (Or the filthy use of an arbitrary libudev.h and the creation of a libudev.so symlink, which is how we roll in the trenches(When life gives you mustard gas, eat franks!)) (This consideration will fall away with the release of the next Raspbian reference image)

In order to use the root filesystem from the SD card, mount the rootfs partition as a loopback device. The offset for mount can change with different images, please query the partition offset with fdisk (see http://www.syslinux.org/wiki/index.php/Hard_disk_images ).

eg (or the official Raspbian image(s)):
$ #mount -o loop,offset=62914560 /opt/stores/broadcom/raspberry-pi/2012-07-15-wheezy-raspbian.img /mnt/rasp-pi-rootfs

In order to be able to use the —sysroot option during the Qt build process, you have to resolve all absolute library links inside the mounted rootfs, but replacing full qualified symlinks with relative ones, otherwise the linker will pickup your host libraries and promptly barf.

The magical fixQualifiedLibraryPaths script in the cross-compile-tools repo above should go some distance to easing this chore. Simply pass it the rootfs and the compiler and it will attempt to fix the symlinks accordingly.

You will also need to create several missing symlinks, notably: libstdc.so (/usr/lib) and libgcc_s.so (/lib) (and any other friends of the forest who rear their frothy maws with the earnest intent to munch on you)

This might seem hacky but it is important that we pass the reference Raspbian image to the code sourcery toolchain to ensure that we are linking against the right system libraries, and not toolchain libs in conflict with the libraries on the actual device.

Additional packages

The additional packages extend the scope of Qt functionality and are optional in as much as the base Raspbian image has all the development files required for GLESv2 and input support.

Additional packages are documented here along with the associated ramifications

I personally install it on the device, shuttle across the .deb, unarchive it and unpack the data.tar.gz over the original mounted image.

Qt 5 on the Raspberry Pi (BCM2835)

Installing Qt 5 nightlies from the repo

We are generating Qt 5 nightlies for the Raspberry PI reference Raspbian image, and these are available here:


this is not currently shipped as part of the Raspbian reference image, and hence

you have to add:

deb http://archive.qmh-project.org/rpi-wheezy/debian unstable main

to your source list and then you need to do to get piping hot Qt 5 action in your life is:

apt-get update apt-get install qt50-snapshot

We generate these packages using this set of scripts

Building Qt

This will build everything in-source, if you want to build out-of-source execute configure and qmake for additional modules from within a separate empty folder.

If you use either squeeze or archlinux, you need to provide the distro name as a device option for the configure script:

-device-option DISTRO=[squeeze,arch]


$ cd <qtbase>
$ ./configure -prefix <your prefix> -release  -device linux-rasp-pi-g''+ -make libs  -device-option CROSS_COMPILE=<your toolchain path>
 -sysroot <your sysroot path>
$ make install

Other modules

Depending on your needs/desires you can now use your freshly minted qmake to (shadow) build whatever Qt 5 modules you require, using the following approach:

$ cd <qt_module_dir>
$ <your prefix>/bin/qmake
$ make
$ make install

At a bare minimum we would recommend: qtjsbackend and qtdeclarative

Runtime information

We would like to get Wayland up and running on the Pi but this requires modifications to EGL that need to be provided by the chipset vendor, Broadcom in this case. We therefore explicit set the default plugin to be the eglfs plugin which is ideal for single process use cases like set top boxes. (This can be overridden by explicitly using -platform if you see fit).

Building and running qtwayland (legacy)

Please note: The current Qt Wayland sha1 is shipped as part of the Wheezy image and simply building the qtwayland module against the Wheezy sysroot should succeed. These instructions persist for the sake of anyone strapped to Raspbian Squeeze or any other distribution.

These instructions cover how to get qtwayland up and running.

First, clone and build qtjsbackend and qtdeclarative per the instructions above.

Now we're going to have to cross compile libffi and wayland. First we need to set up our environment with the following environment variables:

export RPI_SYSROOT=/mnt/rasp-pi-rootfs
export TOOLCHAIN=$HOME/raspberry/arm-2011.09
export QTDIR=$HOME/raspberry/qt5/qtbase
export PREFIX=/opt/myqt
export PKG_CONFIG_PATH="$RPI_SYSROOT/usr/lib/pkgconfig:$RPI_SYSROOT/$PREFIX/lib/pkgconfig:$RPI_SYSROOT/$PREFIX/share/pkgconfig"
export CPP=$TOOLCHAIN/bin/arm-none-linux-gnueabi-cpp
export CC=$TOOLCHAIN/bin/arm-none-linux-gnueabi-gcc
export CXX=$TOOLCHAIN/bin/arm-none-linux-gnueabi-g++
export CFLAGS="—sysroot=$RPI_SYSROOT"
export CXXFLAGS="—sysroot=$RPI_SYSROOT"
export CPPFLAGS="—sysroot=$RPI_SYSROOT"
export LD=$TOOLCHAIN/bin/arm-none-linux-gnueabi-ld
export LDFLAGS="—sysroot=$RPI_SYSROOT"
export AS=$TOOLCHAIN/bin/arm-none-linux-gnueabi-as
export STRIP=$TOOLCHAIN/bin/arm-none-linux-gnueabi-strip
export AR=$TOOLCHAIN/bin/arm-none-linux-gnueabi-ar

Make sure to replace the RPI_SYSROOT, TOOLCHAIN, and QTDIR variables with your equivalents. PREFIX should be whatever you used when configuring Qt above. Now we're ready to cross compile. First, for libffi:

git clone git://github.com/atgreen/libffi.git
cd libffi
./configure —host=arm-linux —prefix=$RPI_SYSROOT$PREFIX
sudo make install

Unfortunately this produces a pkg-config file that has a redundant prefix. Edit $RPI_SYSROOT/$PREFIX/lib/pkgconfig/libffi.pc and remove the $RPI_SYSROOT part from the "prefix=" line, leaving it just as $PREFIX.

As for wayland, we first need to build it for the host to get the wayland-scanner binary which reads wayland extension .xml's and produces C interfaces. You might need to install libffi-dev and libexpat-dev on your host as well for this. You also need to set WAYLAND_SHA1 according to the wayland_sha1.txt in the qtwayland repo, so that we get a compatible version.

Make sure to run these in a clean environment, not the cross compile environment we set up earlier. You may copy wayland-scanner to anywhere as long as it ends up in the $PATH later on.

git clone git://anongit.freedesktop.org/wayland/wayland
cd wayland
git checkout $WAYLAND_SHA1
cp src/wayland-scanner $QTDIR/bin

Now to build wayland for the target. Again make sure the cross compile environment above is sourced. This time we disable the scanner, as we don't want it as an arm binary.

cd wayland
git clean -dxf
./autogen.sh —host=arm-linux —prefix=$RPI_SYSROOT$PREFIX —disable-scanner
sudo make install

Again we need to fix some pkgconfig files. Edit $RPI_SYSROOT/$PREFIX/lib/pkgconfig/wayland-client.pc and wayland-server.pc as for libffi.pc above, removing the $RPI_SYSROOT from the prefix variable. This is required for qtwayland to successfully build.

Now we get to, as we say in Norway, the raisin in the sausage, namely qtwayland. Since we have a hardware integration / buffer sharing mechanism utilizing eglCreateGlobalImageBRCM, we configure it with brcm_egl. This means both raster and opengl based clients will be able to run. The -lffi addition is necessary for some reason I haven't figured out.

export QT_WAYLAND_GL_CONFIG=brcm_egl
cd qtwayland
cd src
make && sudo make install
cd ../examples/
make && sudo make install

I ran into some issues where make failed due to requiring sudo permissions, but following the steps above should give you a working install.

Now it's time to test the stuff we've built. I typically do "rsync -av $RPI_SYSROOT/$PREFIX root@rpi:$PREFIX", but whatever floats your boat.

ssh into the device, and go to the examples/qtwayland/qml-compositor folder, then do as follows:

export XDG_RUNTIME_DIR=/tmp
./qml-compositor -platform eglfs

The XDG_RUNTIME_DIR is where the wayland socket ends up. You should now have the qml-compositor running in all its glory, time to add some clients.

If you've built and installed wiggly from qtbase/examples/widgets/wiggly, here's how to run it:

export XDG_RUNTIME_DIR=/tmp
./wiggly -platform wayland&
./wiggly -platform wayland&

This launches two beautiful wiggly instances as wayland clients. You may also run "qmlscene -platform wayland" on any QML 2 example, or any other Qt OpenGL / QML 2 based application. Bon Appétit!

Building and running Webkit (prone to drowning your pony in a hazard of tentacles)


  • Install the additional dependencies noted above
  • explicitly export PKG_CONFIG_LIBDIR (eg. export PKG_CONFIG_LIBDIR=/mnt/rasp-pi-rootfs/usr/lib/pkgconfig) as Webkit will use pkg-config
  • ./Tools/Scripts/build-webkit —qt —release —no-webgl

Qt 4 on the Raspberry Pi (BCM2835)

Qt 4 runs on the Pi with minor modification and using the following spec: