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..097be9cbde --- /dev/null +++ b/documentation/dev-manual/wayland.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Using Wayland and Weston +************************ + +:wikipedia:`Wayland <Wayland_(display_server_protocol)>` +is a computer display server protocol that provides a method for +compositing window managers to communicate directly with applications +and video hardware and expects them to communicate with input hardware +using other libraries. Using Wayland with supporting targets can result +in better control over graphics frame rendering than an application +might otherwise achieve. + +The Yocto Project provides the Wayland protocol libraries and the +reference :wikipedia:`Weston <Wayland_(display_server_protocol)#Weston>` +compositor as part of its release. You can find the integrated packages +in the ``meta`` layer of the :term:`Source Directory`. +Specifically, you +can find the recipes that build both Wayland and Weston at +``meta/recipes-graphics/wayland``. + +You can build both the Wayland and Weston packages for use only with targets +that accept the :wikipedia:`Mesa 3D and Direct Rendering Infrastructure +<Mesa_(computer_graphics)>`, which is also known as Mesa DRI. This implies that +you cannot build and use the packages if your target uses, for example, the +Intel Embedded Media and Graphics Driver (Intel EMGD) that overrides Mesa DRI. + +.. note:: + + Due to lack of EGL support, Weston 1.0.3 will not run directly on the + emulated QEMU hardware. However, this version of Weston will run + under X emulation without issues. + +This section describes what you need to do to implement Wayland and use +the Weston compositor when building an image for a supporting target. + +Enabling Wayland in an Image +============================ + +To enable Wayland, you need to enable it to be built and enable it to be +included (installed) in the image. + +Building Wayland +---------------- + +To cause Mesa to build the ``wayland-egl`` platform and Weston to build +Wayland with Kernel Mode Setting +(`KMS <https://wiki.archlinux.org/index.php/Kernel_Mode_Setting>`__) +support, include the "wayland" flag in the +:term:`DISTRO_FEATURES` +statement in your ``local.conf`` file:: + + DISTRO_FEATURES:append = " wayland" + +.. note:: + + If X11 has been enabled elsewhere, Weston will build Wayland with X11 + support + +Installing Wayland and Weston +----------------------------- + +To install the Wayland feature into an image, you must include the +following +:term:`CORE_IMAGE_EXTRA_INSTALL` +statement in your ``local.conf`` file:: + + CORE_IMAGE_EXTRA_INSTALL += "wayland weston" + +Running Weston +============== + +To run Weston inside X11, enabling it as described earlier and building +a Sato image is sufficient. If you are running your image under Sato, a +Weston Launcher appears in the "Utility" category. + +Alternatively, you can run Weston through the command-line interpretor +(CLI), which is better suited for development work. To run Weston under +the CLI, you need to do the following after your image is built: + +#. Run these commands to export ``XDG_RUNTIME_DIR``:: + + mkdir -p /tmp/$USER-weston + chmod 0700 /tmp/$USER-weston + export XDG_RUNTIME_DIR=/tmp/$USER-weston + +#. Launch Weston in the shell:: + + weston + |