manuals: split dev-manual/common-tasks.rst

A 500 KB source file is always harder to manage,
and can have section title conflicts.

So, the "Common Tasks" document is gone and all
its constituents are moved up one level.
You now have 40 chapters in the Development Tasks Manual.

(From yocto-docs rev: 8a45bc469411410020b8e688c137395fcaf3761b)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

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 @@
+.. 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:
+
+1. 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
+
+2. Launch Weston in the shell::
+
+      weston
+