Latest revision as of 09:48, 4 February 2022

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!

Determining and setting the window system that KDE applications use

System Settings > About this System shows

Graphics Platform: Wayland

if running under Wayland, otherwise "X11". Each application's Help > About App name > Components dialog shows either "The xcb windowing system" or "The wayland windowing system".

Forcing KDE apps to run as X11

KWin Wayland supports unmodified X11 applications by implmenting the "XWayland" protocol to provide an X11 server. There are various command-line options to /usr/bin/kwin_wayland to enable and configure this. The X11 applications talk to this server and work reasonably well, though utilities such as clipboard managers and screen capture programs will probably have problems. It should start

To make KDE applications use X11, in a terminal such as Konsole enter

QT_QPA_PLATFORM=xcb /usr/bin/kfontview

replacing kfontview with the path to the application's binary.

It is also possible to restart your KDE window system using the other window system.

noframe

TODO
how to do this? Is it standardized

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 may be printed to stdout, e.g.:

X-Server started on display :1

Normally it picks the next free id, e.g. if the system X11 is on display ":0", it will pick ":1". To run an X11 client application on the nested KWin X11 server, set the DISPLAY variable and set the qpa platform to xcb, e.g.:

DISPLAY=:1 QT_QPA_PLATFORM=wayland 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, as above one just needs to set the qpa platform to wayland, e.g.:

QT_QPA_PLATFORM=wayland kwrite

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"

@@ Line 1: / Line 1: @@
 = What is Wayland? =
-[http://wayland.freedesktop.org Wayland] is a small display server 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.
+[http://wayland.freedesktop.org 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? =
@@ Line 12: / Line 12: @@
 = Wayland Support in Plasma =
-Wayland support in the KDE Plasma Workspaces is still in a pre-alpha 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.
+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 4.11 KWin has some initial Wayland support. It is not yet able to manage Wayland Clients but can use another Wayland compositor as a rendering target instead of X. This is the beginning of a Wayland session compositor running on top of a Wayland system compositor. Instructions on how to test it can be found in [http://blog.martin-graesslin.com/blog/2013/06/starting-a-full-kde-plasma-session-in-wayland/ this blog post].
+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? =
@@ Line 24: / Line 24: @@
 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, KDM, 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!
+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!
-= Building KWin with Wayland support =
+= Determining and setting the window system that KDE applications use =
+System Settings > About this System shows
+: Graphics Platform: Wayland
-Follow the build instructions for Wayland. We assume that Wayland and the dependencies have been installed to $WLD. Now you can compile kde-workspace with Wayland support. Adjust the pkgconfig path to include $WLD/lib/pkgconfig. You need to have development headers for OpenGL ES and EGL around, you may use the ones of your Wayland build.
+if running under Wayland, otherwise "X11". Each application's Help > About ''App name'' > Components dialog shows either "The ''xcb'' windowing system" or "The ''wayland'' windowing system".
-If everything works fine, cmake will tell that the optional build dependencies Wayland and OpenGL ES are found.
+== Forcing KDE apps to run as X11 ==
+KWin Wayland supports unmodified X11 applications by implmenting the "XWayland" protocol to provide an X11 server. There are various command-line options to <code>/usr/bin/kwin_wayland</code> to enable and configure this. The X11 applications talk to this server and work reasonably well, though utilities such as clipboard managers and screen capture programs will probably have problems. It should start
-= Starting KWin with Wayland =
+To make KDE applications use X11, in a terminal such as Konsole enter
+{{Input|1=QT_QPA_PLATFORM=xcb /usr/bin/kfontview
+}}
+replacing <code>kfontview</code> with the path to the application's binary.
-After compiling you can  start KWin with Wayland support. Therefore you need to include the Wayland Server libraries in the LD_LIBRARY_PATH and point the LIBGL_DRIVERS_PATH to your self-compiled version of Mesa 7.11:
+It is also possible to restart your KDE window system using the other window system. {{TODO|how to do this? Is it standardized}}
-LD_LIBRARY_PATH=${WLD}/lib:${LD_LIBRARY_PATH} LIBGL_DRIVERS_PATH=${WLD}/lib/dri/  kwin --replace &
+= Starting a nested KWin =
+Since 5.3 it is possible to start a nested KWin instance under either X11 or Wayland:
+{{Input|1=export $(dbus-launch)
+kwin_wayland --xwayland
+}}
+You can use the <code>--socket</code> 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.
-KWin starts the Wayland Server when OpenGL ES compositing is activated. After that you can start one of the Wayland demo clients. You can also start any Qt application with the Wayland Lighthouse build, but it's difficult to notice a difference to a normal X11 client.
+The option <code>--xwayland</code> is required to start a nested X server. The id of the created X11 Display may be printed to stdout, e.g.:
+{{Input|1=
+X-Server started on display :1
+}}
-= Why not Mir =
+Normally it picks the next free id, e.g. if the system X11 is on display ":0", it will pick ":1". To run an X11 client application on the nested KWin X11 server, set the DISPLAY variable and set the qpa platform to xcb, e.g.:
-The Mir project got announced while KWin was already being ported to Wayland. At that time it was not known whether Mir will succeed or not given that it was in very early development stage. Furthermore it was at that time only a solution for one downstream distribution. This made it unsuited to adjust the development plans. Given that the development continues to focus on Wayland. As long as Mir is a solution for only one downstream distribution the maintenance overhead of adding support is not justified.
+{{Input|1=DISPLAY=:1 QT_QPA_PLATFORM=wayland 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, as above one just needs to set the qpa platform to wayland, e.g.:
+{{Input|1=QT_QPA_PLATFORM=wayland kwrite
+}}
+= 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:
+{{Input|1=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:
+{{Input|1=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'' :
+{{Input|1=tail -f ~/.local/share/sddm/wayland-session.log
+}}
 = I found a bug, what should I do? =
-Open your text editor, fix it and open a review request on [http://git.reviewboard.kde.org Review Board].
+[https://bugs.kde.org 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 [https://phabricator.kde.org/ 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 freenode. There is lots to work on and we can use every helping hand.
+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 =
+* [https://www.proli.net/2020/04/03/developing-kwin-wayland/ "Blog post about developing KWin Wayland"]
 * Presentation on Desktop Summit 2011: [[Media:KWin_Wayland.pdf|Slides]]
+* Presentation at Akademy 2014: [https://conf.kde.org/system/attachments/43/original/kwin-akademy-2014.pdf Slides "The state of KWin/Wayland"]
+* Presentation at Akademy 2015: [https://conf.kde.org/system/attachments/75/original/presentation.pdf Slides "Welcome to Masachusetts"]