View source for Plasma/Wayland



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.

= Installing from Packages =
If you use a recent distribution, you might get away with installing from packages. That vastly simplifies the whole setup for you. In the current state (meaning: this info might be outdated by the time you read it, in that case, please correct it here!), Debian unstable provides new enough versions. Install libwayland-dev, weston (and perhaps a few others) build Frameworks against it, and you should be good to go.

If you prefer the painful way, or dependencies of your distro don't satisfy our needs (meaning: the build of Frameworks breaks or ignores Wayland due to to low versions), you can build it yourself. 

= 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


This needs to be tweaked a bit to be useful for our purposes. For that, 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

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.

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


= Protocols =

Initial work on protocols for plasmashell, taskbar and KWindowEffects are [https://github.com/plfiorini/protocols here].