What is Wayland?

Wayland is a small display server protocol and IPC library which is considered to have the chance to replace X11 as primary windowing system. But Wayland is not a direct successor of X and does not follow the design of X. The display server is directly moved into the Compositor (that is KWin) and clients connect to this server through a Unix socket.

Why Plasma needs Wayland?

X has some serious issues and is rather old. The protocol is designed for the usecases three decades ago. Over the last years more and more functionality has been moved from X either into the kernel or into the compositors. The X server is more or less only a proxy between kernel, compositor and the X clients.

Today the compositor does everything the X server used to do. There are some remaining features not yet moved into the compositor (e.g. input handling) but those would make most sense in the compositor. The best situation would be to let the compositor directly work together with the kernel for rendering and input handling and manage the clients directly, which means to remove the Proxy. This is what Wayland is about. More reasons for Wayland in the FAQ.

In Plasma we need Wayland support as we are hitting the limitations of X all the time. Wayland will simplify our architecture and allow us to composite the screen in the way we consider as most useful.

Wayland Support in Plasma

Wayland support in the KDE Plasma Workspaces is in a tech-preview state. The workspaces have been developed for X11 and much functionality relies on X11. To be able to make proper use of Wayland these bits have to be rewritten.

The most complex task is to implement Wayland support in KWin, KDE Plasma's Compositor and Window Manager. Since 5.4 KWin is able to manage Wayland clients and this allows to start a Plasma session on Wayland.

Why not a new Compositor?

Given that KWin was designed as a X11 Window Manager and later as a X11 compositor the question is valid, why not to implement a new Wayland compositor from scratch. Most parts of KWin are X11 independent. E.g. the Desktop Effect system is able to integrate Wayland clients without any change, the same is true for Window Decorations and other parts.

Another reason is that the KWin development team does not have the manpower to maintain an independent X11 window manager and a Wayland compositor. Starting a new Wayland compositor would mean to stop the work on the X11 window manager, which would be a bad move as we cannot know yet whether Wayland will succeed and will be supported on all hardware. Also in future KDE will have to provide an X11 window manager.

KWin is known as one of the most feature complete and most stable window managers. More than a decade of development effort has gone into this Window Manager. Reaching feature parity in a new Wayland compositor seems hardly possible if rewritten from scratch.

Writing a new Wayland Compositor would require to rewrite the complete X11 workspace in one go. This includes not only the Window Manager, but also parts of Plasma, Screen Locker and many, many more. This would take a long development time and the transition would not be smooth, very likely buggy and with regressions like the 4.0 introduction. We do not want to break the desktop!

Starting a nested KWin

Since 5.3 it is possible to start a nested KWin instance under either X11 or Wayland:

export $(dbus-launch)
kwin_wayland --xwayland

You can use the "--socket" option when launching from another Wayland session. It is used to define a different socket name than the one used by the current Wayland session.

The option "--xwayland" is required to start a nested X server. The id of the created X11 Display is printed to stdout, e.g.:

X-Server started on display :1

Normally it picks the next free id, e.g. if the system X is on display ":0", it will pick ":1".

With that it's possible to start an application on the nested X Server, e.g.:

DISPLAY=:1 kwrite

The nested KWin is started on your primary windowing system. E.g. if the DISPLAY environment variable is defined it will start on X11, if the WAYLAND_DISPLAY environment variable is defined it will start on Wayland. It is also possible to explicitly set the system to use by passing command line argument "--x11-display" or "--wayland-display".

To run a Qt application as a Wayland client on this KWin instance, one just needs to set the qpa platform to wayland:

QT_QPA_PLATFORM=wayland kwrite

It is possible to verify whether X11 or Wayland is used in Help -> About Application -> Version

Running on a tty

As an alternative one can also specify which backend to use. On a tty both --drm and --framebuffer are supported, though only --drm provides OpenGL acceleration. If none is specified it will use the DRM backend.

The option "--xwayland" is required to start a nested X server. Normally it picks the next free display id, so if an X Server is running on ":0" it picks ":1".

Once the screen turned black KWin has taken over the display and one can open windows on the Xwayland server. Therefore go to another tty and start an application by passing the correct DISPLAY variable:

DISPLAY=:1 kwrite

Now switching back to the tty KWin is running on should show the started window and allow to interact with it. Support for running KWin on a tty is still in it's early stages. Bugs are to be expected and there are known missing features. Please consider it only as a mode to experiment with.

Start a Plasma session on Wayland

First go to a tty (Press Ctrl+Alt+F3 for instance) and log in. Then run the following command:

dbus-run-session startplasma-wayland

Reading wayland session logs

If you started the wayland session from SDDM, logs are located at ~/.local/share/sddm/wayland-session.log :

tail -f ~/.local/share/sddm/wayland-session.log

I found a bug, what should I do?

Fill a bug! associated with the wayland keyword.

Then if you have the time open your text editor, fix it and open a review request on phabricator. You can find phabricator and arc documentation at https://community.kde.org/Infrastructure/Phabricator

I want to help

Great, get in touch with us either through kwin at kde dot org or plasma dash devel at kde dot org or find us in #kwin or #plasma on Libera Chat. There is lots to work on and we can use every helping hand.

More Information

"Blog post about developing KWin Wayland"
Presentation on Desktop Summit 2011: Slides
Presentation at Akademy 2014: Slides "The state of KWin/Wayland"
Presentation at Akademy 2015: Slides "Welcome to Masachusetts"