Wayland
This article is about the basics of Wayland, like the protocol and core packages. For desktop related software like compositors, launchers, etc, see List of software for Wayland.
Wayland is intended to be a simpler and modern replacement for X display server.
Wayland is now nearly a mature ecosystem. GNOME and KDE have full wayland support and there are numerous independent compositors for those wishing for a more compact set of tools.
"Wayland is a protocol for a compositor to talk to its clients as well as a C library implementation of that protocol. The compositor can be a standalone display server running on Linux kernel modesetting and evdev input devices, an X application, or a wayland client itself. The clients can be traditional applications, X servers (rootless or fullscreen) or other display servers."[1] Where possible, Wayland reuses existing drivers and infrastructure, such as the DRI drivers, the kernel side GEM scheduler and kernel mode setting.
Introduction for users
From a user's point of view, Wayland is nothing more than a framework. In particular, Wayland itself does not implement any display server that should correspond to the Xorg server. In Wayland, compositors are display servers, implemented by various projects. A compositor also serves as X's window manager (and X's compositor).
This means users first have to choose a compositor, and via that compositor they "configure the server", i.e. set screen resolutions, input and video drivers options, etc.
N.B. The Wayland project (as opposed to the protocol) themselves provide the compositor Weston, which is a reference implementation[2] of the Wayland compositor. Though meaningful for developers, Weston is not really meant for users' daily use, being minimal.
Some lack of specification results in chaos more or less. For example one common complaint as of 2021 is that key remapping is absent in the Wayland protocol - in Wayland there is nothing that corresponds to xmodmap of X. Each compositor offers, if any, their own way to remap keys.
The situation however is not totally random - many compositors depend on the library "wlroots", which abstracts such common tasks, and is aimed to be impartial. First started as a subproject of the compositor Sway, it now is used by many compositors. Exceptions include mutter and KWin, i.e. GNOME and KDE, and Weston.
Installation
USE flags
Global
Several packages are aware of the global USE=wayland USE flag.
Local
USE flags for dev-libs/wayland Wayland protocol libraries
Emerge
root #emerge --ask dev-libs/waylandToolkit support
GTK
Wayland is completely supported in GTK 3.22[3]. Nevertheless, when porting application in general two issues must be considered:
- Ensure that the application uses gtk+-3.0 for its pkg-config request.
- All calls to the gdk_x11_ namespace and raw Xlib calls must be wrapped in build-time and run-time backend checks.
More details including plans and progress can be found on the GNOME wiki.
Qt
For Qt an additional package called dev-qt/qtwayland is required. In the Qt Wiki it says: "QtWayland is a Qt 5 module that wraps the functionality of Wayland. QtWayland is separated into a client and server side. The client side is the wayland platform plugin, and provides a way to run Qt applications as Wayland clients. The server side is the QtCompositor API, and allows users to write their own Wayland compositors." To run all Qt applications on the Wayland backend, the environment variable QT_QPA_PLATFORM=wayland needs to be set. This is not necessary if using the Wayland version of KDE Plasma.
Porting Qt applications is much easier than GTK applications. More information on how to use QtWayland can be found at https://wiki.qt.io/Qtwayland and at https://wayland.freedesktop.org/qt5.html.
X-native app support (XWayland)
For X applications to run inside of Wayland, a wrapper called Xwayland is needed and packaged as x11-base/xwayland.
XWayland is an Xorg server that runs as a Wayland client - it runs X11 applications inside of it. See the Wayland docs, Wikipedia, and man Xwayland.
XWayland USE flags
Unfortunately the USE flags for the Xwayland support is not coherent in Gentoo:
| These packages need... | this USE flag for the XWayland support.
|
|---|---|
| dev-libs/weston, x11-wm/enlightenment | xwayland
|
| gui-libs/wlroots, gui-wm/sway | X
|
Troubleshooting
Starting an X11 only app on Wayland
Sometimes it is necessary to start an X11 only application on Wayland.
GTK
When the app uses the GTK toolkit, or when starting an X11 only app from Gnome 3, simply adjust the GDK_BACKEND environment variable as appropriate:
To check the current value:
user $printenv | grep -i GDK_BACKENDGDK_BACKEND=wayland
To temporarily set the value to X11 and start the app, for this example starting the binary Tor browser:
user $GDK_BACKEND=x11 ./start-tor-browser.desktopChecking what apps are running in X11 only mode
root #emerge --ask x11-apps/xlsclientsThen run the following user account:
user $xlsclientshostname java
Setting the screen resolution
If the resolution is not properly detected and cannot be changed from the desktop environment's settings, try to add this to the grub cmdline under /etc/default/grub (change the resolution and depth accordingly like this wightxheightxdepth):
/etc/default/grubGRUB_GFXMODE=1680x1050x24
GRUB_GFXPAYLOAD_LINUX=keep
Then update grub:
root #grub-mkconfig -o /boot/grub/grub.cfgThen reboot.
If that does not work, modify GRUB_CMDLINE_LINUX_DEFAULT and repeat the process:
/etc/default/grubGRUB_CMDLINE_LINUX_DEFAULT="video=VGA-1:1920x1080@60"
Change VGA-1 to HDMI-1, DVI-0, DP-1 or whatever connector the monitor using in the system as well as the resolution and refresh rates.
If you are running the sway compositor, you can instead specify your ideal resoultion with the `mode` argument under the `output` block of whatever the name of your display is in your sway configuration like so:
output HDMI-A-1 {
mode 1920x1080@60Hz
}
For login mangers like SDDM which use xorg, it may be necessary to edit the xorg resolution as specified under Xorg/Guide#Setting the screen resolution.
Running Google Chrome or Chromium in Wayland mode
In order to run Google Chrome or Chromium in native Wayland mode, it should be started with the arguments:
-enable-features=UseOzonePlatform -ozone-platform=wayland
Alternatively, update Preferred Ozone platform to Wayland from chrome://flags/ instead of using the arguments.
It might be necessary that the user is in the video and additionally in the graphics group.
Running Mozilla Firefox in Wayland mode
Starting with Firefox 98, Wayland mode is enabled by default on qualified systems[4]. For older versions, add the following line to your shell's RC file:
user $export MOZ_ENABLE_WAYLAND=1
Running Wayland or X11 applications as a different user
For a pure wayland application, the procedure is relatively simple:
1. Make sure that the new user has at least the permissions rx to the directory $GDK_RUNTIME_DIR (of the logged-in user), the permissions rwx to the socket $WAYLAND_DISPLAY in this directory, and the permissions rw to the lockfile $WAYLAND_DISPLAY in this directory. If the filesystem supports acls and virtual/acl is installed, this can be done as the original user with the commands
user $setfacl -m NEW_USERNAME:r-x -- "$GDK_RUNTIME_DIR"user $setfacl -m NEW_USERNAME:rwx -- "$GDK_RUNTIME_DIR/$WAYLAND_DISPLAY"user $setfacl -m NEW_USERNAME:rw -- "$GDK_RUNTIME_DIRk/$WAYLAND_DISPLAY.lock"2. As the new user, export the path to the original user's socket as WAYLAND_DISPLAY:
export WAYLAND_DISPLAY=/path/to/original_GDK_RUNTIME_DIR/original_WAYLAND_DISPLAY
Both is done by default if app-admin/sudox from the mv overlay is used to change the user permissions.
For an X11 application, things are more complicated: As for native X11, you have to export the MIT cookies. This can be done by using app-admin/sudox to change the user or by copying or giving access to the ~/.Xauthority file.
Unfortunately, many compositors do not start Xwayland with support for cookies: Depending on the compositor, it might be necessary to generate the ~/.Xauthority file manually on startup and to run Xwayland with -auth ~/.Xauthority as the first option (after the display name).
The already mentioned app-admin/sudox provides corresponding startup scripts and desktop files for wayfire.
See also
- List of software for Wayland — various desktop related packages for Wayland - For desktop related softwares.
- Xorg — an open source implementation of the X server.
- Sakaki's EFI Install Guide — includes a tutorial-style chapter covering the installation of GNOME over Wayland (systemd version, OpenRC version).
External resources
- Archlinux wiki article
- QT support
- GTK support
- Wayland Showstoppers - KDE community wiki page about bugs and inconveniences in Wayland