Upto: Table of Contents of full book "Programming Wayland Clients"

This project hasn't been updated since mid-2017. Wayland has moved on since then, so the information here may be out of date, and there is no guarantee the programs still work. You are recommended to look at The Wayland Protocol for more up-todate information, or at A better way to read Wayland documentation . .

Running Wayland


Weston under X

A Wayland compositor is a mixture of a Wayland server, a window manager and a compositor. Weston is a reference implementation of a compositor and normally would be run as a full windowing system, talking directly to the hardware. How to do this is described in the next section.

In order to experiment with Weston in an X environment, Weston can talk to the X server as though it was an X client. This is not the intended use of Wayland, but can be useful. This kind of use will not in general be supported by Wayland compositors. Anyway, to use Weston this way, simply type

from within an X terminal.

This will bring up a window under X looking like

It contains a small menu bar across the top, with a terminal icon and the date. If you were around at the beginning of X, then it would look pretty familiar - and we all got really excited by it! This window is decorated by the X window manager, which would not happen in a standalone environment.

Wayland in a standalone environment

If you are running a Linux system in a command line environment, then you can start a Wayland compositor directly, talking to the hardware. For example, to run Weston type the following at the command prompt:

This will set the proper access permissions and run Weston.

It is not possible to do an X screen dump of this: the standard X tools such as gnome-screenshot will try to connect to the X server, and there isn't one running!

Virtual terminals

Linux has had virtual terminals almost from the beginning. These allow you to have multiple login sessions, each basically independent of the others. By default, Linux has seven of these, so you can have upto seven login sessions running. Note that this is not the same as using multiple terminal windows under X: this is a separate mechanism.

You switch between virtual terminals by the key sequence CTL-ALT-F<n> where n is 1-7. If you are running X as in a normal user distro, then that is usually running in virtual terminal 7. So if you press the keys CTL-ALT-F4 you will get a login prompt for virtual terminal 4. When you want to return to your GUI environment, just press CTL-ALT-F7.

Virtual terminals and X

This is easy: when you switch to another virtual terminal, the X server releases control of the hardware. That means you can do whatever you want, including starting up another X session!

Running a Wayland compositor in a virtual terminal

Switch to a virtual terminal. Login, and at the command prompt, start a compositor.

Many distros such as Ubuntu include the proof-of-concept compositor weston in their repositories. Download and install it by, say,

sudo apt-get install weston
under a Debian-derived system such as Ubuntu. Then in a virtual terminal, run

What runs under Wayland?

If it's an application relying only on X, then it won't run. This includes applications with a long history in X: xterm, xclock and xedit, for example. They just complain that they can't find an X server and give up.

Many GUI applications are now built using toolkits such as Gtk or KDE. Many of these toolkits are progressively including support for Wayland, and many of their applications run okay. This includes for example eog. But other applications using Gtk don't, including Firefox, Chromium and Gimp. This is at June, 2014. The situation can change rapidly.


The X server can be modified to talk to Wayland instead of to the hardware. This has been done as the XWayland project. At present, Weston has been modified to listen on the X ports 6000+. It starts an X server as a Weston client when an X client starts.

To run Weston with XWayland, in a non-X environment, run

weston-launch -- --modules=xwayland.so
[doesn't work for me. sets DISPLAY to :1 but xclock can't open it]

The page XWayland has details.


Copyright © Jan Newmarch, jan@newmarch.name

If you like this book, please contribute using Flattr
or donate using PayPal