Wayland

Resources

Home

Wikipedia

gitweb in freedesktop.org

Note
This is a general introduction to Wayland. For information about Wayland-related software, such compositors, launchers, etc., refer to the List of software for Wayland.

Wayland is a replacement for the X11 window system protocol and architecture with the aim to be easier to develop, extend, and maintain:

Wayland is the language (protocol) that applications can use to talk to a display server in order to make themselves visible and get input from the user (a person). A Wayland server is called a "compositor". Applications are Wayland clients.

Wayland also refers to a system architecture. It is not just a server-client relationship between a compositor and applications. There is no single common Wayland server like Xorg is for X11, but every graphical environment brings with it one of many compositor implementations. Window management and the end user experience are often tied to the compositor rather than swappable components.

GNOME and KDE have full Wayland support: GNOME provides the Mutter compositor, and KDE provides the KWin compositor. However, there are also various independent compositors available, including a number based on the wlroots library.

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 analogous to the Xorg server. Individual Wayland compositors, implemented by various projects, combine the functionality of a display server with the functionality of a window manager (WM).

Thus, using Wayland involves choosing a compositor, and configuring that compositor to "configure the server", i.e. set screen resolutions, input and video drivers options, etc.

The reference implementation compositor is Weston. However, Weston is minimal and intended primarily for developers, rather than for end-users.

In addition to the core Wayland specifications, various extension specifications are being developed. The Wayland explorer site provides information about the specifications, and the extent to which they are implemented by some of the main compositors (including KWin, Mutter and Sway). A particular compositor not implementing certain functionality doesn't necessarily mean that other compositors don't support it, nor that it's not possible under Wayland.

Nonetheless, this situation means there might not (yet) be standard ways of doing certain things: for example, Wayland currently has nothing corresponding to X's xmodmap(1), with each compositor providing its own way to remap keys (if it does so at all).

However, the wlroots library is used as a common base by a number of compositors, including Sway (from which it was originally derived), dwl, Hikari, Hyprland, and Wayfire. Neither Mutter, the GNOME Wayland compositor, nor KWin, the KDE Wayland compositor, use wlroots; both are independent implementations.

Installation

USE flags

Global

Several packages are aware of the global wayland USE flag.

Local

USE flags for dev-libs/wayland Wayland protocol libraries

doc	Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
test	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)

Data provided by the Gentoo Package Database · Last update: 2024-01-12 14:36 More information about USE flags

Emerge

root #emerge --ask dev-libs/wayland

Toolkit support

GTK

Wayland is completely supported in GTK 3.22. 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.

Running X-only applications via Xwayland

Some applications do not yet support running on Wayland. Xwayland(1) is an X server that runs as a Wayland client, allowing the use of X-only applications in a Wayland environment. For further information, please refer to the Xwayland page.

Additionally, some X-only GTK applications might require the GDK_BACKEND environment variable to be set to x11 rather than wayland:

user $GDK_BACKEND=x11 ./start-tor-browser.desktop

To check the current value of GDK_BACKEND, run:

user $env | grep GDK_BACKEND

GDK_BACKEND=wayland

More generally, to check which programs are running as X clients, install the xlsclients package:

root #emerge --ask x11-apps/xlsclients

then run xlsclients(1):

user $xlsclients

localhost java

Wayland over a network

• waypipe(1), provided by the gui-apps/waypipe package, is a transparent proxy for Wayland applications, intended to provide behavior analogous to that of ssh -X in an X context.

• wayvnc(1), provided by the gui-apps/wayvnc package, is a VNC server for wlroots-based Wayland compositors, such as Sway, Hyprland, Wayfire, Hikari, and dwl.

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_DIR/$WAYLAND_DISPLAY.lock"

2. As the new user, export the path to the original user's socket as WAYLAND_DISPLAY:

CODE

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.

Troubleshooting

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):

FILE /etc/default/grub

GRUB_GFXMODE=1680x1050x24
GRUB_GFXPAYLOAD_LINUX=keep

Then update grub:

root #grub-mkconfig -o /boot/grub/grub.cfg

Then reboot.

If that does not work, modify GRUB_CMDLINE_LINUX_DEFAULT and repeat the process:

FILE /etc/default/grub

GRUB_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.

Note
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:

CODE Change Resolution in Sway

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.

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 Known Significant Issues - KDE community wiki page about bugs and inconveniences in Wayland