On this page, we're collecting tips and tricks to make Plasma work on Wayland.

Premises

The idea is to be able to run the same binaries under both, X11 and Wayland. This means that we need to decide at runtime how to interact with the windowing system. The following strategy is useful (in descending order of preference):

Use abstract Qt and Frameworks (KF5) APIs
Use XCB when there are no suitable Qt and KF5 APIs
Decide at runtime whether to call X11-specific functions

X11 as build dependency should be optional, as this is not yet the case, making X11 fully optional (at runtime and at build time) is a goal.

Build instructions

We recommend following this guide to install the Wayland stack, including the QtWayland module

http://qt-project.org/wiki/QtWayland

Generic, but more detailed build instructions for Wayland / Weston, including underlying stack can be found at: http://wayland.freedesktop.org/building.html

Create a wl-env script somewhere in your $PATH, looking like this (adjust WLD to your wayland installation path):

WLD=/home/sebas/kf5/wayland/install
LD_LIBRARY_PATH=$WLD/lib
PKG_CONFIG_PATH=$WLD/lib/pkgconfig/:$WLD/share/pkgconfig/
ACLOCAL="aclocal -I $WLD/share/aclocal"
export YACC=bison

# This is needed for now, as kscreen will otherwise pick the XRandR backend -- and crash
export KSCREEN_BACKEND=fake

export WLD LD_LIBRARY_PATH PKG_CONFIG_PATH ACLOCAL YACC

if test -z "${XDG_RUNTIME_DIR}"; then
    export XDG_RUNTIME_DIR=/tmp/${UID}-runtime-dir
    if ! test -d "${XDG_RUNTIME_DIR}"; then
        mkdir "${XDG_RUNTIME_DIR}"
        chmod 0700 "${XDG_RUNTIME_DIR}"
    fi
fi

Make sure to build your Qt against this updated stack, especially Mesa and libxkbcommon (at the end of Qt's configure, you don't want to see the message that Qt is falling back to the internal 3rdparty copy.

Running KF5 applications under Wayland

Inside an existing X session

weston

starts a new window under your X server with Weston running inside it. You can start Qt5 (and thus KF5 apps) by just adding the parameter "-platform wayland", like this

kwrite -platform wayland

Standalone

From a hard console / virtual terminal:

kf5-env
wl-env
export $(dbus-launch)
weston-launch
kwrite -platform wayland

kf5-env is a script setting up the locations, such as QTDIR, plugin path, etc. for your kf5.

Issues

The following contains a list of issues found when trying to run Plasma or KF5-based software in general under Wayland.

kdeinit5 exits due to missing DISPLAY
kded5 just hangs there when started
Oxygen style works in windowed mode, falls back to Fusion in standalone
File open dialog unable to reach klauncher
After resizing a window, it's not immediately repainted over the new covering area
Icons are missing under Wayland (check with "systemsettings5 -platform wayland", for example)
KScreen has no Wayland backend, calls into KScreen will fail (workaround to make it at least not crash is

export KSCREEN_BACKEND=fake

Font Management KCM crashes when rendering previews, patch to make it not crash (but also not preview fonts) is in git in plasma-desktop[sebas/wayland]

Fixing problems

Guarding X11-specific calls

Since we want to support both, X11 and Wayland with the same binaries, we need to decide at runtime whether or not to call X11-specific functions. We need to guard these calls into X11 libraries as the application will otherwise crash and do something different for non-X11.

    #include <QX11Info>
    // [...]
    if (QX11Info::isPlatformX11()) {
        // You can safely call into X11 libraries here
    } else {
        // Do something smart for non-X11 platforms here
    }