.. SPDX-License-Identifier: CC-BY-SA-2.0-UK ***************************** Using Configuration Fragments ***************************** :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 document provides a quick reference of the :oe_git:`bitbake-config-build ` tool and lists the :term:`Configuration Fragments ` and :term:`Built-in Fragments ` 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 ` are managed with the :oe_git:`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 ` and :term:`Configuration Fragments ` 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 ... :term:`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`` :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 ` 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 .. _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 ` 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 ` 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 ` configurations for :wikipedia:`MIPS64 ` 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 ` configurations for supporting 32-bit libraries on 64-bit :wikipedia:`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 ` configurations for supporting 64-bit libraries on 32-bit :wikipedia:`X86 ` builds.