1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Using Wayland and Weston
4************************
5
6:wikipedia:`Wayland <Wayland_(display_server_protocol)>`
7is a computer display server protocol that provides a method for
8compositing window managers to communicate directly with applications
9and video hardware and expects them to communicate with input hardware
10using other libraries. Using Wayland with supporting targets can result
11in better control over graphics frame rendering than an application
12might otherwise achieve.
13
14The Yocto Project provides the Wayland protocol libraries and the
15reference :wikipedia:`Weston <Wayland_(display_server_protocol)#Weston>`
16compositor as part of its release. You can find the integrated packages
17in the ``meta`` layer of the :term:`Source Directory`.
18Specifically, you
19can find the recipes that build both Wayland and Weston at
20``meta/recipes-graphics/wayland``.
21
22You can build both the Wayland and Weston packages for use only with targets
23that accept the :wikipedia:`Mesa 3D and Direct Rendering Infrastructure
24<Mesa_(computer_graphics)>`, which is also known as Mesa DRI. This implies that
25you cannot build and use the packages if your target uses, for example, the
26Intel Embedded Media and Graphics Driver (Intel EMGD) that overrides Mesa DRI.
27
28.. note::
29
30   Due to lack of EGL support, Weston 1.0.3 will not run directly on the
31   emulated QEMU hardware. However, this version of Weston will run
32   under X emulation without issues.
33
34This section describes what you need to do to implement Wayland and use
35the Weston compositor when building an image for a supporting target.
36
37Enabling Wayland in an Image
38============================
39
40To enable Wayland, you need to enable it to be built and enable it to be
41included (installed) in the image.
42
43Building Wayland
44----------------
45
46To cause Mesa to build the ``wayland-egl`` platform and Weston to build
47Wayland with Kernel Mode Setting
48(`KMS <https://wiki.archlinux.org/index.php/Kernel_Mode_Setting>`__)
49support, include the "wayland" flag in the
50:term:`DISTRO_FEATURES`
51statement in your ``local.conf`` file::
52
53   DISTRO_FEATURES:append = " wayland"
54
55.. note::
56
57   If X11 has been enabled elsewhere, Weston will build Wayland with X11
58   support
59
60Installing Wayland and Weston
61-----------------------------
62
63To install the Wayland feature into an image, you must include the
64following
65:term:`CORE_IMAGE_EXTRA_INSTALL`
66statement in your ``local.conf`` file::
67
68   CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
69
70Running Weston
71==============
72
73To run Weston inside X11, enabling it as described earlier and building
74a Sato image is sufficient. If you are running your image under Sato, a
75Weston Launcher appears in the "Utility" category.
76
77Alternatively, you can run Weston through the command-line interpretor
78(CLI), which is better suited for development work. To run Weston under
79the CLI, you need to do the following after your image is built:
80
81#. Run these commands to export ``XDG_RUNTIME_DIR``::
82
83      mkdir -p /tmp/$USER-weston
84      chmod 0700 /tmp/$USER-weston
85      export XDG_RUNTIME_DIR=/tmp/$USER-weston
86
87#. Launch Weston in the shell::
88
89      weston
90
91