9 Creating New Configuration Fragments In Your Build
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 Built-in Fragment mechanism.
This section will describe how to create new fragments for your builds.
There are two kinds of configuration fragments:
Standard Configuration Fragments which a stored in a file. These fragments include a summary and a description, following by configuration statements.
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).
9.1 Creating A Standard Configuration Fragment
By default, all configuration fragments are located within the
conf/fragments directory of a layer. This location is defined by the
OE_FRAGMENTS_PREFIX variable which, in turn, is used as a parameter in an
addfragments directive in bitbake.conf.
You can create one or more configuration fragment files in your
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 OpenEmbedded
Build System:
BB_CONF_FRAGMENT_SUMMARY: a one-line summary of this fragment.
BB_CONF_FRAGMENT_DESCRIPTION: a description of this fragment.
Note
The BB_CONF_FRAGMENT_SUMMARY and BB_CONF_FRAGMENT_DESCRIPTION variables are also passed as parameters in an addfragments directive in bitbake.conf.
After creating these variables, our custom fragment should look like the following:
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:
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 BitBake will use with the BB_NUMBER_THREADS and BB_NUMBER_PARSE_THREADS variables.
For now, our fragment exists and is listed by the bitbake-config-build list-fragments command, but is not enabled. To enable this fragment, use the 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 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.
9.2 Creating A Built-in Fragment
Within the OpenEmbedded Build System, Built-in Fragments are defined with the OE_FRAGMENTS_BUILTIN variable, which is passed as a parameter in an addfragments directive in bitbake.conf.
Adding new Built-in Fragments can be done by appending the OE_FRAGMENTS_BUILTIN variable from your layer configuration file:
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 BitBake parses files, it is not possible to modify
OE_FRAGMENTS_BUILTIN from any kind of configuration file.
Setting it from the layer configuration file (conf/layer.conf) is
the retained solution to create new built-in fragments.
You can then use the bitbake-config-build enable-fragment command to
set a value to the CUSTOM_VARIABLE variable:
bitbake-config-build enable-fragment custom-builtin-fragment/somevalue