Enhance Documentation: Clarifications and Helpers for Graphical Booti…

…ng in QEMU Signed-off-by: Camila Macedo <[email protected]> Co-authored-by: Katrina Prosise <[email protected]> Signed-off-by: Camila Macedo <[email protected]>
foundriesio · Oct 3, 2023 · 4427e3d · 4427e3d
1 parent 6da9f63
commit 4427e3d
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 2 deletions.
diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst
@@ -7,6 +7,9 @@ LmP provides reference distros to be used in different use cases. They state the
 
 If you are not familiar with the concept of Distro, the Yocto Project definition can help (`term-DISTRO`_), another good document is the `Poky`_ description, which is the default distro reference used by the Yocto Project.
 
+.. note::
+   For guidance on building new targets with a different distro and customizations, see: :ref:`Customizing the Distro <ref-customizing-the-distro>`.
+
 LmP
 ***
 
@@ -48,8 +51,10 @@ LmP MFGTools
 
 The distro used to generate the ``mfgtool-files`` artifacts which provide the deploy and update tool for some machines (i.MX family).
 
+.. _ref-lmp-wayland-xwayland:
+
 LmP Wayland and LmP XWayland
-****************************
+*********************************
 
 The distros which provide Wayland and XWayland support on top of ``lmp`` distro.
 

diff --git a/source/reference-manual/qemu/qemu-instructions.template b/source/reference-manual/qemu/qemu-instructions.template
@@ -95,7 +95,18 @@ Booting in QEMU
 Booting Graphically
 -------------------
 
-In order to boot QEMU with an OpenGL capable virtual GPU (required for Wayland/Weston), add the following flags to the QEMU CLI:
+This section shows how to boot QEMU with an OpenGL capable virtual GPU—required for Wayland/Weston.
+To check the available options for your system, use the ``-display help`` flag:
+
+.. parsed-literal::
+   $ qemu-system-aarch64 -display help
+   Available display backend types:
+   none
+   curses
+   cocoa
+   dbus
+
+In general, adding the following flags to the QEMU CLI should work:
 
 .. tabs::
 
@@ -111,7 +122,28 @@ In order to boot QEMU with an OpenGL capable virtual GPU (required for Wayland/W
 
          |QEMU_GUI_FLAGS_MAC|
 
+.. note::
+
+    You can also utilize the option ``-display default``.
+    This attempts to use the default display type corresponding to the operating system on which you are running the command.
+
 .. note::
 
     Do not copy the ``-nographic`` flag at the end of the QEMU CLI below.
 
+.. important::
+
+   Specifying display options in QEMU does not make console-only images graphical. It just opens a potential graphical
+   output window. Interaction is mainly text-based. The images created with ``DISTRO=lmp-xwayland`` or ``DISTRO=lmp-wayland``
+   have graphical interfaces. For further information see: :ref:`LmP Wayland and LmP XWayland <ref-lmp-wayland-xwayland>`.
+
+   If you are following :ref:`gs-flash-device` and downloading the console image, it will not boot with a
+   graphical interface. See :ref:`Customizing the Distro <ref-customizing-the-distro>` to know how to build a new
+   target image. Also, ensure that you download the image with the interface, which is usually
+   prefixed with ``lmp-factory-image``.
+
+.. important::
+
+   Compatibility of the display options may vary, and not all options are supported on every host OS.
+   Refer to the `QEMU Documentation <https://www.qemu.org/>`_ for more advanced configurations and options.
+
diff --git a/source/user-guide/lmp-customization/lmp-customization.rst b/source/user-guide/lmp-customization/lmp-customization.rst
@@ -12,6 +12,49 @@ and other options related to the platform build.
    The tutorial for :ref:`tutorial-customizing-the-platform` covers adding a custom recipe service.
    This helps introduces core concepts and steps related to customizing LmP, and is a good place to start.
 
+.. _ref-customizing-the-distro:
+
+Customizing the Distro
+-----------------------------
+
+This section shows how to build new targets with other Distro. Following an example on
+how to build a new targets with :ref:`LmP XWayland <ref-lmp-wayland-xwayland>`.
+
+1. Update your factory config:
+
+.. code-block:: shell
+
+    git clone https://source.foundries.io/factories/<factory>/ci-scripts.git
+    cd ci-scripts
+    vi factory-config.yml
+
+2. Add the distro under `LmP`:
+
+.. code-block:: yaml
+
+    worker_tag: "amd64-partner-aws"
+    params:
+        IMAGE: lmp-factory-image
+        SSTATE_CACHE_MIRROR: ""
+        DOCKER_COMPOSE_APP: "1"
+        DISTRO: "lmp-xwayland"
+
+3. Commit and push the changes:
+
+.. code-block:: shell
+
+    git add .
+    git commit -m "Adding lmp-xwayland as base for my factory"
+    git push
+
+4. Changes into the ``ci-script`` repository don't auto-trigger builds. Push a commit in ``lmp-manifest`` or ``meta-subscriber-overrides``:
+
+.. code-block:: shell
+
+    git clone https://source.foundries.io/factories/<factory>/lmp-manifest.git
+    cd lmp-manifest
+    git commit -m "trigger build" --allow-empty
+
 Kernel Command Line Arguments
 -----------------------------