Add documentation on fragments

- terms.rst: Provide the definitions of a Configuration Fragment and a
  Built-in Fragment.
- ref-manual: Add a quick reference guide on bitbake-config-build, and
  list the available fragments in OE-Core.
  Document the underlying variables related to fragments in the
  glossary.
- dev-manual: give instructions on how to create new custom fragments.

(From yocto-docs rev: 0820b71c830cab4151b0219b6d4013c41f461c6e)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

4 files changed, 390 insertions, 0 deletions

diff --git a/documentation/ref-manual/fragments.rst b/documentation/ref-manual/fragments.rst
new file mode 100644
index 0000000000..c0118876c8
--- /dev/null
+++ b/documentation/ref-manual/fragments.rst
@@ -0,0 +1,258 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*****************************
+Using Configuration Fragments
+*****************************
+
+:term:`Configuration Fragments <Configuration Fragment>` define top level build
+configuration features that can be independently enabled and disabled using
+standard tooling. Such features are made of one or several build configuration
+statements that are either contained in a fragment file, or are set indirectly
+using the :term:`Built-in Fragment` mechanism.
+
+This document provides a quick reference of the :oe_git:`bitbake-config-build
+</bitbake/tree/bin/bitbake-config-build>` tool and lists the
+:term:`Configuration Fragments <Configuration Fragment>` and :term:`Built-in
+Fragments <Built-in Fragment>` available in the :term:`OpenEmbedded Build
+System` core repositories.
+
+.. note::
+
+   For details on how to define new fragments in your build, see the
+   :doc:`/dev-manual/creating-fragments` section of the Yocto Project Development
+   Tasks Manual.
+
+``bitbake-config-build`` Quick Reference
+========================================
+
+:term:`Configuration Fragments <Configuration Fragment>` are managed with the
+:oe_git:`bitbake-config-build </bitbake/tree/bin/bitbake-config-build>`
+command-line tool, which is available after :ref:`dev-manual/start:Initializing
+the Build Environment`.
+
+The ``bitbake-config-build`` command-line tool uses sub-commands to manage
+fragments, which are detailed in the sections below. For each sub-command, the
+``--help`` flag can be passed to get more information on the sub-command.
+
+.. _ref-bitbake-config-build-list-fragments:
+
+``bitbake-config-build list-fragments``
+---------------------------------------
+
+The :ref:`ref-bitbake-config-build-list-fragments` command will list the :term:`Built-in
+Fragments <Built-in Fragment>` and :term:`Configuration Fragments <Configuration
+Fragment>` that are currently available, and will also print which fragments are
+enabled or disabled.
+
+.. _ref-bitbake-config-build-show-fragment:
+
+``bitbake-config-build show-fragment``
+--------------------------------------
+
+The :ref:`ref-bitbake-config-build-show-fragment` command is used to show the
+location and value of a fragment. For example, running ``bitbake-config-build
+show-fragment core/yocto/sstate-mirror-cdn`` will show the content of the
+:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment.
+
+.. _ref-bitbake-config-build-enable-fragment:
+
+``bitbake-config-build enable-fragment``
+----------------------------------------
+
+The :ref:`ref-bitbake-config-build-enable-fragment` command is used to enable a
+fragment. When a fragment is enabled, the configuration variables of this
+fragment are parsed by :term:`BitBake` and their values are available globally
+in your build.
+
+From the list obtained with the :ref:`ref-bitbake-config-build-list-fragments`
+command, you can determine which fragments can be enabled for your build.
+
+For example, the following command would enable the
+:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
+
+   bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
+
+.. note::
+
+   Multiple fragments can be enabled at once with the same command::
+
+      bitbake-config-build enable-fragment <fragment1> <fragment2> ...
+
+:term:`Built-in fragments <Built-in Fragment>` are enabled the same way, and
+their values are defined from the command-line directly. For example, the
+following command sets the ``qemuarm64`` :term:`MACHINE` through the
+:ref:`ref-fragments-builtin-core-machine` fragment::
+
+   bitbake-config-build enable-fragment machine/qemuarm64
+
+This fragment can be overridden from the command-line by setting it to another
+value, for example::
+
+   bitbake-config-build enable-fragment machine/qemux86-64
+
+Note that in this case, the fragment will be defined twice in
+:term:`OE_FRAGMENTS`, and the last value is taken into account:
+
+.. code-block::
+   :caption: build/conf/auto.conf
+
+   OE_FRAGMENTS += " ... machine/qemuarm64 machine/qemux86-64"
+
+In the above example, the value of :term:`MACHINE` is thus equal to
+``qemux86-64``.
+
+When a fragment is enabled with :ref:`ref-bitbake-config-build-enable-fragment`,
+its name is automatically appended to the :term:`OE_FRAGMENTS` variable in
+:ref:`structure-build-conf-auto.conf`.
+
+.. note::
+
+   It is also possible to manually remove or add fragments by modifying the
+   :term:`OE_FRAGMENTS` variable in a configuration file such as
+   :ref:`structure-build-conf-local.conf`.
+
+.. _ref-bitbake-config-build-disable-fragment:
+
+``bitbake-config-build disable-fragment``
+-----------------------------------------
+
+Any fragment enabled with the :ref:`ref-bitbake-config-build-enable-fragment`
+command can be disabled with the :ref:`ref-bitbake-config-build-disable-fragment`
+command. The list of enabled fragments can be obtained with
+:ref:`ref-bitbake-config-build-list-fragments`.
+
+For example, the following command disables the
+:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
+
+   bitbake-config-build disable-fragment core/yocto/sstate-mirror-cdn
+
+Likewise, :term:`Built-in Fragments <Built-in Fragment>` are disabled the
+same way. For example, this would disable the ``machine/qemuarm64`` fragment::
+
+   bitbake-config-build disable-fragment machine/qemuarm64
+
+.. note::
+
+   Multiple fragments can be disabled at once with the same command::
+
+      bitbake-config-build disable-fragment <fragment1> <fragment2>
+
+.. _ref-bitbake-config-build-disable-all-fragments:
+
+``bitbake-config-build disable-all-fragments``
+----------------------------------------------
+
+The :ref:`ref-bitbake-config-build-disable-all-fragments` command disables all of the
+currently enabled fragments.  The list of enabled fragments can be obtained with
+:ref:`ref-bitbake-config-build-list-fragments`.
+
+This command is run without arguments::
+
+   bitbake-config-build disable-all-fragments
+
+Core Fragments
+==============
+
+Core Built-in Fragments
+-----------------------
+
+:term:`Built-in Fragments <Built-in Fragment>` are used to assign a single
+variable globally. The :term:`OpenEmbedded Build System` defines multiple
+built-in fragments that are detailed in this section.
+
+.. _ref-fragments-builtin-core-machine:
+
+``machine/``
+~~~~~~~~~~~~
+
+The ``machine/`` :term:`built-in fragment` can be used to assign the value of
+the :term:`MACHINE` variable globally.
+
+.. _ref-fragments-builtin-core-distro:
+
+``distro/``
+~~~~~~~~~~~
+
+The ``distro/`` :term:`built-in fragment` can be used to assign the value of
+the :term:`DISTRO` variable globally.
+
+Core Configuration Fragments
+----------------------------
+
+Yocto Project Fragments
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This group defines fragments related to the Yocto Project infrastructure in
+general.
+
+.. _ref-fragments-core-yocto-sstate-mirror-cdn:
+
+``core/yocto/sstate-mirror-cdn``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``core/yocto/sstate-mirror-cdn`` :term:`configuration fragment` can be used
+to set up :term:`BB_HASHSERVE_UPSTREAM` and :term:`SSTATE_MIRRORS` to use
+pre-built :ref:`shared state cache <overview-manual/concepts:shared state
+cache>` artifacts for standard Yocto build configurations.
+
+This will mean the build will query the Yocto Project mirrors to check for
+artifacts at the start of builds, which does slow it down initially but it will
+then speed up the builds by not having to build things if they are present in
+the cache. It assumes you can download something faster than you can build it
+which will depend on your network configuration.
+
+Yocto Project Autobuilder Fragments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This group defines fragment used for the Yocto Project Autobuilder. For details,
+see the :ref:`test-manual/intro:Yocto Project Autobuilder Overview` section of
+the Yocto Project Test Environment Manual.
+
+.. _ref-fragment-core-yocto-autobuilder-autobuilder:
+
+``core/yocto-autobuilder/autobuilder``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``core/yocto-autobuilder/autobuilder`` fragment defines common variables
+used in builds started by the Yocto Project Autobuilder.
+
+.. _ref-fragment-core-yocto-autobuilder-autobuilder-resource-constraints:
+
+``core/yocto-autobuilder/autobuilder-resource-constraints``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``core/yocto-autobuilder/autobuilder`` fragment defines variables for
+limiting the resources used by the Yocto Project Autobuilder during builds. For
+more details on how to limit resources, see the :doc:`/dev-manual/limiting-resources`
+section of the Yocto Project Development Tasks Manual.
+
+.. _ref-fragment-core-yocto-autobuilder-multilib-mips64-n32:
+
+``core/yocto-autobuilder/multilib-mips64-n32``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``core/yocto-autobuilder/multilib-mips64-n32`` fragment enables
+tri-architecture :ref:`multilib <dev-manual/libraries:Combining Multiple
+Versions of Library Files into One Image>` configurations for :wikipedia:`MIPS64
+<MIPS_architecture>` machines, which includes ``mips64-n32``, ``mips64``, and
+``mips32r2``.
+
+.. _ref-fragment-core-yocto-autobuilder-multilib-x86-lib32:
+
+``core/yocto-autobuilder/multilib-x86-lib32``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``core/yocto-autobuilder/multilib-x86-lib32`` fragment enables
+:ref:`multilib <dev-manual/libraries:Combining Multiple Versions of Library
+Files into One Image>` configurations for supporting 32-bit libraries on 64-bit
+:wikipedia:`X86 <X86>` builds.
+
+.. _ref-fragment-core-yocto-autobuilder-multilib-x86-lib64:
+
+``core/yocto-autobuilder/multilib-x86-lib64``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``core/yocto-autobuilder/multilib-x86-lib64`` fragment enables
+:ref:`multilib <dev-manual/libraries:Combining Multiple Versions of Library
+Files into One Image>` configurations for supporting 64-bit libraries on 32-bit
+:wikipedia:`X86 <X86>` builds.
diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst
index 53fa98cc99..aa1a63e050 100644
--- a/documentation/ref-manual/index.rst
+++ b/documentation/ref-manual/index.rst
@@ -17,6 +17,7 @@ Yocto Project Reference Manual
    structure
    classes
    tasks
+   fragments
    devtool-reference
    kickstart
    qa-checks
diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
index f3d3d059d1..e25c714d9b 100644
--- a/documentation/ref-manual/terms.rst
+++ b/documentation/ref-manual/terms.rst
@@ -131,6 +131,53 @@ universal, the list includes them just in case:
       A variant of :term:`buildtools`, just providing the required
       version of ``make`` to run the OpenEmbedded build system.
 
+   :term:`Built-in Fragment`
+      A built-in fragment is a specific kind of :term:`Configuration Fragment`
+      that affects the value of a single variable globally. :term:`Built-in
+      Fragments <Built-in Fragment>` do not require a separate configuration
+      file, but like a standard :term:`Configuration Fragment`, Built-in
+      Fragments can be enabled or disabled using the :oe_git:`bitbake-config-build
+      </bitbake/tree/bin/bitbake-config-build>` command-line utility.
+
+      When declared, a built-in fragment follows the following naming
+      convention::
+
+         <fragment>:<variable name>
+
+      Where:
+
+      -  ``<fragment>`` is the name of the built-in fragment.
+      -  ``<variable name>`` is the name of the variable to be modified by this
+         fragment.
+
+      For example::
+
+         machine:MACHINE
+
+      Will setup the ``machine`` Built-in Fragment for modifying the value of
+      the :term:`MACHINE` variable.
+
+      Setting the :term:`MACHINE` variable through this fragment must follow
+      this syntax::
+
+         machine/qemux86-64
+
+      This sets the value of :term:`MACHINE` to ``qemux86-64``.
+
+      In :term:`OpenEmbedded-Core (OE-Core)`, the list of available
+      :term:`Built-in Fragments <Built-in Fragment>` can be obtained from the
+      :term:`OE_FRAGMENTS_BUILTIN` variable.
+
+      For more details on fragments, see:
+
+      -  The :doc:`/ref-manual/fragments` section of the Yocto Project Reference
+         Manual for a list of fragments the :term:`OpenEmbedded Build System`
+         supports, and a quick reference guide on how to manage fragments.
+
+      -  The :doc:`/dev-manual/creating-fragments` section of the Yocto Project
+         Development Tasks Manual for details on how to create new fragments
+         in your build.
+
    :term:`Classes`
       Files that provide for logic encapsulation and inheritance so that
       commonly used patterns can be defined once and then easily used in
@@ -154,6 +201,51 @@ universal, the list includes them just in case:
       only used when building for that target (e.g. the
       :file:`machine/beaglebone.conf` configuration file defines variables for
       the Texas Instruments ARM Cortex-A8 development board).
+      :term:`Configuration Fragments <Configuration Fragment>` such as
+      :ref:`ref-fragments-core-yocto-sstate-mirror-cdn` define snippets of
+      configuration that can be enabled from the command-line.
+
+   :term:`Configuration Fragment`
+      A :term:`Configuration Fragment` (also called Standard :term:`Configuration
+      Fragment`) is a :term:`configuration file` that contains configuration
+      statements such as variable assignments, affecting the build at a
+      global-level when the fragment is enabled. By default, configuration
+      fragments are located in the :file:`conf/fragments/` directory of a
+      :term:`Layer`.
+
+      .. note::
+
+         Another form of fragment not to be confounded with Standard
+         :term:`Configuration Fragments <Configuration Fragment>` are
+         :term:`Built-in Fragments <Built-in Fragment>` which are used to assign
+         a single variable value globally.
+
+      A fragment :term:`configuration file` must contain a summary
+      (:term:`BB_CONF_FRAGMENT_SUMMARY`) and a description
+      (:term:`BB_CONF_FRAGMENT_DESCRIPTION`) explaining the purpose of the
+      fragment.
+
+      In :term:`OpenEmbedded-Core (OE-Core)`, the location of fragments and what
+      variables are required in a fragment is specified in :oe_git:`bitbake.conf
+      </openembedded-core/tree/meta/conf/bitbake.conf>` thanks to the
+      :ref:`addfragments <bitbake-user-manual/bitbake-user-manual-metadata:\`\`addfragments\`\`
+      directive>` directive and the :term:`OE_FRAGMENTS`,
+      :term:`OE_FRAGMENTS_METADATA_VARS` and :term:`OE_FRAGMENTS_BUILTIN`
+      variables.
+
+      Fragments can be listed, enabled and disabled with the
+      :oe_git:`bitbake-config-build </bitbake/tree/bin/bitbake-config-build>`
+      command-line utility.
+
+      For more details on fragments, see:
+
+      -  The :doc:`/ref-manual/fragments` section of the Yocto Project Reference
+         Manual for a list of fragments the :term:`OpenEmbedded Build System`
+         supports, and a quick reference guide on how to manage fragments.
+
+      -  The :doc:`/dev-manual/creating-fragments` section of the Yocto Project
+         Development Tasks Manual for details on how to create new fragments
+         in your build.
 
    :term:`Container Layer`
       A flexible definition that typically refers to a single Git checkout
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 2f9f1a9d80..aefe598a56 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -397,6 +397,18 @@ system and gives an overview of their function and contents.
    :term:`BB_CHECK_SSL_CERTS`
       See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual.
 
+   :term:`BB_CONF_FRAGMENT_DESCRIPTION`
+      The :term:`BB_CONF_FRAGMENT_DESCRIPTION` variable defines the textual
+      description of a :term:`Configuration Fragment`. For details on how to use
+      fragments, see the :doc:`/ref-manual/fragments` section of the Yocto
+      Project Reference Manual.
+
+   :term:`BB_CONF_FRAGMENT_SUMMARY`
+      The :term:`BB_CONF_FRAGMENT_SUMMARY` variable defines the one-line textual
+      summary of a :term:`Configuration Fragment`. For details on how to use
+      fragments, see the :doc:`/ref-manual/fragments` section of the Yocto
+      Project Reference Manual.
+
    :term:`BB_CONSOLELOG`
       See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual.
 
@@ -6230,6 +6242,33 @@ system and gives an overview of their function and contents.
       :term:`Source Directory` for details on how this class
       applies these additional sed command arguments.
 
+   :term:`OE_FRAGMENTS`
+      The :term:`OE_FRAGMENTS` variable holds the list of :term:`Configuration
+      Fragments <Configuration Fragment>` currently enabled for the build. For
+      details on how to use fragments, see the :doc:`/ref-manual/fragments`
+      section of the Yocto Project Reference Manual.
+
+   :term:`OE_FRAGMENTS_BUILTIN`
+      The :term:`OE_FRAGMENTS_BUILTIN` variable holds the list of
+      :term:`Built-in Fragments <Built-in Fragment>` available for being set with
+      :oe_git:`bitbake-config-build </bitbake/tree/bin/bitbake-config-build>`.
+      For details on how to use fragments, see the :doc:`/ref-manual/fragments`
+      section of the Yocto Project Reference Manual.
+
+   :term:`OE_FRAGMENTS_METADATA_VARS`
+      The :term:`OE_FRAGMENTS_METADATA_VARS` variable holds the list of
+      variables that are required to set in a standard :term:`Configuration
+      Fragment` file. In :term:`OpenEmbedded-Core (OE-Core)`, these variables
+      are :term:`BB_CONF_FRAGMENT_SUMMARY` and
+      :term:`BB_CONF_FRAGMENT_DESCRIPTION`.
+
+   :term:`OE_FRAGMENTS_PREFIX`
+      The :term:`OE_FRAGMENTS_PREFIX` variable defines the prefix where
+      :term:`BitBake` tries to locate :term:`Configuration Fragments
+      <Configuration Fragment>` in :term:`layers <Layer>`. For details on how to
+      use fragments, see the :doc:`/ref-manual/fragments` section of the Yocto
+      Project Reference Manual.
+
    :term:`OE_INIT_ENV_SCRIPT`
       The name of the build environment setup script for the purposes of
       setting up the environment within the extensible SDK. The default