Wayland on Windows

Wayland is a display protocol, a protocol (and accompanying C library) spoken by a graphical application with a display server in order to communicate about both input to the application (keyboard, mouse, ...) and about output from the application -- that is, the rendered window. Wayland was developed to replace the X11 server on the Linux system. After quite a few years of incubation, it's becoming much more common. It's a far simpler and more attractive protocol compared to X11, allowing much more flexibility in developing custom compositors and control in the display compositor on how the client applications are shown and with less decades-old baggage to keep around and take into account.

So, what's the problem?

Qt provides both a Wayland platform allowing you to run Qt applications as Wayland clients in a Wayland compositor and a library to build a Wayland compositor, both using QML or not, in the Qt Wayland module. However, that and Wayland, in general, are only available on Linux, which may prove to be a problem for many. Many projects that target a Linux embedded platform but are developed on Windows because of some tooling that is only available there or for any other reason end up using a Linux virtual machine, which is a far less than optimal solution. It has several disadvantages: worse performance, an OS and environment that you are not used to, possibly bad or no hardware support for some devices, and a clunky user experience.

A Better Solution

There is a better solution. With the WSL subsystem on Windows, it is actually possible to run directly (albeit through an X server and so far unfortunately only OpenGL software) a Wayland compositor and clients. By running a Wayland compositor directly in your Windows machine, you avoid all the aforementioned problems. In this blog post, I'll explain how to do it.

First, you need to setup WSL2, following the guide at https://docs.microsoft.com/en-us/windows/wsl/install-win10.

After that, you need to install an X server for Windows. I've successfully tried both VcxSrv and Xming. Launch it, but make sure to disable access control. If you're using VcxSrv or Xming, there is an option in the XLaunch utility for that.

Now open the terminal of the Linux distribution you installed from the Start menu (I'm using Ubuntu 20.04, but any distribution should work) and run these commands:


sudo apt update && sudo apt upgrade
sudo apt install weston

If you picked another distribution, you may need to adapt these commands, but it should not be difficult.

We are almost there. Now we need to tell the compositor the location of the X server. To do that, you need to open the PowerShell from the Start menu, run the ipconfig command, and locate IPv4 address in the section about the WSL adapter (usually the last one). In the Linux terminal, that's the address we need to use to connect to the X server:

export DISPLAY=<address>:0

Wayland also needs the XDG_RUNTIME_DIR environment variable to know where to put the socket file:

mkdir /tmp/xdg

export XDG_RUNTIME_DIR=/tmp/xdg

We are going to add this export line also at the end of the .bashrc file so that it's run automatically every time a terminal is opened.

Now if you run weston, you should see it open a window. To then run a Wayland client, open another Linux terminal and run a Wayland client. Weston provides a few, such as weston-terminal. But you can also install and run any Qt application by using the -platform wayland command line parameter or exporting the QT_QPA_PLATFORM=waylandenvironment variable beforehand, provided you've installed the QtWayland module. On Ubuntu, that is only a sudo apt install qtwayland5 away.

That's it! As I've said, at this point in time it has the limitation that OpenGL is only provided by LLVMpipe, which runs on the CPU. Microsoft is working on improvements to the WSL layer to make this whole experience better, including adding GPU acceleration. However, that version is not released yet to the broad public. You can, in the meantime, subscribe to the Windows Insider program to try a preview. See https://docs.microsoft.com/en-us/windows/wsl/tutorials/gui-apps. For a QML application, unless you have some custom item that does heavy rendering, it's not a real problem if you can accept maybe less than 60 fps.