1 files changed, 189 insertions, 43 deletions

diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
index bf46148876..b18c4183b6 100644
--- a/documentation/ref-manual/terms.rst
+++ b/documentation/ref-manual/terms.rst
@@ -4,7 +4,7 @@
 Yocto Project Terms
 *******************
 
-Following is a list of terms and definitions users new to the Yocto Project
+Here is a list of terms and definitions users new to the Yocto Project
 development environment might find helpful. While some of these terms are
 universal, the list includes them just in case:
 
@@ -21,18 +21,17 @@ universal, the list includes them just in case:
 
       Information in append files extends or overrides the information in the
       similarly-named recipe file. For an example of an append file in use, see
-      the ":ref:`dev-manual/common-tasks:Using .bbappend Files in
-      Your Layer`" section in the Yocto Project Development Tasks Manual.
+      the    ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
+      section in the Yocto Project Development Tasks Manual.
 
       When you name an append file, you can use the "``%``" wildcard character
       to allow for matching recipe names. For example, suppose you have an
-      append file named as follows:
-      ::
-      
+      append file named as follows::
+
          busybox_1.21.%.bbappend
 
       That append file
-      would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
+      would match any ``busybox_1.21.x.bb`` version of the recipe. So,
       the append file would match any of the following recipe names:
 
       .. code-block:: shell
@@ -65,54 +64,73 @@ universal, the list includes them just in case:
       builds. The area is created when you ``source`` the setup environment
       script that is found in the Source Directory
       (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The
-      :term:`TOPDIR` variable points to the Build Directory.
+      :term:`TOPDIR` variable points to the :term:`Build Directory`.
 
-      You have a lot of flexibility when creating the Build Directory.
-      Following are some examples that show how to create the directory.  The
+      You have a lot of flexibility when creating the :term:`Build Directory`.
+      Here are some examples that show how to create the directory.  The
       examples assume your :term:`Source Directory` is named ``poky``:
 
-         -  Create the Build Directory inside your Source Directory and let
-            the name of the Build Directory default to ``build``:
+         -  Create the :term:`Build Directory` inside your Source Directory and let
+            the name of the :term:`Build Directory` default to ``build``:
 
             .. code-block:: shell
 
-               $ cd $HOME/poky
+               $ cd poky
                $ source oe-init-build-env
 
-         -  Create the Build Directory inside your home directory and
+         -  Create the :term:`Build Directory` inside your home directory and
             specifically name it ``test-builds``:
 
             .. code-block:: shell
 
-               $ cd $HOME
                $ source poky/oe-init-build-env test-builds
 
-         -  Provide a directory path and specifically name the Build
-            Directory. Any intermediate folders in the pathname must exist.
-            This next example creates a Build Directory named
-            ``YP-&POKYVERSION;`` in your home directory within the existing
-            directory ``mybuilds``:
+         -  Provide a directory path and specifically name the
+            :term:`Build Directory`. Any intermediate folders in the pathname
+            must exist.  This next example creates a :term:`Build Directory`
+            named ``YP-&DISTRO;`` within the existing directory ``mybuilds``:
 
             .. code-block:: shell
 
-               $ cd $HOME
-               $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-&POKYVERSION;
+               $ source poky/oe-init-build-env mybuilds/YP-&DISTRO;
 
       .. note::
 
-         By default, the Build Directory contains :term:`TMPDIR`, which is a
-         temporary directory the build system uses for its work. ``TMPDIR`` cannot
-         be under NFS. Thus, by default, the Build Directory cannot be under
-         NFS. However, if you need the Build Directory to be under NFS, you can
-         set this up by setting ``TMPDIR`` in your ``local.conf`` file to use a local
-         drive. Doing so effectively separates ``TMPDIR`` from :term:`TOPDIR`, which is the
-         Build Directory.
+         By default, the :term:`Build Directory` contains :term:`TMPDIR`, which is a
+         temporary directory the build system uses for its work. :term:`TMPDIR` cannot
+         be under NFS. Thus, by default, the :term:`Build Directory` cannot be under
+         NFS. However, if you need the :term:`Build Directory` to be under NFS, you can
+         set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local
+         drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the
+         :term:`Build Directory`.
 
    :term:`Build Host`
       The system used to build images in a Yocto Project Development
       environment. The build system is sometimes referred to as the development
       host.
 
+   :term:`buildtools`
+      Build tools in binary form, providing required versions of development
+      tools (such as Git, GCC, Python and make), to run the OpenEmbedded build
+      system on a development host without such minimum versions.
+
+      See the ":ref:`system-requirements-buildtools`" paragraph in the
+      Reference Manual for details about downloading or building an archive
+      of such tools.
+
+   :term:`buildtools-extended`
+      A set of :term:`buildtools` binaries extended with additional development
+      tools, such as a required version of the GCC compiler to run the
+      OpenEmbedded build system.
+
+      See the ":ref:`system-requirements-buildtools`" paragraph in the
+      Reference Manual for details about downloading or building an archive
+      of such tools.
+
+   :term:`buildtools-make`
+      A variant of :term:`buildtools`, just providing the required
+      version of ``make`` to run the OpenEmbedded build system.
+
    :term:`Classes`
       Files that provide for logic encapsulation and inheritance so that
       commonly used patterns can be defined once and then easily used in
@@ -138,10 +156,25 @@ universal, the list includes them just in case:
       the Texas Instruments ARM Cortex-A8 development board).
 
    :term:`Container Layer`
-      Layers that hold other layers. An example of a container layer is
-      OpenEmbedded's `meta-openembedded
-      <https://github.com/openembedded/meta-openembedded>`_ layer. The
-      ``meta-openembedded`` layer contains many ``meta-*`` layers.
+      A flexible definition that typically refers to a single Git checkout
+      which contains multiple (and typically related) sub-layers which can
+      be included independently in your project's ``bblayers.conf`` file.
+
+      In some cases, such as with OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>`
+      layer, the top level ``meta-openembedded/`` directory is not itself an actual layer,
+      so you would never explicitly include it in a ``bblayers.conf`` file;
+      rather, you would include any number of its layer subdirectories, such as
+      :oe_git:`meta-oe </meta-openembedded/tree/meta-oe>`, :oe_git:`meta-python
+      </meta-openembedded/tree/meta-python>` and so on.
+
+      On the other hand, some container layers (such as
+      :yocto_git:`meta-security </meta-security>`)
+      have a top-level directory that is itself an actual layer, as well as
+      a variety of sub-layers, both of which could be included in your
+      ``bblayers.conf`` file.
+
+      In either case, the phrase "container layer" is simply used to describe
+      a directory structure which contains multiple valid OpenEmbedded layers.
 
    :term:`Cross-Development Toolchain`
       In general, a cross-development toolchain is a collection of software
@@ -179,6 +212,48 @@ universal, the list includes them just in case:
       of the supported image types that the Yocto Project provides, see the
       ":ref:`ref-manual/images:Images`" chapter.
 
+   :term:`Initramfs`
+      An Initial RAM Filesystem (:term:`Initramfs`) is an optionally compressed
+      :wikipedia:`cpio <Cpio>` archive which is extracted
+      by the Linux kernel into RAM in a special :wikipedia:`tmpfs <Tmpfs>`
+      instance, used as the initial root filesystem.
+
+      This is a replacement for the legacy init RAM disk ("initrd")
+      technique, booting on an emulated block device in RAM, but being less
+      efficient because of the overhead of going through a filesystem and
+      having to duplicate accessed file contents in the file cache in RAM,
+      as for any block device.
+
+      .. note::
+
+         As far as bootloaders are concerned, :term:`Initramfs` and "initrd"
+         images are still copied to RAM in the same way. That's why most
+         most bootloaders refer to :term:`Initramfs` images as "initrd"
+         or "init RAM disk".
+
+      This kind of mechanism is typically used for two reasons:
+
+      -  For booting the same kernel binary on multiple systems requiring
+         different device drivers. The :term:`Initramfs` image is then customized
+         for each type of system, to include the specific kernel modules
+         necessary to access the final root filesystem. This technique
+         is used on all GNU / Linux distributions for desktops and servers.
+
+      -  For booting faster. As the root filesystem is extracted into RAM,
+         accessing the first user-space applications is very fast, compared
+         to having to initialize a block device, to access multiple blocks
+         from it, and to go through a filesystem having its own overhead.
+         For example, this allows to display a splashscreen very early,
+         and to later take care of mounting the final root filesystem and
+         loading less time-critical kernel drivers.
+
+      This cpio archive can either be loaded to RAM by the bootloader,
+      or be included in the kernel binary.
+
+      For information on creating and using an :term:`Initramfs`, see the
+      ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`"
+      section in the Yocto Project Development Tasks Manual.
+
    :term:`Layer`
       A collection of related recipes. Layers allow you to consolidate related
       metadata to customize your build. Layers also isolate information used
@@ -192,12 +267,18 @@ universal, the list includes them just in case:
       ":ref:`overview-manual/yp-intro:The Yocto Project Layer
       Model`" section in the Yocto Project Overview and Concepts Manual. For
       more detailed information on layers, see the
-      ":ref:`dev-manual/common-tasks:Understanding and Creating
+      ":ref:`dev-manual/layers:Understanding and Creating
       Layers`" section in the Yocto Project Development Tasks Manual. For a
       discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
       Layers`" section in the Yocto Project Board Support Packages (BSP)
       Developer's Guide.
 
+   :term:`LTS`
+      This term means "Long Term Support", and in the context of the Yocto
+      Project, it corresponds to selected stable releases for which bug and
+      security fixes are provided for at least four years. See
+      the :ref:`ref-long-term-support-releases` section for details.
+
    :term:`Metadata`
       A key element of the Yocto Project is the Metadata that
       is used to construct a Linux distribution and is contained in the
@@ -217,6 +298,12 @@ universal, the list includes them just in case:
       :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>`
       Git repository.
 
+   :term:`Mixin`
+      A :term:`Mixin` layer is a layer which can be created by the community to
+      add a specific feature or support a new version of some package for an
+      :term:`LTS` release. See the :ref:`ref-long-term-support-releases`
+      section for details.
+
    :term:`OpenEmbedded-Core (OE-Core)`
       OE-Core is metadata comprised of
       foundational recipes, classes, and associated files that are meant to
@@ -257,7 +344,7 @@ universal, the list includes them just in case:
       your Linux distribution.
 
       Another point worth noting is that historically within the Yocto
-      Project, recipes were referred to as packages - thus, the existence
+      Project, recipes were referred to as packages --- thus, the existence
       of several BitBake variables that are seemingly mis-named, (e.g.
       :term:`PR`, :term:`PV`, and
       :term:`PE`).
@@ -310,6 +397,23 @@ universal, the list includes them just in case:
       :term:`build host<Build Host>` and other components, that can
       work on specific hardware.
 
+   :term:`SBOM`
+      This term means *Software Bill of Materials*. When you distribute
+      software, it offers a description of all the components you used,
+      their corresponding licenses, their dependencies, the changes that were
+      applied and the known vulnerabilities that were fixed.
+
+      This can be used by the recipients of the software to assess
+      their exposure to license compliance and security vulnerability issues.
+
+      See the :wikipedia:`Software Supply Chain <Software_supply_chain>`
+      article on Wikipedia for more details.
+
+      The OpenEmbedded Build System can generate such documentation for your
+      project, in :term:`SPDX` format, based on all the metadata it used to
+      build the software images. See the ":ref:`dev-manual/sbom:creating
+      a software bill of materials`" section of the Development Tasks manual.
+
    :term:`Source Directory`
      This term refers to the directory structure
      created as a result of creating a local copy of the ``poky`` Git
@@ -344,19 +448,19 @@ universal, the list includes them just in case:
      repository results in a local Git repository whose top-level folder
      is also named "poky".
 
-     While it is not recommended that you use tarball expansion to set up
+     While it is not recommended that you use tarball extraction to set up
      the Source Directory, if you do, the top-level directory name of the
      Source Directory is derived from the Yocto Project release tarball.
-     For example, downloading and unpacking
-     :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2`
-     results in a Source Directory whose root folder is named
-     ``&YOCTO_POKY;``.
+     For example, downloading and unpacking poky tarballs from
+     :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/`
+     results in a Source Directory whose root folder is named poky.
+
 
      It is important to understand the differences between the Source
      Directory created by unpacking a released tarball as compared to
      cloning ``git://git.yoctoproject.org/poky``. When you unpack a
      tarball, you have an exact copy of the files based on the time of
-     release - a fixed release point. Any changes you make to your local
+     release --- a fixed release point. Any changes you make to your local
      files in the Source Directory are on top of the release and will
      remain local only. On the other hand, when you clone the ``poky`` Git
      repository, you have an active development repository with access to
@@ -370,11 +474,53 @@ universal, the list includes them just in case:
      ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
      section in the Yocto Project Overview and Concepts Manual.
 
+   :term:`SPDX`
+      This term means *Software Package Data Exchange*, and is used as an open
+      standard for providing a *Software Bill of Materials* (:term:`SBOM`).
+      This standard is developed through a `Linux Foundation project
+      <https://spdx.dev/>`__ and is used by the OpenEmbedded Build System to
+      provide an :term:`SBOM` associated to each software image.
+
+      For details, see Wikipedia's :wikipedia:`SPDX page <Software_Package_Data_Exchange>`
+      and the ":ref:`dev-manual/sbom:creating a software bill of materials`"
+      section of the Development Tasks manual.
+
+   :term:`Sysroot`
+      When cross-compiling, the target file system may be differently laid
+      out and contain different things compared to the host system. The concept
+      of a *sysroot* is directory which looks like the target filesystem and
+      can be used to cross-compile against.
+
+      In the context of cross-compiling toolchains, a *sysroot*
+      typically contains C library and kernel headers, plus the
+      compiled binaries for the C library. A *multilib toolchain*
+      can contain multiple variants of the C library binaries,
+      each compiled for a target instruction set (such as ``armv5``,
+      ``armv7`` and ``armv8``), and possibly optimized for a specific CPU core.
+
+      In the more specific context of the OpenEmbedded build System and
+      of the Yocto Project, each recipe has two sysroots:
+
+      -  A *target sysroot* contains all the **target** libraries and headers
+         needed to build the recipe.
+
+      -  A *native sysroot* contains all the **host** files and executables
+         needed to build the recipe.
+
+      See the :term:`SYSROOT_* <SYSROOT_DESTDIR>` variables controlling
+      how sysroots are created and stored.
+
    :term:`Task`
-      A unit of execution for BitBake (e.g.
+      A per-recipe unit of execution for BitBake (e.g.
       :ref:`ref-tasks-compile`,
       :ref:`ref-tasks-fetch`,
       :ref:`ref-tasks-patch`, and so forth).
+      One of the major benefits of the build system is that, since each
+      recipe will typically spawn the execution of numerous tasks,
+      it is entirely possible that many tasks can execute in parallel,
+      either tasks from separate recipes or independent tasks within
+      the same recipe, potentially up to the parallelism of your
+      build system.
 
    :term:`Toaster`
       A web interface to the Yocto Project's :term:`OpenEmbedded Build System`.
@@ -385,7 +531,7 @@ universal, the list includes them just in case:
 
    :term:`Upstream`
       A reference to source code or repositories that are not
-      local to the development system but located in a master area that is
+      local to the development system but located in a remote area that is
       controlled by the maintainer of the source code. For example, in
       order for a developer to work on a particular piece of code, they
       need to first get a copy of it from an "upstream" source.