An Introduction to the Wayland Build Tools

Most people’s first encounter with Wayland will be when their regular Linux distribution has migrated to it. Indeed, Wayland is really just a protocol, so chances are you’ll soon be using it through your normal desktop environment (Enlightenment/Gnome/etc.) without any particular action on your part, aside from a normal upgrade.

But perhaps you’re one of the few, proud, hardcore Wayland hackers that already have the various repos checked out, and know all the intricacies of configuring Mesa and installing Xwayland and so on. So, if you don’t care about any of the details, or if you care a whole lot about ALL THE DETAILS, well, you’re probably already set.

Kick Wayland’s Tires with the Wayland Build Tools

If, on the other hand, you’re somewhere in between – you’re interested in playing with raw Wayland and Weston, but want to get the latest bits up and running quickly and don’t want to risk system disruption – then you want to snag the new wayland-build-tools package.

$ git clone git://

These are simply script versions of the standard Wayland build and installation directions, which take care of downloading and building the various upstream components needed for Wayland, the Weston compositor, and Xwayland.

The first step is the config file; you can copy

$ mkdir -p ~/.config/wayland-build-tools
$ cp ~/.config/wayland-build-tools/

You can probably use the defaults listed in that file as is, but there are three parameters you might wish to tweak to your preference. You can specify where the repositories are checked out and built via the WLROOT parameter (by default it’ll place stuff into ~/Wayland). The libraries and binaries will be installed to $WLROOT/install but you can configure this differently via the WLD parameter. There is also an INCLUDE_XWAYLAND parameter that lets you disable Xwayland building, which you might want to do if the X builds go awry.

Next, while we’ll be manually building the dependencies that Wayland typically needs the latest changes from, a bunch of dependencies we require can be loaded from your regular distribution normally. For Ubuntu, just do:

$ wl_install_deps

Users on other distros will need to adapt it to their package management system if they want to use it. Patches to wl_install_deps to support more distros are most definitely welcomed!

Next, run this to check out all the git repositories:

$ wl_clone

You can also re-run it to update your existing checkouts.

Now for the fun part, go ahead and build the Weston world:

$ wl_build

This will first build wayland and wayland-protocols. Despite the naming, both of these are protocol packages. The first one is official protocols, the second unofficial, but both are required by Weston. Compilation of these should be easy and without drama.

Next, it will build a variety of other packages that Mesa needs, along with Mesa itself. The Mesa project develops at a pretty brisk pace and sometimes dependencies can change or other oddnesses can creep in, so this is the one place where you might potentially run into issues. At the time of this writing, wayland-build-tools is able to build mesa with no muss or fuss on Ubuntu 14.04 with Intel, NVIDIA, and Radeon graphics hardware. Depending on when you’re reading this and what Linux distribution you’re on this part of the build may need some adjustment. Again, patches would be welcomed because our goal is for wayland-build-tools to make these builds easy for everyone.

After Mesa comes Weston’s library dependencies. There are several, but they rarely present challenges and should build smoothly. Finally, Xwayland is built if it has been enabled in the config. This hammers into place a whole mess of X11 packages including’s Xserver itself with Xwayland enabled and various other bits disabled that aren’t needed.

Use Weston to Test Out Wayland

Finally comes Weston itself, along with its demo clients. Along with Weston, a weston.ini will automatically be copied into your ~/.config/ directory. For normal usage there’s nothing that needs changed here, but the man page details all the options if you wish to tinker:

$ source $HOME/.config/wayland-build-tools/
$ man weston.ini

You’re now ready to run weston.

$ source $HOME/.config/wayland-build-tools/
$ weston

This will launch weston in a window inside your regular X session. A weston-enabled terminal program can be launched via the toolbar button, and from that command line you should be able to launch wayland and X11 software.

An Introduction to the Wayland Build Tools - wayland-osg

Weston can also be run natively outside X from the console, but only if you’re using non-proprietary graphics drivers (i.e. don’t expect smooth sailing if you’re using NVIDIA or FGLRX proprietary drivers). Switch to a console (e.g. Ctrl+Alt+F2), login as root, and then:

source $HOME/.config/wayland-build-tools/

Get Involved

This guide provides all of the information you need to get up and running with Wayland today. If you’d like to contribute to this toolset, please feel free to send patches to the Wayland mailing list, or to me personally. The official home of the git repository is at freedesktop, and there’s a mirror of it on github.

Author: Bryce Harrington

Bryce is a founder and developer of the Inkscape project, but began his career in the aerospace industry as a spacecraft propulsions engineer.