Contents

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

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

In this case, the environment, especially the DBus session is not set, so we need to make sure there's a dbus session bus available. Doing this before running weston-launch makes it possible for client apps to pick it up within the session.

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

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.