From e86a3d2236d7a9fe77483f8db1f07de8be6fab6c Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Fri, 26 Sep 2025 15:06:23 +0200 Subject: 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 Signed-off-by: Richard Purdie --- documentation/dev-manual/creating-fragments.rst | 146 ++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 documentation/dev-manual/creating-fragments.rst (limited to 'documentation/dev-manual/creating-fragments.rst') diff --git a/documentation/dev-manual/creating-fragments.rst b/documentation/dev-manual/creating-fragments.rst new file mode 100644 index 0000000000..7f437d7c94 --- /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 ` 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 ` which a + stored in a file. These fragments include a summary and a description, + following by configuration statements. + +- :term:`Built-in Fragments ` 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 ` directive in :oe_git:`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 + ` directive in :oe_git:`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 ` directive in :oe_git:`bitbake.conf `. + +Adding new :term:`Built-in Fragments ` 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 -- cgit v1.2.3-54-g00ecf