mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-20 09:32:13 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation on fragments

Browse Source 
- 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>
This commit is contained in:
Antonin Godard
2025-09-26 15:06:23 +02:00
committed by Richard Purdie
parent bb64a9adcf
commit e86a3d2236
6 changed files with 537 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
documentation/dev-manual/creating-fragments.rst Normal file
View File

@@ -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

1
documentation/dev-manual/index.rst
View File

@@ -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

258
documentation/ref-manual/fragments.rst Normal file
View File

@@ -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.

1
documentation/ref-manual/index.rst
View File

@@ -17,6 +17,7 @@ Yocto Project Reference Manual
structure
classes
tasks
fragments
devtool-reference
kickstart
qa-checks

92
documentation/ref-manual/terms.rst
View File

@@ -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

39
documentation/ref-manual/variables.rst
View File

@@ -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