Differences between revisions 29 and 45 (spanning 16 versions)
Revision 29 as of 2020-08-07 10:36:53
Size: 10597
Editor: ?sergio
Comment: Riot -> Element
Revision 45 as of 2022-05-03 02:38:15
Size: 14809
Editor: PaulWise
Comment: drop bugs category, Wayland is unrelated
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: English - [[fr/Wayland|Français]] -~
----
= Wayland =
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: English - [[fr/Wayland|Français]] - [[de/Wayland|Deutsch]] -~
----
Line 7: Line 7:
Wayland is a communication protocol that specifies the communication [[https://en.wikipedia.org/wiki/Wayland_(display_server_protocol)|Wayland]]
is a communication protocol that specifies the communication
Line 9: Line 10:
Wayland protocol is called a Wayland compositor, because it additionally
performs the task of a compositing window manager.

The aim of Wayland is replacing the X Window System (Also known as X11, or Xorg)
with a modern, secure, and simpler windowing system. As part of its efforts,
the Wayland project also develops a reference implementation of a Wayland
compositor called Weston.
Major desktops such as KDE Plasma and GNOME have
implemented their own Wayland compositors.
Wayland protocol is called a Wayland compositor, because it additionally 
performs the task of a
[[https://en.wikipedia.org/wiki/Compositing_window_manager|compositing window manager]]
.

The aim of Wayland is replacing the
[[https://en.wikipedia.org/wiki/
X_Window_System|X Window System]]
(Also known as X11, or Xorg) with a modern, secure, and simpler windowing system.
As part of its efforts, the Wayland project also develops a reference
implementation of a Wayland compositor called
[[https://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston|Weston]].
Major desktops such as
[[https://en.wikipedia.org/wiki/
KDE_Plasma_5|KDE Plasma]]
and
[[https://en.wikipedia.org/wiki/
GNOME|GNOME]]
have implemented their own Wayland compositors.
Line 19: Line 27:
== Usage ==
=== Hardware requirements ===
It's important firstly to check your hardware and make sure it's
compatible with your choice of desktop. The divide right now is
strictly between two buffer APIs, GBM and EGLStreams. NVIDIA GPUs
using the proprietary driver support EGLStreams, while all other
graphics cards and driver combinations support GBM. A Wayland
compositor needs to explicitly support one or both of these APIs
= Usage =

== Hardware requirements ==

Firstly, hardware should be checked for compatibility with
a choice of desktop. Buffer [[https://en.wikipedia.org/wiki/API|API]]s currently supported are
[[https://en.wikipedia.org/wiki/Mesa_(computer_graphics)#Generic_Buffer_Management|GBM]]
and [[https://en.wikipedia.org/wiki/EGL_(API)|EGLStreams]].
NVIDIA GPUs using the proprietary driver support EGLStreams, while
all other graphics cards and driver combinations support GBM.
A Wayland compositor needs to explicitly support one or both of these APIs
Line 29: Line 40:
As it stands, GNOME (using Mutter) supports both GBM and EGLStreams well.
KDE Plasma (using KWin) supports GBM in all versions, and EGLStreams since
Plasma 5.16. All other compositors only support GBM and will not function
with the proprietary NVIDIA driver in use.
----
=== Desktops ===
=
=== GNOME ====
As it stands, [[https://en.wikipedia.org/wiki/GNOME|GNOME]]
(using [[https://en.wikipedia.org/wiki/Mutter_(software)|Mutter]])
supports
GBM and EGLStreams well. 
KDE Plasma (using KWin) supports GBM in all versions,
and EGLStreams since  [[https://en.wikipedia.org/wiki/KDE_Plasma_5|Plasma 5.16]].
All other compositors only support
[[https://en.wikipedia.org/wiki/Mesa_(computer_graphics)#Generic_
Buffer_Management|GBM]]
and will not function
with the proprietary NVIDIA driver in use.
----

== Desktops ==

=== GNOME (supported since 3.20+) ===
Line 39: Line 58:
==== KDE ==== As this is the default Debian desktop environment, Wayland is used by default in Debian 10 and newer,
older versions use Xorg by default.

=== KDE Plasma (supported since 5.4+) ===
Line 46: Line 69:
==== Others ====
Other Wayland compositors of interest may include [[sway|Sway]]
(a near drop-in replacement for i3) and DebianPkg:enlightenment.
----
=== Applications ===
==== Introduction ====
=== Enlightenment (unsupported) ===

Support [[https://www.enlightenment.org/about-wayland|being worked on]] upstream.

=== Hawaii (unsupported) ===

=== Cinnamon (unsupported) ===

Support [[https://github.com/linuxmint/Cinnamon/issues/5201|discussed]] upstream.

=== MATE (unsupported) ===

Support [[https://github.com/mate-desktop/mate-wiki/tree/master/pages/wayland.md|planned]], [[https://www.phoronix.com/scan.php?page=news_item&px=MTYwNjQ|source]] (2014), [[https://www.phoronix.com/scan.php?page=news_item&px=MATE-Usable-Wayland-Mir-Video|an update]] (2019)

=== XFCE (unsupported) ===

Support [[https://wiki.xfce.org/releng/wayland_roadmap|being worked on]] upstream.

=== Compositors (supported) ===

Other Wayland compositors of interest may include:

 * DebianPkg:weston (the reference Wayland compositor),
 * DebianPkg:sway (a near drop-in replacement for i3): ([[https://swaywm.org/|website]], [[https://github.com/swaywm/sway|Github project]]) (Will [[https://drewdevault.com/2017/10/26/Fuck-you-nvidia.html|stop]] supporting NVidia EGL/closed source driver from 1.0 onwards.)
 * DebianPkg:enlightenment,
 * [[https://github.com/Drakulix/fireplace|Fireplace]] (no Debian package yet)

=== Window Managers and Compositors (unsupported) ===

 * DebianPkg:i3: [[https://faq.i3wm.org/question/687/i3-support-for-wayland.1.html|FAQ]], [[https://www.reddit.com/r/i3wm/comments/2ucznn/any_i3_support_plans_for_wayland_in_the_neaby/|discussion]].
 * Other X11 window managers unlikely to be supported.

----

== Toolkits ==

=== Introduction ===
Line 61: Line 116:
==== GTK3 ==== To support screenshotting, screencasting and screensharing for example in Web Browsers
DebianPkg:pipewire is required in addition to one of the Desktop specific
DebianPkg:xdg-desktop-portal packages.

=== GTK3 (supported since 3.20+) ===
Line 68: Line 128:
Note that some Electron applications (Slack, Element, Discord, etc.)
may break when setting {{{GDK_BACKEND}}} to "wayland".

==== Qt 5 ====
Note that some Electron applications (Slack, Element, Discord, etc.) or
DebianPkg:chromium (DebianBug:861796)
may break when setting {{{GDK_BACKEND}}}
to "wayland".

=== Clutter (supported) ===

The {{{CLUTTER_BACKEND}}} environment variable, when set to "wayland", will forcibly
run Clutter applications with the Wayland backend.

==
= Qt (supported since 5) ===
Line 76: Line 143:
"wayland,xcb" which will have applications prefer Wayland only use X11 as a "wayland;xcb" which will have applications prefer Wayland only use X11 as a
Line 83: Line 150:
==== SDL2 ==== === SDL1 (unsupported) ===

The toolkit is in maintenance mode, and it will not get Wayland support. There's an SDL1 binary compatible wrapper
that uses SDL2 as its backend (libsdl12-compat), that is being package (DebianBug:985170), that could make any SDL1
application transparently gain Wayland support. Otherwise applications using this toolkit need to be ported to SDL2.
In addition some SDL1 applications might crash if they are started with {{{SDL_VIDEODRIVER}}} set to "wayland".

Here's a tracking list of applications that need porting:

  * DebianPkg:aranym DebianBug:985183
  * DebianPkg:reminiscence DebianBug:985184
  * DebianPkg:edgar DebianBug:985185
  * DebianPkg:glob2 DebianBug:985186

=== SDL2 (supported since 2.0.2+) ===
Line 89: Line 171:
----
=== Display Managers ===
==== GDM3 ====

=== EFL (supported) ===

=== GLFW (supported since 3.2) ===

=== FLTK (unsupported) ===

This toolkit '''does not''' currently support Wayland. The progress is tracked at DebianBug:984620.

----

== Display Managers ==

=== GDM3 ===
Line 99: Line 193:
==== SDDM ==== === SDDM ===
Line 104: Line 199:
==== LightDM ==== === LightDM ===
Line 107: Line 203:
----
== Testing Wayland ==

----

== Applications ==

=== Chromium (supported) ===

Upstream supports Wayland via its new Ozone backend. To turn it on, either run chromium with --ozone-platform=wayland, or edit chrome://flags as described at the end of DebianBug:1003689.

Screen sharing via PipeWire is not yet supported, tracked at DebianBug:954824.

=== Firefox (supported) ===

The {{{MOZ_ENABLE_WAYLAND}}} environment variable can be set to "1" to force using the Wayland backend.

=== LibreOffice (supported, not by default) ===

LibreOffice supports Wayland via its System Abstraction Layer plugins, in packages such as DebianPkg:libreoffice-gtk3, DebianPkg:libreoffice-plasma, DebianPkg:libreoffice-kf5 and DebianPkg:libreoffice-qt5.

By default it will try to detect the current Desktop Environment, which requires the matching SAL backend being installed. If it cannot detect the current Desktop Environment, but detects Wayland in use, it will default to the GTK3 backend, and will segfault if the plugin is not installed.

The {{{SAL_USE_VCLPLUGIN}}} environment variable can be set to one of "gtk3", "kf5" or "qt5" to force the specific backend to use when not using an actual Desktop Environment, such as when using a bare compositor.

=== Java Programs (supported since OpenJDK 16?) ===

Starting with OpenJDK 16, the JRE can dynamically load GTK3 (which has Wayland support), it appears this might be supported according to this [[https://stackoverflow.com/questions/39197208/java-gui-support-on-wayland|discussion]].

The {{{_JAVA_AWT_WM_NONREPARENTING}}} environment variable can be set to "1" to fix misbehavior where the application starts with a blank screen.

=== Emacs (partially supported) ===

Because Emacs is [[http://emacshorrors.com/posts/psa-emacs-is-not-a-proper-gtk-application.html|not a real GTK application]], it still talks with X11 and therefore will use XWayland.

=== Vim (partially supported) ===

Similar to Emacs, progress tracked at DebianBug:819954.

----

= Testing Wayland =
Line 128: Line 263:
----
== Supported environments ==

Desktop environments:

 * GNOME 3.20+ (Wayland used by default in Debian 10 and newer, older versions use Xorg by default)
 * KDE Plasma 5.4+ (Xorg is used by default, Wayland requires the DebianPkg:plasma-workspace-wayland package to be installed)
 * Enlightenment
 * Hawaii

Toolkits:

 * Qt 5
 * GTK+ 3.20+
 * Clutter
 * SDL 2.0.2+
 * EFL
 * GLFW 3.2

Window managers:

 * DebianPkg:sway ([[https://swaywm.org/|website]], [[https://github.com/SirCmpwn/sway|Github project]]) (Will [[https://drewdevault.com/2017/10/26/Fuck-you-nvidia.html|stop]] supporting NVidia EGL/closed source driver from 1.0 onwards.)
 * [[https://github.com/Drakulix/fireplace|Fireplace]] (no Debian package yet)

== Partially supported ==

 * Emacs: because Emacs is [[http://emacshorrors.com/posts/psa-emacs-is-not-a-proper-gtk-application.html|not a real GTK apps]], it still talks with X11 and therefore will use XWayland
 * Vim: similar (DebianBug:819954)

== Unsupported ==

Desktop environments:

 * Cinnamon: [[https://github.com/linuxmint/Cinnamon/issues/5201|discussed]]
 * MATE: [[https://github.com/mate-desktop/mate-wiki/tree/master/pages/wayland.md|planned]], [[https://www.phoronix.com/scan.php?page=news_item&px=MTYwNjQ|source]] (2014), [[https://www.phoronix.com/scan.php?page=news_item&px=MATE-Usable-Wayland-Mir-Video|an update]] (2019)
 * XFCE: [[https://www.reddit.com/r/xfce/comments/4aeqda/xfce_wayland_support/|planned]]

Window managers:

 * i3: [[https://faq.i3wm.org/question/687/i3-support-for-wayland.1.html|FAQ]], [[https://www.reddit.com/r/i3wm/comments/2ucznn/any_i3_support_plans_for_wayland_in_the_neaby/|discussion]].
 * other window managers unlikely to be supported
----
== Xwayland ==

If you have fully switched and want to check whether an application is using native Wayland support or XWayland,
the easiest way is to run the xeyes program, and check whether the eyes still track the cursor when that is inside
the application window.

----

= Xwayland =
Line 174: Line 274:
If you're using the Weston compositor, you may need to add these lines to {{{~/.config/weston.ini}}} If using the Weston compositor add these lines to {{{~/.config/weston.ini}}}
Line 185: Line 285:
----
== Troubleshooting ==

=== Xresources won't load ===

----

= Troubleshooting =

== Xresources won't load ==
Line 197: Line 299:
----
== FAQ ==

=== Why is Wayland necessary? ===

----

= FAQ =

== Why is Wayland necessary? ==
Line 208: Line 312:
=== Applications can't share information with each other... so how do I copy and paste? === == Applications can't share information with each other... so how do I copy and paste? ==
Line 212: Line 316:
=== I'm accustomed to running various programs (e.g. synaptic) as root in my X session. How will this work under Wayland? === == I'm accustomed to running various programs (e.g. synaptic) as root in my X session. How will this work under Wayland? ==
Line 218: Line 322:
=== I run various programs over the network, e.g. through ssh X11 forwarding, or xhost. How will this work under Wayland? === == I run various programs over the network, e.g. through ssh X11 forwarding, or xhost. How will this work under Wayland? ==
Line 222: Line 326:
=== I share monitors between systems using x2x. How will this work under Wayland? === == I share monitors between systems using x2x. How will this work under Wayland? ==
Line 230: Line 335:
----
== Further reading ==

----

= Further reading =

Translation(s): English - Français - Deutsch


Wayland is a communication protocol that specifies the communication between a display server and its clients. A display server using the Wayland protocol is called a Wayland compositor, because it additionally performs the task of a compositing window manager.

The aim of Wayland is replacing the X Window System (Also known as X11, or Xorg) with a modern, secure, and simpler windowing system. As part of its efforts, the Wayland project also develops a reference implementation of a Wayland compositor called Weston. Major desktops such as KDE Plasma and GNOME have implemented their own Wayland compositors.

Usage

Hardware requirements

Firstly, hardware should be checked for compatibility with a choice of desktop. Buffer APIs currently supported are GBM and EGLStreams. NVIDIA GPUs using the proprietary driver support EGLStreams, while all other graphics cards and driver combinations support GBM. A Wayland compositor needs to explicitly support one or both of these APIs in order to function.

As it stands, GNOME (using Mutter) supports GBM and EGLStreams well. KDE Plasma (using KWin) supports GBM in all versions, and EGLStreams since Plasma 5.16. All other compositors only support GBM and will not function with the proprietary NVIDIA driver in use.


Desktops

GNOME (supported since 3.20+)

The Wayland session is built into GNOME and it should be an option in your display manager simply by having GNOME installed.

As this is the default Debian desktop environment, Wayland is used by default in Debian 10 and newer, older versions use Xorg by default.

KDE Plasma (supported since 5.4+)

KDE Plasma requires the non-default plasma-workspace-wayland package to be installed. This is often enough for basic functionality, however you are recommended to read the detailed wiki section for KDE on Wayland, especially if you are using an NVIDIA GPU.

Enlightenment (unsupported)

Support being worked on upstream.

Hawaii (unsupported)

Cinnamon (unsupported)

Support discussed upstream.

MATE (unsupported)

Support planned, source (2014), an update (2019)

XFCE (unsupported)

Support being worked on upstream.

Compositors (supported)

Other Wayland compositors of interest may include:

Window Managers and Compositors (unsupported)


Toolkits

Introduction

GTK3 and Qt 5 applications using the system libraries should default to Wayland automatically. Some that use statically-linked versions of these, or which explicitly disable Wayland support for various reasons (e.g., KeePassXC), will require special flags or environment variables to be set.

Applications using X11 will work fine in Wayland via the Xwayland compatibility layer, however there may be input issues or other bugs introduced. When possible, using an application in its native Wayland mode is preferred.

To support screenshotting, screencasting and screensharing for example in Web Browsers pipewire is required in addition to one of the Desktop specific xdg-desktop-portal packages.

GTK3 (supported since 3.20+)

The GDK_BACKEND environment variable, when set to "wayland", will forcibly run a GTK3 application with the Wayland backend. Similarly, setting the environment variable to "x11" will force it to run with the X11 backend (useful for forcing applications to use Xwayland that have compatibility issues when operating in their native Wayland mode).

Note that some Electron applications (Slack, Element, Discord, etc.) or chromium (861796) may break when setting GDK_BACKEND to "wayland".

Clutter (supported)

The CLUTTER_BACKEND environment variable, when set to "wayland", will forcibly run Clutter applications with the Wayland backend.

Qt (supported since 5)

The qtwayland5 package will install the relevant platform plugin allowing Wayland apps to run natively with Qt.

You are recommended to set the environment variable QT_QPA_PLATFORM to "wayland;xcb" which will have applications prefer Wayland only use X11 as a fallback. You can, of course, set this to also be specifically either "wayland" or "xcb" if you want to force one.

The -platform wayland flag can also be used as a simpler means to force most Qt applications to use the Wayland backend.

SDL1 (unsupported)

The toolkit is in maintenance mode, and it will not get Wayland support. There's an SDL1 binary compatible wrapper that uses SDL2 as its backend (libsdl12-compat), that is being package (985170), that could make any SDL1 application transparently gain Wayland support. Otherwise applications using this toolkit need to be ported to SDL2. In addition some SDL1 applications might crash if they are started with SDL_VIDEODRIVER set to "wayland".

Here's a tracking list of applications that need porting:

SDL2 (supported since 2.0.2+)

For games, applications, or other software that uses SDL2 as a toolkit, set the SDL_VIDEODRIVER environment variable to "wayland". Note that doing this on a system-wide basis isn't recommended, as many proprietary applications use statically-linked versions of SDL2 that are older and may break when forcing the usage of Wayland.

EFL (supported)

GLFW (supported since 3.2)

FLTK (unsupported)

This toolkit does not currently support Wayland. The progress is tracked at 984620.


Display Managers

GDM3

GDM (GNOME Display Manager) will automatically use Wayland when supported, except when using the proprietary NVIDIA driver, in which case it will fall back to X11 due to instability.

To use the X11 backend by default, uncomment the WaylandEnable=false line in the /etc/gdm3/daemon.conf file.

SDDM

Wayland support for SDDM itself is in progress, currently it uses X11 by default everywhere. SDDM is still capable of starting a Wayland session for a desktop however.

LightDM

There is little hope of LightDM obtaining native Wayland support, however it can still start a Wayland session for a desktop.


Applications

Chromium (supported)

Upstream supports Wayland via its new Ozone backend. To turn it on, either run chromium with --ozone-platform=wayland, or edit chrome://flags as described at the end of 1003689.

Screen sharing via PipeWire is not yet supported, tracked at 954824.

Firefox (supported)

The MOZ_ENABLE_WAYLAND environment variable can be set to "1" to force using the Wayland backend.

LibreOffice (supported, not by default)

LibreOffice supports Wayland via its System Abstraction Layer plugins, in packages such as libreoffice-gtk3, libreoffice-plasma, libreoffice-kf5 and libreoffice-qt5.

By default it will try to detect the current Desktop Environment, which requires the matching SAL backend being installed. If it cannot detect the current Desktop Environment, but detects Wayland in use, it will default to the GTK3 backend, and will segfault if the plugin is not installed.

The SAL_USE_VCLPLUGIN environment variable can be set to one of "gtk3", "kf5" or "qt5" to force the specific backend to use when not using an actual Desktop Environment, such as when using a bare compositor.

Java Programs (supported since OpenJDK 16?)

Starting with OpenJDK 16, the JRE can dynamically load GTK3 (which has Wayland support), it appears this might be supported according to this discussion.

The _JAVA_AWT_WM_NONREPARENTING environment variable can be set to "1" to fix misbehavior where the application starts with a blank screen.

Emacs (partially supported)

Because Emacs is not a real GTK application, it still talks with X11 and therefore will use XWayland.

Vim (partially supported)

Similar to Emacs, progress tracked at 819954.


Testing Wayland

To test Wayland, you will need to have a compatible compositor installed. A Wayland compositor combines the roles of the X window manager, compositing manager and display server. Most major desktops support Wayland well, but for testing purposes, weston is the reference implementation of the concept.

You can test Weston directly from a regular X session simply by installing the weston package and then running weston in a terminal session. This will start a Wayland window in your regular X session where you can test things.

You can also test GNOME's mutter Wayland compositor directly:

mutter --nested --wayland

Then further Wayland clients will show up in that window. Try, for example, starting gnome-terminal.

If you have fully switched and want to check whether an application is using native Wayland support or XWayland, the easiest way is to run the xeyes program, and check whether the eyes still track the cursor when that is inside the application window.


Xwayland

For backwards compatibility, any X program will run under Xwayland. Install the xwayland package if it wasn't brought in by your desktop of choice.

If using the Weston compositor add these lines to ~/.config/weston.ini

[core]
xwayland=true

[xwayland]
path=/usr/bin/Xwayland

The security and performance improvements of Wayland are not be obtained with Xwayland.


Troubleshooting

Xresources won't load

This is a known issue. Back in 2015, it was decided that the resources were too slow to load and that was dropped from the main GNOME session, see Redhat's bugzilla for more information.

Workaround: run this by hand or setup something to start it up automatically on session login.

xrdb -load .Xsession


FAQ

Why is Wayland necessary?

Wayland allows better isolation between processes: one window cannot access resources from, or inject keystrokes into, another window.

Wayland also has the potential to be faster, by reducing the amount of code between the processes and the hardware, by delegating lots of things to the processes themselves.

See also the Wayland FAQ for more information.

Applications can't share information with each other... so how do I copy and paste?

The clipboard should work like normal between X11 and Wayland applications in most sessions, however it's up to the Wayland compositor to negotiate this.

I'm accustomed to running various programs (e.g. synaptic) as root in my X session. How will this work under Wayland?

(In fact, synaptic was temporarily removed from buster because it didn't work under Wayland.)

There are plans to allow X11 applications running as root to use XWayland but native Wayland applications need to be restructured into a GUI part and a root part.

I run various programs over the network, e.g. through ssh X11 forwarding, or xhost. How will this work under Wayland?

SSH X11 forwarding works like before for X11 applications via XWayland. Native Wayland applications are not forwarded.

I share monitors between systems using x2x. How will this work under Wayland?

Screen sharing with Wayland is in the preliminary stages. Currently, the most progress has been made in Chromium where pipewire and xdg-desktop-portal can be leveraged for screen sharing in WebRTC. With these packages installed, WebRTC PipeWire support must still be enabled in the Chromium flags, as can be found by entering in the address bar: chrome://flags/#enable-webrtc-pipewire-capturer


Further reading


CategoryDesktopEnvironment