diff options
Diffstat (limited to 'documentation/dev-manual/wayland.rst')
-rw-r--r-- | documentation/dev-manual/wayland.rst | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst new file mode 100644 index 0000000000..bcbf40acc5 --- /dev/null +++ b/documentation/dev-manual/wayland.rst | |||
@@ -0,0 +1,90 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Using Wayland and Weston | ||
4 | ************************ | ||
5 | |||
6 | :wikipedia:`Wayland <Wayland_(display_server_protocol)>` | ||
7 | is a computer display server protocol that provides a method for | ||
8 | compositing window managers to communicate directly with applications | ||
9 | and video hardware and expects them to communicate with input hardware | ||
10 | using other libraries. Using Wayland with supporting targets can result | ||
11 | in better control over graphics frame rendering than an application | ||
12 | might otherwise achieve. | ||
13 | |||
14 | The Yocto Project provides the Wayland protocol libraries and the | ||
15 | reference :wikipedia:`Weston <Wayland_(display_server_protocol)#Weston>` | ||
16 | compositor as part of its release. You can find the integrated packages | ||
17 | in the ``meta`` layer of the :term:`Source Directory`. | ||
18 | Specifically, you | ||
19 | can find the recipes that build both Wayland and Weston at | ||
20 | ``meta/recipes-graphics/wayland``. | ||
21 | |||
22 | You can build both the Wayland and Weston packages for use only with targets | ||
23 | that accept the :wikipedia:`Mesa 3D and Direct Rendering Infrastructure | ||
24 | <Mesa_(computer_graphics)>`, which is also known as Mesa DRI. This implies that | ||
25 | you cannot build and use the packages if your target uses, for example, the | ||
26 | Intel 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 | |||
34 | This section describes what you need to do to implement Wayland and use | ||
35 | the Weston compositor when building an image for a supporting target. | ||
36 | |||
37 | Enabling Wayland in an Image | ||
38 | ============================ | ||
39 | |||
40 | To enable Wayland, you need to enable it to be built and enable it to be | ||
41 | included (installed) in the image. | ||
42 | |||
43 | Building Wayland | ||
44 | ---------------- | ||
45 | |||
46 | To cause Mesa to build the ``wayland-egl`` platform and Weston to build | ||
47 | Wayland with Kernel Mode Setting | ||
48 | (`KMS <https://wiki.archlinux.org/index.php/Kernel_Mode_Setting>`__) | ||
49 | support, include the "wayland" flag in the | ||
50 | :term:`DISTRO_FEATURES` | ||
51 | statement 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 | |||
60 | Installing Wayland and Weston | ||
61 | ----------------------------- | ||
62 | |||
63 | To install the Wayland feature into an image, you must include the | ||
64 | following | ||
65 | :term:`CORE_IMAGE_EXTRA_INSTALL` | ||
66 | statement in your ``local.conf`` file:: | ||
67 | |||
68 | CORE_IMAGE_EXTRA_INSTALL += "wayland weston" | ||
69 | |||
70 | Running Weston | ||
71 | ============== | ||
72 | |||
73 | To run Weston inside X11, enabling it as described earlier and building | ||
74 | a Sato image is sufficient. If you are running your image under Sato, a | ||
75 | Weston Launcher appears in the "Utility" category. | ||
76 | |||
77 | Alternatively, you can run Weston through the command-line interpretor | ||
78 | (CLI), which is better suited for development work. To run Weston under | ||
79 | the CLI, you need to do the following after your image is built: | ||
80 | |||
81 | 1. 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 | 2. Launch Weston in the shell:: | ||
88 | |||
89 | weston | ||
90 | |||