[v2,2/2] 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.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/creating-fragments.rst | 146 ++++++++++++++
 documentation/dev-manual/index.rst              |   1 +
 documentation/ref-manual/fragments.rst          | 258 ++++++++++++++++++++++++
 documentation/ref-manual/index.rst              |   1 +
 documentation/ref-manual/terms.rst              |  92 +++++++++
 documentation/ref-manual/variables.rst          |  39 ++++
 6 files changed, 537 insertions(+)

Thanks, this is fine. Now the stage is set for bitbake-setup documentation.

Alex

On Fri, 26 Sept 2025 at 15:06, Antonin Godard
<antonin.godard@bootlin.com> wrote:
>
> - 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.
>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>  documentation/dev-manual/creating-fragments.rst | 146 ++++++++++++++
>  documentation/dev-manual/index.rst              |   1 +
>  documentation/ref-manual/fragments.rst          | 258 ++++++++++++++++++++++++
>  documentation/ref-manual/index.rst              |   1 +
>  documentation/ref-manual/terms.rst              |  92 +++++++++
>  documentation/ref-manual/variables.rst          |  39 ++++
>  6 files changed, 537 insertions(+)
>
> diff --git a/documentation/dev-manual/creating-fragments.rst b/documentation/dev-manual/creating-fragments.rst
> new file mode 100644
> index 000000000..7f437d7c9
> --- /dev/null
> +++ b/documentation/dev-manual/creating-fragments.rst
> @@ -0,0 +1,146 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +Creating New Configuration Fragments In Your Build
> +**************************************************
> +
> +: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 section will describe how to create new fragments for your builds.
> +
> +There are two kinds of configuration fragments:
> +
> +-  Standard :term:`Configuration Fragments <Configuration Fragment>` which a
> +   stored in a file. These fragments include a summary and a description,
> +   following by configuration statements.
> +
> +-  :term:`Built-in Fragments <Built-in Fragment>` which can be used to assign a
> +   value to a single variable and do not require a separate definition file.
> +   They are especially useful when a list of possible values is very long (or
> +   infinite).
> +
> +Creating A Standard Configuration Fragment
> +==========================================
> +
> +By default, all configuration fragments are located within the
> +``conf/fragments`` directory of a :term:`layer`. This location is defined by the
> +:term:`OE_FRAGMENTS_PREFIX` variable which, in turn, is used as a parameter in an
> +:ref:`addfragments <bitbake-user-manual/bitbake-user-manual-metadata:\`\`addfragments\`\`
> +directive>` directive in :oe_git:`bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`.
> +
> +You can create one or more :term:`configuration fragment` files in your
> +:term:`layer` in this directory. Let's take the following example, where
> +``custom-fragment.conf`` is our custom fragment file::
> +
> +   meta-custom
> +   ├── conf
> +   │   ├── fragments
> +   │   │   └── custom-fragment.conf
> +   │   └── layer.conf
> +   ...
> +
> +For our ``custom-fragment.conf`` file, the following variables **must** be set
> +for our fragment to be considered a valid fragment by the :term:`OpenEmbedded
> +Build System`:
> +
> +-  :term:`BB_CONF_FRAGMENT_SUMMARY`: a one-line summary of this fragment.
> +
> +-  :term:`BB_CONF_FRAGMENT_DESCRIPTION`: a description of this fragment.
> +
> +.. note::
> +
> +   The :term:`BB_CONF_FRAGMENT_SUMMARY` and :term:`BB_CONF_FRAGMENT_DESCRIPTION`
> +   variables are also passed as parameters in an :ref:`addfragments
> +   <bitbake-user-manual/bitbake-user-manual-metadata:\`\`addfragments\`\`
> +   directive>` directive in :oe_git:`bitbake.conf
> +   </openembedded-core/tree/meta/conf/bitbake.conf>`.
> +
> +After creating these variables, our custom fragment should look like the
> +following:
> +
> +.. code-block::
> +   :caption: custom-fragment.conf
> +
> +   BB_CONF_FRAGMENT_SUMMARY = "This fragment sets a limit of 4 bitbake threads and 4 parsing threads"
> +   BB_CONF_FRAGMENT_DESCRIPTION = "This fragment is useful to constrain resource consumption when the Yocto default \
> +   is causing an overload of host machine's memory and CPU resources."
> +
> +For now, our fragment does not have any additional configuration statement.
> +Let's add the following assignments to our fragment:
> +
> +.. code-block::
> +   :caption: custom-fragment.conf (continued)
> +
> +   BB_NUMBER_THREADS = "4"
> +   BB_NUMBER_PARSE_THREADS = "4"
> +
> +This means that our fragment can be enabled to set a limit on the number of
> +threads :term:`BitBake` will use with the :term:`BB_NUMBER_THREADS` and
> +:term:`BB_NUMBER_PARSE_THREADS` variables.
> +
> +For now, our fragment exists and is listed by the
> +:ref:`ref-bitbake-config-build-list-fragments` command, but is not enabled. To
> +enable this fragment, use the :ref:`ref-bitbake-config-build-enable-fragment`
> +command::
> +
> +   bitbake-config-build enable-fragment meta-custom/custom-fragment
> +
> +.. note::
> +
> +   The ``meta-custom`` prefix in the above command depends on the name of your
> +   layer. This name is defined by the :term:`BBFILE_COLLECTIONS` variable in
> +   the ``conf/layer.conf`` file of your layer.
> +
> +Standard Configuration fragments can be organized in a more complex way. For
> +example, it's possible to create sub-directories to organize your fragments::
> +
> +   meta-custom
> +   ├── conf
> +   │   ├── fragments
> +   │   │   ├── networking
> +   │   │   │   └── mirrors.conf
> +   │   │   └── resources
> +   │   │       └── numberthreads.conf
> +   │   └── layer.conf
> +   ...
> +
> +In the above example, the ``meta-custom/networking/mirrors`` and
> +``meta-custom/resources/numberthreads`` fragments will be available in your
> +build.
> +
> +Creating A Built-in Fragment
> +============================
> +
> +Within the :term:`OpenEmbedded Build System`, Built-in Fragments are defined
> +with the :term:`OE_FRAGMENTS_BUILTIN` variable, which is passed as a
> +parameter in an :ref:`addfragments <bitbake-user-manual/bitbake-user-manual-metadata:\`\`addfragments\`\`
> +directive>` directive in :oe_git:`bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`.
> +
> +Adding new :term:`Built-in Fragments <Built-in Fragment>` can be done by
> +appending the :term:`OE_FRAGMENTS_BUILTIN` variable from your :term:`layer`
> +configuration file:
> +
> +.. code-block::
> +   :caption: layer.conf
> +
> +   OE_FRAGMENTS_BUILTIN:append = " custom-builtin-fragment:CUSTOM_VARIABLE"
> +
> +.. warning::
> +
> +   Make sure to use the ``:append`` override in the above assignment, as using
> +   ``+=`` can lead to unexpected behavior.
> +
> +.. warning::
> +
> +   Due to the way :term:`BitBake` parses files, it is not possible to modify
> +   :term:`OE_FRAGMENTS_BUILTIN` from any kind of :term:`configuration file`.
> +   Setting it from the :term:`layer` configuration file (``conf/layer.conf``) is
> +   the retained solution to create new built-in fragments.
> +
> +You can then use the :ref:`ref-bitbake-config-build-enable-fragment` command to
> +set a value to the ``CUSTOM_VARIABLE`` variable::
> +
> +   bitbake-config-build enable-fragment custom-builtin-fragment/somevalue
> diff --git a/documentation/dev-manual/index.rst b/documentation/dev-manual/index.rst
> index ea528855a..7a581236a 100644
> --- a/documentation/dev-manual/index.rst
> +++ b/documentation/dev-manual/index.rst
> @@ -16,6 +16,7 @@ Yocto Project Development Tasks Manual
>     new-machine
>     upgrading-recipes
>     temporary-source-code
> +   creating-fragments
>     quilt.rst
>     development-shell
>     python-development-shell
> diff --git a/documentation/ref-manual/fragments.rst b/documentation/ref-manual/fragments.rst
> new file mode 100644
> index 000000000..c0118876c
> --- /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 53fa98cc9..aa1a63e05 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 f3d3d059d..e25c714d9 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 18ead7d04..57dc71ed8 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.
>
> @@ -6231,6 +6243,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
>
> --
> 2.51.0
>