Wayland logo

Qt 5 on Wayland

Wayland support in the Qt 5 toolkit is happening in the Qt Platform Abstraction (QPA) Wayland plugin. The minimum requirement for building and using QtWayland is Wayland (and Weston) 1.0.0.

If you also want to build the qtwebkit browser, you may be better off following the directions for building Qt 5 from git, which builds a lot more. The init-repository script does not appropriately return an error when it fails (unfortunately frequently), so you need to run it manually and make sure it doesn't print an error.

The third option is the Qt 5 Alpha building instructions, which is smaller and more reliable than the git instructions while still including qtwebkit, but which requires an LD_PRELOAD for Wayland clients:
$ LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libfontconfig.so.1 ./fancybrowser -platform wayland

Getting the source and compiling

To try it out, first clone the qtbase:

$ mkdir qt; cd qt
$ git clone git://code.qt.io/qt/qtbase.git

You might want to set some env variables for compilation as well:

$ export QTVER=qt5
$ export QTDIR=/opt/qt/$QTVER
$ export PATH=$QTDIR/bin/:$PATH
$ export PKG_CONFIG_PATH=$QTDIR/lib/pkgconfig/:$PKG_CONFIG_PATH
$ export QT_PLUGIN_PATH=$QTDIR/lib/plugins/
$ ./configure -confirm-license -opensource -debug -nomake examples \
   -nomake tests -nomake demos -make libs --prefix ${QTDIR}
$ make
$ sudo make install

Here you need to also clone and build qtdeclarative:


To build them run these commands:

$ qmake
$ make
$ sudo make install

At this point you have all needed Qt libraries and needed tools to compile the QtWayland platform:

$ cd ../
$ git clone git://code.qt.io/qt/qtwayland.git
$ cd qtwayland/
$ qmake
$ make
$ sudo make install

Trying it out

First, don't forget to set the XDG directory, as well as the variables set before for compiling Qt, and re-run .bashrc:

$ export XDG_RUNTIME_DIR=$HOME/.xdg
$ mkdir $HOME/.xdg

You can jump back and forth between Wayland and X ("-platform xcb") to compare the look and feel of the application under Wayland and X:

$ cd ../qtbase/examples/opengl/hellowindow
$ qmake
$ make
$ weston &
$ ./hellowindow -platform wayland

Porting your Qt application

Qt 5 is structured with the Lighthouse (or Qt Platform) Abstraction, which is the windowing system and device agnostic architecture. That means Qt can load in run-time different backend plugins for different window systems as desired. For instance, an application developed on Qt could be run using "-platform xcb" and "-platform wayland" for XCB or Wayland respectively (or set the QT_QPA_PLATFORM environment variable) and should have a similar behavior on both systems, without the need to recompile.

Qt abstraction exposes to applications developers two native resources of Wayland: wl_display and wl_surface. With those types, one could access Wayland internals to deal with special cases through the interface:

    void *QPlatformNativeInterface::nativeResourceForWindow(const QByteArray &resource, QWindow *window)

Getting the display global handler is quite straightforward, as shown in the following example:

    QPlatformNativeInterface *native =
    struct wl_display *wl_dpy = (struct wl_display *)
        native->nativeResourceForWindow("display", NULL);

and for wl_surface:

    QPlatformNativeInterface *native =
    struct wl_surface *surface = static_cast<struct wl_surface *>(
        native->nativeResourceForWindow("surface", this->windowHandle()));

Known issues

Getting help and reporting issues

Try the #qt-labs IRC channel on irc.freenode.net