[kirkstone][PATCH 00/16] kirkstone documentation backports

[kirkstone][PATCH 00/16] kirkstone documentation backports

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Corresponding to changes in master which are
also applicable to kirkstone, sometimes after
specific tweaks.

Arne Schwerdt (1):
  ref-manual: Warn about COMPATIBLE_MACHINE skipping native recipes

BELHADJ SALEM Talel (5):
  ref-manual: Fix PACKAGECONFIG term and add an example
  dev-manual: layers: Add notes about layer.conf
  ref-manual: variables: add RECIPE_SYSROOT and RECIPE_SYSROOT_NATIVE
  ref-manual: variables: add TOOLCHAIN_OPTIONS variable
  ref-manual: variables: add example for SYSROOT_DIRS variable

Michael Opdenacker (6):
  manuals: update linux-yocto append examples
  dev-manual: wic: update "wic list images" output
  sdk-manual: appendix-obtain: improve and update descriptions
  bsp-guide: bsp: skip Intel machines no longer supported in Poky
  brief-yoctoprojectqs: use new CDN mirror for sstate
  dev-manual: start.rst: remove obsolete reference

Paul Eggleton (1):
  dev/ref-manual: Document INIT_MANAGER

Quentin Schulz (1):
  ref-manual: variables: provide no-match example for COMPATIBLE_MACHINE

Robert P. J. Day (2):
  dev-manual: new-recipe.rst: add missing parenthesis to "Patching Code"
    section
  profile-manual: aesthetic cleanups

 documentation/brief-yoctoprojectqs/index.rst |   2 +-
 documentation/bsp-guide/bsp.rst              |  46 ++---
 documentation/dev-manual/layers.rst          |  14 ++
 documentation/dev-manual/new-recipe.rst      |   4 +-
 documentation/dev-manual/start.rst           |  24 +--
 documentation/dev-manual/wic.rst             |  27 +--
 documentation/kernel-dev/advanced.rst        |   3 +-
 documentation/kernel-dev/common.rst          |  34 ++--
 documentation/profile-manual/intro.rst       |  40 +++--
 documentation/ref-manual/variables.rst       | 180 +++++++++++++++++--
 documentation/sdk-manual/appendix-obtain.rst |  50 ++----
 11 files changed, 275 insertions(+), 149 deletions(-)

-- 
2.34.1

[kirkstone][PATCH 01/16] ref-manual: Warn about COMPATIBLE_MACHINE skipping native recipes

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Arne Schwerdt <arne.schwerdt@elbbits.com>

Signed-off-by: Arne Schwerdt <arne.schwerdt@elbbits.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 6fa400a574..148eebf56a 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1202,6 +1202,13 @@ system and gives an overview of their function and contents.
       speed since the build system skips parsing recipes not compatible
       with the current machine.
 
+      .. note::
+
+         When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from
+         native, the recipe is always skipped. All native recipes must be
+         entirely target independent and should not rely on :term:`MACHINE`.
+
+
    :term:`COMPLEMENTARY_GLOB`
       Defines wildcards to match when installing a list of complementary
       packages for all the packages explicitly (or implicitly) installed in
-- 
2.34.1

[kirkstone][PATCH 02/16] manuals: update linux-yocto append examples

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/bsp-guide/bsp.rst        | 32 ++++++++++++------------
 documentation/kernel-dev/advanced.rst  |  3 +--
 documentation/kernel-dev/common.rst    | 34 +++++++++++++-------------
 documentation/ref-manual/variables.rst | 12 ++++-----
 4 files changed, 40 insertions(+), 41 deletions(-)

diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
index 8b29290b59..f9e13d145a 100644
--- a/documentation/bsp-guide/bsp.rst
+++ b/documentation/bsp-guide/bsp.rst
@@ -1449,39 +1449,39 @@ The kernel recipe used to build the kernel image for the BeagleBone
 device was established in the machine configuration::
 
    PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
-   PREFERRED_VERSION_linux-yocto ?= "5.0%"
+   PREFERRED_VERSION_linux-yocto ?= "5.15%"
 
 The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains
 metadata used to build the kernel. In this case, a kernel append file
-(i.e. ``linux-yocto_5.0.bbappend``) is used to override an established
-kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in
-:yocto_git:`/poky/tree/meta/recipes-kernel/linux`.
+(i.e. ``linux-yocto_5.15.bbappend``) is used to override an established
+kernel recipe (i.e. ``linux-yocto_5.15.bb``), which is located in
+:yocto_git:`/poky/tree/meta-yocto-bsp/recipes-kernel/linux`.
 
 Following is the contents of the append file::
 
-   KBRANCH:genericx86 = "v5.0/standard/base"
-   KBRANCH:genericx86-64 = "v5.0/standard/base"
-   KBRANCH:edgerouter = "v5.0/standard/edgerouter"
-   KBRANCH:beaglebone-yocto = "v5.0/standard/beaglebone"
+   KBRANCH:genericx86  = "v5.15/standard/base"
+   KBRANCH:genericx86-64  = "v5.15/standard/base"
+   KBRANCH:edgerouter = "v5.15/standard/edgerouter"
+   KBRANCH:beaglebone-yocto = "v5.15/standard/beaglebone"
 
    KMACHINE:genericx86 ?= "common-pc"
    KMACHINE:genericx86-64 ?= "common-pc-64"
    KMACHINE:beaglebone-yocto ?= "beaglebone"
 
-   SRCREV_machine:genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
-   SRCREV_machine:genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
-   SRCREV_machine:edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
-   SRCREV_machine:beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
+   SRCREV_machine:genericx86 ?= "0b628306d1f9ea28c0e86369ce9bb87a47893c9c"
+   SRCREV_machine:genericx86-64 ?= "0b628306d1f9ea28c0e86369ce9bb87a47893c9c"
+   SRCREV_machine:edgerouter ?= "90f1ee6589264545f548d731c2480b08a007230f"
+   SRCREV_machine:beaglebone-yocto ?= "9aabbaa89fcb21af7028e814c1f5b61171314d5a"
 
    COMPATIBLE_MACHINE:genericx86 = "genericx86"
    COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64"
    COMPATIBLE_MACHINE:edgerouter = "edgerouter"
    COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto"
 
-   LINUX_VERSION:genericx86 = "5.0.3"
-   LINUX_VERSION:genericx86-64 = "5.0.3"
-   LINUX_VERSION:edgerouter = "5.0.3"
-   LINUX_VERSION:beaglebone-yocto = "5.0.3"
+   LINUX_VERSION:genericx86 = "5.15.72"
+   LINUX_VERSION:genericx86-64 = "5.15.72"
+   LINUX_VERSION:edgerouter = "5.15.54"
+   LINUX_VERSION:beaglebone-yocto = "5.15.54"
 
 This particular append file works for all the machines that are
 part of the ``meta-yocto-bsp`` layer. The relevant statements are
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
index b5290b61b3..e38a8da25c 100644
--- a/documentation/kernel-dev/advanced.rst
+++ b/documentation/kernel-dev/advanced.rst
@@ -69,8 +69,7 @@ to indicate the branch.
    You can use the :term:`KBRANCH` value to define an alternate branch typically
    with a machine override as shown here from the ``meta-yocto-bsp`` layer::
 
-           KBRANCH:edgerouter = "standard/edgerouter"
-
+      KBRANCH:beaglebone-yocto = "standard/beaglebone"
 
 The linux-yocto style recipes can optionally define the following
 variables:
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 4279cbb707..3406fcfe75 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -455,13 +455,13 @@ Creating the Append File
 
 You create this file in your custom layer. You also name it accordingly
 based on the linux-yocto recipe you are using. For example, if you are
-modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
+modifying the ``meta/recipes-kernel/linux/linux-yocto_5.15.bb`` recipe,
 the append file will typically be located as follows within your custom
 layer:
 
 .. code-block:: none
 
-   your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
+   your-layer/recipes-kernel/linux/linux-yocto_5.15.bbappend
 
 The append file should initially extend the
 :term:`FILESPATH` search path by
@@ -489,36 +489,36 @@ As an example, consider the following append file used by the BSPs in
 
 .. code-block:: none
 
-   meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
+   meta-yocto-bsp/recipes-kernel/linux/linux-yocto_5.15.bbappend
 
 Here are the contents of this file. Be aware that the actual commit ID
 strings in this example listing might be different than the actual
 strings in the file from the ``meta-yocto-bsp`` layer upstream.
 ::
 
-   KBRANCH:genericx86  = "standard/base"
-   KBRANCH:genericx86-64  = "standard/base"
+   KBRANCH:genericx86  = "v5.15/standard/base"
+   KBRANCH:genericx86-64  = "v5.15/standard/base"
+   KBRANCH:edgerouter = "v5.15/standard/edgerouter"
+   KBRANCH:beaglebone-yocto = "v5.15/standard/beaglebone"
 
    KMACHINE:genericx86 ?= "common-pc"
    KMACHINE:genericx86-64 ?= "common-pc-64"
-   KBRANCH:edgerouter = "standard/edgerouter"
-   KBRANCH:beaglebone = "standard/beaglebone"
-
-   SRCREV_machine:genericx86    ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
-   SRCREV_machine:genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
-   SRCREV_machine:edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
-   SRCREV_machine:beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d"
+   KMACHINE:beaglebone-yocto ?= "beaglebone"
 
+   SRCREV_machine:genericx86 ?= "0b628306d1f9ea28c0e86369ce9bb87a47893c9c"
+   SRCREV_machine:genericx86-64 ?= "0b628306d1f9ea28c0e86369ce9bb87a47893c9c"
+   SRCREV_machine:edgerouter ?= "90f1ee6589264545f548d731c2480b08a007230f"
+   SRCREV_machine:beaglebone-yocto ?= "9aabbaa89fcb21af7028e814c1f5b61171314d5a"
 
    COMPATIBLE_MACHINE:genericx86 = "genericx86"
    COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64"
    COMPATIBLE_MACHINE:edgerouter = "edgerouter"
-   COMPATIBLE_MACHINE:beaglebone = "beaglebone"
+   COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto"
 
-   LINUX_VERSION:genericx86 = "4.12.7"
-   LINUX_VERSION:genericx86-64 = "4.12.7"
-   LINUX_VERSION:edgerouter = "4.12.10"
-   LINUX_VERSION:beaglebone = "4.12.10"
+   LINUX_VERSION:genericx86 = "5.15.72"
+   LINUX_VERSION:genericx86-64 = "5.15.72"
+   LINUX_VERSION:edgerouter = "5.15.54"
+   LINUX_VERSION:beaglebone-yocto = "5.15.54"
 
 This append file
 contains statements used to support several BSPs that ship with the
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 148eebf56a..7d537bf878 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3943,7 +3943,7 @@ system and gives an overview of their function and contents.
 
       Values for this variable are set in the kernel's recipe file and the
       kernel's append file. For example, if you are using the
-      ``linux-yocto_4.12`` kernel, the kernel recipe file is the
+      ``linux-yocto_5.15`` kernel, the kernel recipe file is the
       ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH`
       is set as follows in that kernel recipe file::
 
@@ -3956,13 +3956,13 @@ system and gives an overview of their function and contents.
       BSP layer for a given machine. For example, the append file for the
       Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA
       machines (``meta-yocto-bsp``) is named
-      ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``.
+      ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.15.bbappend``.
       Here are the related statements from that append file::
 
-         KBRANCH:genericx86 = "standard/base"
-         KBRANCH:genericx86-64 = "standard/base"
-         KBRANCH:edgerouter = "standard/edgerouter"
-         KBRANCH:beaglebone = "standard/beaglebone"
+         KBRANCH:genericx86  = "v5.15/standard/base"
+         KBRANCH:genericx86-64  = "v5.15/standard/base"
+         KBRANCH:edgerouter = "v5.15/standard/edgerouter"
+         KBRANCH:beaglebone-yocto = "v5.15/standard/beaglebone"
 
       The :term:`KBRANCH` statements
       identify the kernel branch to use when building for each supported
-- 
2.34.1

[kirkstone][PATCH 03/16] dev-manual: wic: update "wic list images" output

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/wic.rst | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/documentation/dev-manual/wic.rst b/documentation/dev-manual/wic.rst
index 213f143273..25180c5cb5 100644
--- a/documentation/dev-manual/wic.rst
+++ b/documentation/dev-manual/wic.rst
@@ -142,17 +142,18 @@ command to return the available Wic images as follows::
      genericx86                    		Create an EFI disk image for genericx86*
      edgerouter                    		Create SD card image for Edgerouter
      beaglebone-yocto              		Create SD card image for Beaglebone
-     qemux86-directdisk            		Create a qemu machine 'pcbios' direct disk image
-     systemd-bootdisk              		Create an EFI disk image with systemd-boot
-     mkhybridiso                   		Create a hybrid ISO image
+     qemuriscv                     		Create qcow2 image for RISC-V QEMU machines
      mkefidisk                     		Create an EFI disk image
-     sdimage-bootpart              		Create SD card image with a boot partition
      directdisk-multi-rootfs       		Create multi rootfs image using rootfs plugin
      directdisk                    		Create a 'pcbios' direct disk image
-     directdisk-bootloader-config  		Create a 'pcbios' direct disk image with custom bootloader config
-     qemuriscv                     		Create qcow2 image for RISC-V QEMU machines
+     efi-bootdisk                  		
+     mkhybridiso                   		Create a hybrid ISO image
      directdisk-gpt                		Create a 'pcbios' direct disk image
-     efi-bootdisk
+     systemd-bootdisk              		Create an EFI disk image with systemd-boot
+     sdimage-bootpart              		Create SD card image with a boot partition
+     qemux86-directdisk            		Create a qemu machine 'pcbios' direct disk image
+     directdisk-bootloader-config  		Create a 'pcbios' direct disk image with custom bootloader config
+
 
 Once you know the list of available
 Wic images, you can use ``help`` with the command to get help on a
@@ -283,16 +284,18 @@ Use the following command to list the available kickstart files::
 
    $ wic list images
      genericx86                    		Create an EFI disk image for genericx86*
-     beaglebone-yocto              		Create SD card image for Beaglebone
      edgerouter                    		Create SD card image for Edgerouter
-     qemux86-directdisk            		Create a QEMU machine 'pcbios' direct disk image
-     directdisk-gpt                		Create a 'pcbios' direct disk image
+     beaglebone-yocto              		Create SD card image for Beaglebone
+     qemuriscv                     		Create qcow2 image for RISC-V QEMU machines
      mkefidisk                     		Create an EFI disk image
+     directdisk-multi-rootfs       		Create multi rootfs image using rootfs plugin
      directdisk                    		Create a 'pcbios' direct disk image
-     systemd-bootdisk              		Create an EFI disk image with systemd-boot
+     efi-bootdisk                  		
      mkhybridiso                   		Create a hybrid ISO image
+     directdisk-gpt                		Create a 'pcbios' direct disk image
+     systemd-bootdisk              		Create an EFI disk image with systemd-boot
      sdimage-bootpart              		Create SD card image with a boot partition
-     directdisk-multi-rootfs       		Create multi rootfs image using rootfs plugin
+     qemux86-directdisk            		Create a qemu machine 'pcbios' direct disk image
      directdisk-bootloader-config  		Create a 'pcbios' direct disk image with custom bootloader config
 
 When you use an existing file, you
-- 
2.34.1

[kirkstone][PATCH 04/16] sdk-manual: appendix-obtain: improve and update descriptions

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

- Improve text formatting
- Stop mentioning all possible values
- Update examples
- Correct descriptions

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/sdk-manual/appendix-obtain.rst | 50 +++++++-------------
 1 file changed, 18 insertions(+), 32 deletions(-)

diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst
index 841abac5aa..7b458f281b 100644
--- a/documentation/sdk-manual/appendix-obtain.rst
+++ b/documentation/sdk-manual/appendix-obtain.rst
@@ -25,27 +25,20 @@ Follow these steps to locate and hand-install the toolchain:
    download the installer appropriate for your build host, target
    hardware, and image type.
 
-   The installer files (``*.sh``) follow this naming convention::
+   The installer files (``*.sh``) follow this naming convention:
+   ``poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh``:
 
-      poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
+   -  ``host_system``: string representing your development system: ``i686`` or ``x86_64``
 
-      Where:
-          host_system is a string representing your development system:
-                 "i686" or "x86_64"
+   -  ``type``: string representing the image: ``sato`` or ``minimal``
 
-          type is a string representing the image:
-                "sato" or "minimal"
+   -  ``arch``: string representing the target architecture such as ``cortexa57-qemuarm64``
 
-          arch is a string representing the target architecture:
-                 "aarch64", "armv5e", "core2-64", "cortexa8hf-neon", "i586", "mips32r2",
-                 "mips64", or "ppc7400"
-
-          release is the version of Yocto Project.
-
-          NOTE:
-             The standard SDK installer does not have the "-ext" string as
-             part of the filename.
+   -  ``release``: version of the Yocto Project.
 
+   .. note::
+      The standard SDK installer does not have the ``-ext`` string as
+      part of the filename.
 
    The toolchains provided by the Yocto
    Project are based off of the ``core-image-sato`` and
@@ -53,16 +46,16 @@ Follow these steps to locate and hand-install the toolchain:
    developing against those images.
 
    For example, if your build host is a 64-bit x86 system and you need
-   an extended SDK for a 64-bit core2 target, go into the ``x86_64``
+   an extended SDK for a 64-bit core2 QEMU target, go into the ``x86_64``
    folder and download the following installer::
 
-      poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+      poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
 
 4. *Run the Installer:* Be sure you have execution privileges and run
    the installer. Following is an example from the ``Downloads``
    directory::
 
-      $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
+      $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-qemux86-64-toolchain-&DISTRO;.sh
 
    During execution of the script, you choose the root location for the
    toolchain. See the
@@ -206,21 +199,14 @@ Follow these steps to extract the root filesystem:
    also contain flattened root filesystem image files (``*.ext4``),
    which you can use with QEMU directly.
 
-   The pre-built root filesystem image files follow these naming
-   conventions::
-
-      core-image-profile-arch.tar.bz2
+   The pre-built root filesystem image files follow the
+   ``core-image-profile-machine.tar.bz2`` naming convention:
 
-      Where:
-          profile is the filesystem image's profile:
-                    lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
-                    sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
-                    these types of image profiles, see the "Images" chapter in
-                    the Yocto Project Reference Manual.
+   -  ``profile``: filesystem image's profile, such as ``minimal``,
+      ``minimal-dev`` or ``sato``. For information on these types of image
+      profiles, see the "Images" chapter in the Yocto Project Reference Manual.
 
-          arch is a string representing the target architecture:
-                    beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
-                    genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
+   -  ``machine``:  same string as the name of the parent download directory.
 
    The root filesystems
    provided by the Yocto Project are based off of the
-- 
2.34.1

[kirkstone][PATCH 05/16] bsp-guide: bsp: skip Intel machines no longer supported in Poky

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
---
 documentation/bsp-guide/bsp.rst | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
index f9e13d145a..94ed1641b5 100644
--- a/documentation/bsp-guide/bsp.rst
+++ b/documentation/bsp-guide/bsp.rst
@@ -774,20 +774,6 @@ workflow.
 
          -  Two general IA platforms (``genericx86`` and ``genericx86-64``)
 
-      -  There are three core Intel BSPs in the Yocto Project
-         release, in the ``meta-intel`` layer:
-
-         -  ``intel-core2-32``, which is a BSP optimized for the Core2
-            family of CPUs as well as all CPUs prior to the Silvermont
-            core.
-
-         -  ``intel-corei7-64``, which is a BSP optimized for Nehalem
-            and later Core and Xeon CPUs as well as Silvermont and later
-            Atom CPUs, such as the Baytrail SoCs.
-
-         -  ``intel-quark``, which is a BSP optimized for the Intel
-            Galileo gen1 & gen2 development boards.
-
    When you set up a layer for a new BSP, you should follow a standard
    layout. This layout is described in the ":ref:`bsp-guide/bsp:example filesystem layout`"
    section. In the standard layout, notice
-- 
2.34.1

[kirkstone][PATCH 06/16] dev-manual: new-recipe.rst: add missing parenthesis to "Patching Code" section

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Robert P. J. Day <rpjday@crashcourse.ca>

Add missing parenthesis, and another example of a compressed patch filename.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/new-recipe.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index 855ef8eb06..a031c59875 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -409,8 +409,8 @@ Patching Code
 
 Sometimes it is necessary to patch code after it has been fetched. Any
 files mentioned in :term:`SRC_URI` whose names end in ``.patch`` or
-``.diff`` or compressed versions of these suffixes (e.g. ``diff.gz`` are
-treated as patches. The
+``.diff`` or compressed versions of these suffixes (e.g. ``diff.gz``,
+``patch.bz2``, etc.) are treated as patches. The
 :ref:`ref-tasks-patch` task
 automatically applies these patches.
 
-- 
2.34.1

[kirkstone][PATCH 07/16] dev/ref-manual: Document INIT_MANAGER

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Paul Eggleton <bluelightning@bluelightning.org>

The INIT_MANAGER variable was added in 3.0 but it seems we didn't get
around to documenting it yet. I have added a variable glossary entry and
made the basic adjustment of the "Using systemd Exclusively" section in
the dev manual, however I think the latter section still needs work.

Signed-off-by: Paul Eggleton <bluelightning@bluelightning.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/variables.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 7d537bf878..0c573194e9 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3701,6 +3701,21 @@ system and gives an overview of their function and contents.
          even if the toolchain's binaries are strippable, there are other files
          needed for the build that are not strippable.
 
+   :term:`INIT_MANAGER`
+      Specifies the system init manager to use. Available options are:
+
+      -  ``sysvinit`` - System V init (default for poky)
+      -  ``systemd`` - systemd
+      -  ``mdev-busybox`` - mdev provided by busybox
+      -  ``none`` - no init manager
+
+      More concretely, this is used to include
+      ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global
+      configuration. You can have a look at the ``conf/distro/include/init-manager-*.inc``
+      files for more information, and also the
+      ":ref:`dev-manual/init-manager:selecting an initialization manager`"
+      section in the Yocto Project Development Tasks Manual.
+
    :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
       Indicates the deploy directory used by ``do_bundle_initramfs`` where the
       :term:`INITRAMFS_IMAGE` will be fetched from.
-- 
2.34.1

[kirkstone][PATCH 08/16] ref-manual: Fix PACKAGECONFIG term and add an example

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: BELHADJ SALEM Talel <bhstalel@gmail.com>

PACKAGECONFIG's first and second flag value will be added to PACKAGECONFIG_CONFARGS
and then it will be added to the appropriate variable (EXTRA_OECMAKE, or ...)
So we need to only mention PACKAGECONFIG_CONFARGS and it will lead to other variables.

I added a custom example that can help understanding very well PACKAGECONFIG.

Signed-off-by: Talel BELHAJSALEM <bhstalel@gmail.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 50 ++++++++++++++++++++------
 1 file changed, 40 insertions(+), 10 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 0c573194e9..5d45f4a9f9 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5548,25 +5548,23 @@ system and gives an overview of their function and contents.
       omit any argument you like but must retain the separating commas. The
       order is important and specifies the following:
 
-      1. Extra arguments that should be added to the configure script
-         argument list (:term:`EXTRA_OECONF` or
-         :term:`PACKAGECONFIG_CONFARGS`) if
-         the feature is enabled.
+      #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
+         if the feature is enabled.
 
-      2. Extra arguments that should be added to :term:`EXTRA_OECONF` or
-         :term:`PACKAGECONFIG_CONFARGS` if the feature is disabled.
+      #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
+         if the feature is disabled.
 
-      3. Additional build dependencies (:term:`DEPENDS`)
+      #. Additional build dependencies (:term:`DEPENDS`)
          that should be added if the feature is enabled.
 
-      4. Additional runtime dependencies (:term:`RDEPENDS`)
+      #. Additional runtime dependencies (:term:`RDEPENDS`)
          that should be added if the feature is enabled.
 
-      5. Additional runtime recommendations
+      #. Additional runtime recommendations
          (:term:`RRECOMMENDS`) that should be added if
          the feature is enabled.
 
-      6. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG`
+      #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG`
          settings for this feature.
 
       Consider the following :term:`PACKAGECONFIG` block taken from the
@@ -5613,6 +5611,38 @@ system and gives an overview of their function and contents.
 
             PACKAGECONFIG:append:pn-recipename = " f4"
 
+      Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service
+      in which :term:`PACKAGECONFIG` is used to transform the systemd service
+      into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`::
+
+         example.c
+         example.service
+         CMakeLists.txt
+
+      The ``CMakeLists.txt`` file contains::
+
+         if(WITH_SYSTEMD)
+            install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd)
+         endif(WITH_SYSTEMD)
+
+      In order to enable the installation of ``example.service`` we need to
+      ensure that ``-DWITH_SYSTEMD=ON`` is passed to the ``cmake`` command
+      execution.  Recipes that have ``CMakeLists.txt`` generally inherit the
+      :ref:`ref-classes-cmake` class, that runs ``cmake`` with
+      :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be
+      appended to.  Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is
+      automatically filled with either the first or second element of
+      :term:`PACKAGECONFIG` flag value, the recipe would be like::
+
+         inherit cmake
+         PACKAGECONFIG = "systemd"
+         PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF"
+
+      A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER`
+      or not::
+
+         PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}"
+
    :term:`PACKAGECONFIG_CONFARGS`
       A space-separated list of configuration options generated from the
       :term:`PACKAGECONFIG` setting.
-- 
2.34.1

[kirkstone][PATCH 09/16] profile-manual: aesthetic cleanups

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Robert P. J. Day <rpjday@crashcourse.ca>

Various aesthetic cleanups of section 1 of that manual, including:

  * replace 'HOWTO' with manual
  * add more examples of sdk-related images
  * font fixes

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/profile-manual/intro.rst | 40 ++++++++++++++------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/documentation/profile-manual/intro.rst b/documentation/profile-manual/intro.rst
index 9c8fa3dbfa..86310cf318 100644
--- a/documentation/profile-manual/intro.rst
+++ b/documentation/profile-manual/intro.rst
@@ -7,43 +7,45 @@ Yocto Project Profiling and Tracing Manual
 Introduction
 ============
 
-Yocto bundles a number of tracing and profiling tools - this 'HOWTO'
+Yocto Project bundles a number of tracing and profiling tools --- this manual
 describes their basic usage and shows by example how to make use of them
-to examine application and system behavior.
+to analyze application and system behavior.
 
-The tools presented are for the most part completely open-ended and have
+The tools presented are, for the most part, completely open-ended and have
 quite good and/or extensive documentation of their own which can be used
 to solve just about any problem you might come across in Linux. Each
 section that describes a particular tool has links to that tool's
 documentation and website.
 
-The purpose of this 'HOWTO' is to present a set of common and generally
+The purpose of this manual is to present a set of common and generally
 useful tracing and profiling idioms along with their application (as
 appropriate) to each tool, in the context of a general-purpose
 'drill-down' methodology that can be applied to solving a large number
-(90%?) of problems. For help with more advanced usages and problems,
-please see the documentation and/or websites listed for each tool.
+of problems. For help with more advanced usages and problems,
+refer to the documentation and/or websites provided for each tool.
 
-The final section of this 'HOWTO' is a collection of real-world examples
-which we'll be continually adding to as we solve more problems using the
-tools - feel free to add your own examples to the list!
+The final section of this manual is a collection of real-world examples
+which we'll be continually updating as we solve more problems using the
+tools --- feel free to suggest additions to what you read here.
 
 General Setup
 =============
 
-Most of the tools are available only in 'sdk' images or in images built
-after adding 'tools-profile' to your local.conf. So, in order to be able
-to access all of the tools described here, please first build and boot
-an 'sdk' image e.g. ::
+Most of the tools are available only in ``sdk`` images or in images built
+after adding ``tools-profile`` to your ``local.conf`` file. So, in order to be able
+to access all of the tools described here, you can build and boot
+an ``sdk`` image, perhaps one of::
 
    $ bitbake core-image-sato-sdk
+   $ bitbake core-image-weston-sdk
+   $ bitbake core-image-rt-sdk
 
-or alternatively by adding 'tools-profile' to the EXTRA_IMAGE_FEATURES line in
-your local.conf::
+Alternatively,  you can add ``tools-profile`` to the :term:`EXTRA_IMAGE_FEATURES` line in
+your ``local.conf`` file::
 
    EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
 
-If you use the 'tools-profile' method, you don't need to build an sdk image -
+If you use the ``tools-profile`` method, you don't need to build an sdk image ---
 the tracing and profiling tools will be included in non-sdk images as well e.g.::
 
    $ bitbake core-image-sato
@@ -64,12 +66,12 @@ the tracing and profiling tools will be included in non-sdk images as well e.g.:
 If you've already built a stripped image, you can generate debug
 packages (xxx-dbg) which you can manually install as needed.
 
-To generate debug info for packages, you can add dbg-pkgs to
-EXTRA_IMAGE_FEATURES in local.conf. For example::
+To generate debug info for packages, you can add ``dbg-pkgs`` to
+:term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example::
 
    EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
 
-Additionally, in order to generate the right type of debuginfo, we also need to
+Additionally, in order to generate the right type of debug info, we also need to
 set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file::
 
    PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
-- 
2.34.1

[kirkstone][PATCH 10/16] ref-manual: variables: provide no-match example for COMPATIBLE_MACHINE

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Quentin Schulz <quentin.schulz@theobroma-systems.com>

COMPATIBLE_MACHINE is used to forbid the use of a recipe or its packages
for a specific set of machines.

In some cases, it may make more sense to have the logic inverted and
have the recipe always forbidden except for hand-picked machines. Such
could be the case for pieces of software that only support some
architectures. In that scenario, it is sometimes a bit easier on the eye
and for maintenance to use the OVERRIDES mechanism but for that, a
default should be set.

COMPATIBLE_MACHINE:aarch64 = "^(aarch64)$"
COMPATIBLE_MACHINE:mips64 = "^(mips64)$"

wouldn't do much because if COMPATIBLE_MACHINE isn't set, the recipe is
assumed compatible and therefore, if no default is provided we enter
that case.

Hence, we need to add

COMPATIBLE_MACHINE = "^$"

as default so that it only matches the empty string, which isn't
possible for MACHINEOVERRIDES.

Cc: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 5d45f4a9f9..38b13ecf8d 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1202,13 +1202,32 @@ system and gives an overview of their function and contents.
       speed since the build system skips parsing recipes not compatible
       with the current machine.
 
+      If one wants to have a recipe only available for some architectures
+      (here ``aarch64`` and ``mips64``), the following can be used::
+
+         COMPATIBLE_MACHINE = "^$"
+         COMPATIBLE_MACHINE:arch64 = "^(aarch64)$"
+         COMPATIBLE_MACHINE:mips64 = "^(mips64)$"
+
+      The first line means "match all machines whose :term:`MACHINEOVERRIDES`
+      contains the empty string", which will always be none.
+
+      The second is for matching all machines whose :term:`MACHINEOVERRIDES`
+      contains one override which is exactly ``aarch64``.
+
+      The third is for matching all machines whose :term:`MACHINEOVERRIDES`
+      contains one override which is exactly ``mips64``.
+
+      The same could be achieved with::
+
+         COMPATIBLE_MACHINE = "^(aarch64|mips64)$"
+
       .. note::
 
          When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from
          native, the recipe is always skipped. All native recipes must be
          entirely target independent and should not rely on :term:`MACHINE`.
 
-
    :term:`COMPLEMENTARY_GLOB`
       Defines wildcards to match when installing a list of complementary
       packages for all the packages explicitly (or implicitly) installed in
-- 
2.34.1

[kirkstone][PATCH 11/16] dev-manual: layers: Add notes about layer.conf

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: BELHADJ SALEM Talel <bhstalel@gmail.com>

As discussed before with Richard Purdie, the code supports this but the documentation does not.
Developers in general will not notice this or focus on it because they do not mess with the
layer.conf template file, but in my opinion I think more details can help.

Signed-off-by: Talel BELHAJSALEM <bhstalel@gmail.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/layers.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index c5c34134b6..16f62ee696 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -128,6 +128,20 @@ Follow these general steps to create your layer without using tools:
       variable is a good way to indicate if your particular layer is
       current.
 
+
+   .. note::
+
+      A layer does not have to contain only recipes ``.bb`` or append files
+      ``.bbappend``. Generally, developers create layers using
+      ``bitbake-layers create-layer``.
+      See ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`",
+      explaining how the ``layer.conf`` file is created from a template located in
+      ``meta/lib/bblayers/templates/layer.conf``.
+      In fact, none of the variables set in ``layer.conf`` are mandatory,
+      except when :term:`BBFILE_COLLECTIONS` is present. In this case
+      :term:`LAYERSERIES_COMPAT` and :term:`BBFILE_PATTERN` have to be
+      defined too.
+
 #. *Add Content:* Depending on the type of layer, add the content. If
    the layer adds support for a machine, add the machine configuration
    in a ``conf/machine/`` file within the layer. If the layer adds
-- 
2.34.1

[kirkstone][PATCH 12/16] brief-yoctoprojectqs: use new CDN mirror for sstate

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Recommended instead of the Yocto Project mirror, because expected
to be faster. Make sure you only set one such mirror.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: richard.purdie@linuxfoundation.org
---
 documentation/brief-yoctoprojectqs/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 545fa03f1e..20b2ebab6b 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -257,7 +257,7 @@ an entire Linux distribution, including the toolchain, from source.
          BB_SIGNATURE_HANDLER = "OEEquivHash"
          BB_HASHSERVE = "auto"
          BB_HASHSERVE_UPSTREAM = "hashserv.yocto.io:8687"
-         SSTATE_MIRRORS ?= "file://.* https://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
+         SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH"
 
 #. **Start the Build:** Continue with the following command to build an OS
    image for the target, which is ``core-image-sato`` in this example:
-- 
2.34.1

[kirkstone][PATCH 13/16] dev-manual: start.rst: remove obsolete reference

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Remove a reference to a web resource which is clearly marked as obsolete.
Replace the unnecessarily verbose note by just links to the mentioned tools.

[YOCTO #15233]

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
---
 documentation/dev-manual/start.rst | 24 ++++++------------------
 1 file changed, 6 insertions(+), 18 deletions(-)

diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 8938f0d772..3bc4244595 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -88,27 +88,15 @@ particular working environment and set of practices.
        For information about BitBake, see the
        :doc:`bitbake:index`.
 
-    It is relatively easy to set up Git services and create
-    infrastructure like :yocto_git:`/`, which is based on
-    server software called ``gitolite`` with ``cgit`` being used to
-    generate the web interface that lets you view the repositories. The
-    ``gitolite`` software identifies users using SSH keys and allows
+    It is relatively easy to set up Git services and create infrastructure like
+    :yocto_git:`/`, which is based on server software called
+    `Gitolite <https://gitolite.com>`__
+    with `cgit <https://git.zx2c4.com/cgit/about/>`__ being used to
+    generate the web interface that lets you view the repositories.
+    ``gitolite`` identifies users using SSH keys and allows
     branch-based access controls to repositories that you can control as
     little or as much as necessary.
 
-    .. note::
-
-       The setup of these services is beyond the scope of this manual.
-       However, here are sites describing how to perform setup:
-
-       -  `Gitolite <https://gitolite.com>`__: Information for
-          ``gitolite``.
-
-       -  `Interfaces, frontends, and
-          tools <https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools>`__:
-          Documentation on how to create interfaces and frontends for
-          Git.
-
 5.  *Set up the Application Development Machines:* As mentioned earlier,
     application developers are creating applications on top of existing
     software stacks. Following are some best practices for setting up
-- 
2.34.1

[kirkstone][PATCH 14/16] ref-manual: variables: add RECIPE_SYSROOT and RECIPE_SYSROOT_NATIVE

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: BELHADJ SALEM Talel <bhstalel@gmail.com>

Signed-off-by: Talel BELHAJSALEM <bhstalel@gmail.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 38 ++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 38b13ecf8d..517c35d032 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6456,6 +6456,39 @@ system and gives an overview of their function and contents.
       in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`"
       section.
 
+   :term:`RECIPE_SYSROOT`
+      This variable points to the directory that holds all files populated from
+      recipes specified in :term:`DEPENDS`. As the name indicates,
+      think of this variable as a custom root (``/``) for the recipe that will be
+      used by the compiler in order to find headers and other files needed to complete
+      its job.
+
+      This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET`
+      according to the type of the recipe and the build target.
+
+      To better understand this variable, consider the following examples:
+
+      -  For ``#include <header.h>``, ``header.h`` should be in ``"${RECIPE_SYSROOT}/usr/include"``
+
+      -  For ``-lexample``, ``libexample.so`` should be in ``"${RECIPE_SYSROOT}/lib"``
+         or other library sysroot directories.
+
+      The default value is ``"${WORKDIR}/recipe-sysroot"``.
+      Do not modify it.
+
+   :term:`RECIPE_SYSROOT_NATIVE`
+      This is similar to :term:`RECIPE_SYSROOT` but the populated files are from
+      ``-native`` recipes. This allows a recipe built for the target machine to
+      use ``native`` tools.
+
+      This variable is related to :term:`STAGING_DIR_NATIVE`.
+
+      The default value is ``"${WORKDIR}/recipe-sysroot-native"``.
+      Do not modify it.
+
+   :term:`REPODIR`
+      See :term:`bitbake:REPODIR` in the BitBake manual.
+
    :term:`REQUIRED_DISTRO_FEATURES`
       When inheriting the
       :ref:`features_check <ref-classes-features_check>`
@@ -7690,10 +7723,15 @@ system and gives an overview of their function and contents.
             for ``-native`` recipes, as they make use of host headers and
             libraries.
 
+      Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`.
+
    :term:`STAGING_DIR_NATIVE`
       Specifies the path to the sysroot directory used when building
       components that run on the build host itself.
 
+      The default value is ``"${RECIPE_SYSROOT_NATIVE}"``,
+      check :term:`RECIPE_SYSROOT_NATIVE`.
+
    :term:`STAGING_DIR_TARGET`
       Specifies the path to the sysroot used for the system for which the
       component generates code. For components that do not generate code,
-- 
2.34.1

[kirkstone][PATCH 15/16] ref-manual: variables: add TOOLCHAIN_OPTIONS variable

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: BELHADJ SALEM Talel <bhstalel@gmail.com>

Signed-off-by: Talel BELHAJSALEM <bhstalel@gmail.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 517c35d032..87081d94b9 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8508,6 +8508,16 @@ system and gives an overview of their function and contents.
       portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK`
       applying to SDKs.
 
+   :term:`TOOLCHAIN_OPTIONS`
+      This variable holds extra options passed to the compiler and the linker
+      for non ``-native`` recipes as they have to point to their custom
+      ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`::
+
+         TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}"
+
+      Native recipes don't need this variable to be set, as they are
+      built for the host machine with the native compiler.
+
    :term:`TOOLCHAIN_OUTPUTNAME`
       This variable defines the name used for the toolchain output. The
       :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
-- 
2.34.1

[kirkstone][PATCH 16/16] ref-manual: variables: add example for SYSROOT_DIRS variable

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: BELHADJ SALEM Talel <bhstalel@gmail.com>

Signed-off-by: Talel BELHAJSALEM <bhstalel@gmail.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 29 ++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 87081d94b9..827c94acd4 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7913,6 +7913,35 @@ system and gives an overview of their function and contents.
              ${libdir}/${BPN}/ptest \
              "
 
+      Consider the following example in which you need to manipulate this variable.
+      Assume you have a recipe ``A`` that provides a shared library ``.so.*`` that is
+      installed into a custom folder other than "``${libdir}``"
+      or "``${base_libdir}``", let's say "``/opt/lib``".
+
+      .. note::
+
+         This is not a recommended way to deal with shared libraries, but this
+         is just to show the usefulness of setting :term:`SYSROOT_DIRS`.
+
+      When a recipe ``B`` :term:`DEPENDS` on ``A``, it means what is in
+      :term:`SYSROOT_DIRS` will be copied from :term:`D` of the recipe ``B``
+      into ``B``'s :term:`SYSROOT_DESTDIR` that is "``${WORKDIR}/sysroot-destdir``".
+
+      Now, since ``/opt/lib`` is not in :term:`SYSROOT_DIRS`, it will never be copied to
+      ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So,
+      the linking process will fail.
+
+      To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`::
+
+         SYSROOT_DIRS:append = " /opt/lib"
+
+      .. note::
+         Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail
+         because the linker does not know that location, since :term:`TARGET_LDFLAGS`
+         doesn't contain it (if your recipe is for the target). Therefore, so you should add::
+
+            TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib"
+
    :term:`SYSROOT_DIRS_NATIVE`
       Extra directories staged into the sysroot by the
       :ref:`ref-tasks-populate_sysroot` task for
-- 
2.34.1