8 Using Configuration Fragments
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 document provides a quick reference of the bitbake-config-build tool and lists the Configuration Fragments and Built-in Fragments available in the OpenEmbedded Build System core repositories.
Note
For details on how to define new fragments in your build, see the Creating New Configuration Fragments In Your Build section of the Yocto Project Development Tasks Manual.
8.1 bitbake-config-build Quick Reference
Configuration Fragments are managed with the bitbake-config-build command-line tool, which is available after 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.
8.1.1 bitbake-config-build list-fragments
The bitbake-config-build list-fragments command will list the Built-in Fragments and Configuration Fragments that are currently available, and will also print which fragments are enabled or disabled.
8.1.2 bitbake-config-build show-fragment
The 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
core/yocto/sstate-mirror-cdn fragment.
8.1.3 bitbake-config-build enable-fragment
The 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 BitBake and their values are available globally in your build.
From the list obtained with the 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 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> ...
Built-in fragments are enabled the same way, and
their values are defined from the command-line directly. For example, the
following command sets the qemuarm64 MACHINE through the
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 OE_FRAGMENTS, and the last value is taken into account:
OE_FRAGMENTS += " ... machine/qemuarm64 machine/qemux86-64"
In the above example, the value of MACHINE is thus equal to
qemux86-64.
When a fragment is enabled with bitbake-config-build enable-fragment, its name is automatically appended to the OE_FRAGMENTS variable in build/conf/auto.conf.
Note
It is also possible to manually remove or add fragments by modifying the OE_FRAGMENTS variable in a configuration file such as build/conf/local.conf.
8.1.4 bitbake-config-build disable-fragment
Any fragment enabled with the bitbake-config-build enable-fragment command can be disabled with the bitbake-config-build disable-fragment command. The list of enabled fragments can be obtained with bitbake-config-build list-fragments.
For example, the following command disables the core/yocto/sstate-mirror-cdn fragment:
bitbake-config-build disable-fragment core/yocto/sstate-mirror-cdn
Likewise, Built-in Fragments 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>
8.1.5 bitbake-config-build disable-all-fragments
The bitbake-config-build disable-all-fragments command disables all of the currently enabled fragments. The list of enabled fragments can be obtained with bitbake-config-build list-fragments.
This command is run without arguments:
bitbake-config-build disable-all-fragments
8.2 Core Fragments
8.2.1 Core Built-in Fragments
Built-in Fragments are used to assign a single variable globally. The OpenEmbedded Build System defines multiple built-in fragments that are detailed in this section.
8.2.1.1 machine/
The machine/ built-in fragment can be used to assign the value of
the MACHINE variable globally.
8.2.1.2 distro/
The distro/ built-in fragment can be used to assign the value of
the DISTRO variable globally.
8.2.2 Core Configuration Fragments
8.2.2.1 Yocto Project Fragments
This group defines fragments related to the Yocto Project infrastructure in general.
8.2.2.1.1 core/yocto/sstate-mirror-cdn
The core/yocto/sstate-mirror-cdn configuration fragment can be used
to set up BB_HASHSERVE_UPSTREAM and SSTATE_MIRRORS to use
pre-built 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.
8.2.2.2 Yocto Project Autobuilder Fragments
This group defines fragment used for the Yocto Project Autobuilder. For details, see the Yocto Project Autobuilder Overview section of the Yocto Project Test Environment Manual.
8.2.2.2.1 core/yocto-autobuilder/autobuilder
The core/yocto-autobuilder/autobuilder fragment defines common variables
used in builds started by the Yocto Project Autobuilder.
8.2.2.2.2 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 Limiting the Host Resources Usage
section of the Yocto Project Development Tasks Manual.
8.2.2.2.3 core/yocto-autobuilder/multilib-mips64-n32
The core/yocto-autobuilder/multilib-mips64-n32 fragment enables
tri-architecture multilib configurations for MIPS64 machines, which includes mips64-n32, mips64, and
mips32r2.
8.2.2.2.4 core/yocto-autobuilder/multilib-x86-lib32
The core/yocto-autobuilder/multilib-x86-lib32 fragment enables
multilib configurations for supporting 32-bit libraries on 64-bit
X86 builds.
8.2.2.2.5 core/yocto-autobuilder/multilib-x86-lib64
The core/yocto-autobuilder/multilib-x86-lib64 fragment enables
multilib configurations for supporting 64-bit libraries on 32-bit
X86 builds.