Wayland logo

Weston on Raspberry Pi

This is a guide for installing Weston into Raspberry Pi. All commands and compiling are done directly on the Pi. In Raspbian, it is recommended to run Weston as the user 'pi', as Raspbian seems to allow input device access mostly for this user while logged in locally (not via ssh).

However, if you just want to try Weston and not build it, there are packages.

Raspbian packages

There are pre-built Wayland and Weston packages for the Raspbian distribution.

Recent versions of the Raspbian image downloaded from raspberrypi.org already have the raspberrypi.collabora.com repository enabled. At least version 2013-09-25 is confirmed to have it, and in fact that image comes with Weston 1.1.0 pre-installed.

If you need to add the repository manually, add the following line to /etc/apt/sources.list file:

    deb http://raspberrypi.collabora.com wheezy rpi

To install Weston, just issue:

    sudo apt-get update
    sudo apt-get install weston

This will install also a script called weston-launch (not the real weston-launch program), which will automatically set up XDG_RUNTIME_DIR for you and run weston. Running Weston with this package is as simple as:


No need to manually set up environment variables. The firmware notes below are still worth checking, though.

Build dependencies

Assuming you are using the Raspbian distribution, install the build dependencies:

    $ sudo apt-get install build-essential automake libtool bison flex \
    xutils-dev libcairo2-dev libffi-dev libmtdev-dev libjpeg-dev \
    libudev-dev libxcb-xfixes0-dev libxcursor-dev libraspberrypi-dev \
    libxkbcommon-dev libxcb-composite0-dev libpam-dev

On December 4th, 2013, libxkbcommon-dev is not yet found in Raspbian itself, but it is available from the raspberrypi.collabora.com repository, see above.


You may need the latest Raspberry Pi firmware, which you can get with the rpi-update tool. A too old firmware may cause rpi-backend to malfunction on Raspberry Pi. Running rpi-update will overwrite files installed by some raspbian packages like libraspberrypi-dev. You can safely try Weston without rpi-update first, but if you encounter graphics problems, see if it fixes them.

You may want to tweak the following options in /boot/config.txt:

How much memory to reserve for the VideoCore, i.e. framebuffers, GL textures, Dispmanx resources.
This will enable the firmware to fall back to off-line compositing of Dispmanx elements. Normally the compositing is done on-line, during scanout, but cannot handle too many elements. With off-line enabled, an off-screen buffer is allocated for compositing. When scene complexity (number and sizes of elements) is high, compositing will happen off-line into the buffer. Heavily recommended.

Setting up the environment

Here we will install to the home directory of the pi user.

export WLD="$HOME/local"
export PATH="$WLD/bin:$PATH"
export LD_LIBRARY_PATH="$WLD/lib:/opt/vc/lib"
export PKG_CONFIG_PATH="$WLD/lib/pkgconfig/:$WLD/share/pkgconfig/"
export ACLOCAL_PATH="$WLD/share/aclocal"
export ACLOCAL="aclocal -I $ACLOCAL_PATH"

export XDG_RUNTIME_DIR="/run/shm/wayland"
export XDG_CONFIG_HOME="$WLD/etc"
export XORGCONFIG="$WLD/etc/xorg.conf"

mkdir -p "$WLD/share/aclocal"
mkdir -p "$XDG_RUNTIME_DIR"
chmod 0700 "$XDG_RUNTIME_DIR"

You may put the above in a script and source it in the terminal where you wish to build the packages or run Weston.

pkg-config files

Some libraries on the Pi do not have appropriate pkg-config files installed. We need to install them.

Download the .pc files from git://git.collabora.co.uk/git/user/pq/android-pc-files.git and make sure you take the raspberrypi branch. The master branch contains similar files for Android, and will not work.

Copy the .pc files into $WLD/share/pkgconfig/:

    $ cp bcm_host.pc egl.pc glesv2.pc $WLD/share/pkgconfig/

Wayland libraries

Libwayland is built and installed the same way as in the generic build guide.

    $ git clone git://anongit.freedesktop.org/wayland/wayland
    $ cd wayland
    $ ./autogen.sh --prefix=$WLD --disable-documentation
    $ make
    $ make install

The --disable-documentation makes it not require Doxygen.

Weston and demo applications

Weston is configured slightly differently compared to the normal build:

    $ git clone git://anongit.freedesktop.org/wayland/weston
    $ cd weston

    $ ./autogen.sh --prefix=$WLD \
    --disable-x11-compositor --disable-drm-compositor \
    --disable-wayland-compositor \
    --enable-weston-launch --disable-simple-egl-clients --disable-egl \
    --disable-libunwind --disable-colord --disable-resize-optimization \
    --disable-xwayland-test --with-cairo=image \

    $ make
    $ sudo make install

To use weston-launch, the user must be in the weston-launch group. Create the group and add the user pi to it:

    $ sudo addgroup weston-launch
    $ sudo adduser pi weston-launch
    $ logout

You need to log out and then back in to make the group addition effective. You can check that it succeeded with the command id which should now list weston-launch. This needs to be done only once, unlike the environment setup.

On Raspbian, the user also needs to be in the group video to have read and write access to /dev/vchiq.

Weston should work by running weston-launch. Remember to have the environment set up.


Missing bcm_host.pc

checking for RPI_BCM_HOST... no
configure: WARNING: Raspberry Pi BCM host libraries not found, will use stubs instead.

If the right pkg-config files are not installed, building weston can fail. If you see the above during Weston's configure step, the bcm_host.pc file was not found, and the rpi-backend will not work. The following is what you should see:

checking for RPI_BCM_HOST... yes

Build error: undefined reference to `wl_egl_...

Somehow, cairo-egl is getting used, when it should not. Remove the dummy wayland-egl.pc, and make sure --disable-wayland-compositor is in the configure line.

Some or all surfaces (graphics) are corrupted

Too old firmware might cause corrupted graphics. Try upgrading the firmware, and try the /boot/config.txt options mentioned above.

Monitor or TV goes blank, loses signal, etc.

You probably do not have dispmanx_offline=1 for the firmware. When there are too many things on screen for the on-line compositor to handle, the output dies or becomes corrupt without the off-line fallback.

Some windows or the whole image flickers

There may be so many things on screen, that even the off-line compositor in the firmware cannot keep up. Try to close some windows.

Programs are dying on SIGBUS

Most likely you are running out of space in $XDG_RUNTIME_DIR. This is where Wayland programs allocate their pixel buffers.