8. User Configuration¶

Figure 8.1 User Configuration with Details¶

BitBake needs some basic configuration files in order to complete a build. These files are *.conf files. The minimally necessary ones reside as example files in the build/conf directory of the Source Directory. For simplicity, this section and Figure 8.1 refers to the Source Directory as the Poky Directory.

The meta-poky layer inside Poky contains a conf directory that has example configuration files. These example files are used as a basis for creating actual configuration files when you source oe-init-build-env, which is the build environment script.

Sourcing the build environment script creates a Build Directory if one does not already exist. BitBake uses the Build Directory for all its work during builds. The Build Directory has a conf directory that contains default versions of your local.conf and bblayers.conf configuration files. These default configuration files are created only if versions do not already exist in the Build Directory at the time you source the build environment setup script.

Attention

Because the Poky repository is fundamentally an aggregation of existing repositories, some users might be familiar with running the oe-init-build-env script in the context of separate OpenEmbedded Core and BitBake repositories rather than a single Poky repository. This discussion assumes the script is executed from within a cloned or unpacked version of Poky.

The conf/local.conf file provides many basic variables that define a build environment. Here is a list of a few:

Target Machine Selection: Controlled by the MACHINE variable.
Download Directory: Controlled by the DL_DIR variable. Mostly set in conf/site.conf. → Local Storage → Source Material (mirrored)
Shared State Directory: Controlled by the SSTATE_DIR variable. Mostly set in conf/site.conf. → Shared State Cache
Build Output: Controlled by the TMPDIR variable.
Distribution Policy: Controlled by the DISTRO variable.
Packaging Format: Controlled by the PACKAGE_CLASSES variable.
SDK Target Architecture: Controlled by the SDKMACHINE variable.
Extra Image Packages: Controlled by the EXTRA_IMAGE_FEATURES variable.

Note

Configurations set in the conf/local.conf file can also be set in the conf/site.conf and conf/auto.conf configuration files. Both files are not created by the environment initialization script (oe-init-build-env). If you want the conf/site.conf file, you need to create that yourself. The conf/auto.conf file is typically created by an autobuilder running on a CI/CD environment.

The conf/bblayers.conf file tells BitBake what layers you want considered during the build. By default, the layers listed in this file include layers minimally needed by the build system. However, you must manually add any custom layers you have created. You can find more information on working with the bblayers.conf file in the Enabling Your Layer section in the Yocto Project Development Tasks Manual.

When you launch your build with the bitbake target command, BitBake sorts out the configurations to ultimately define your build environment. It is important to understand that the BitBake Tool reads the configuration files in a specific order: conf/site.conf, conf/auto.conf, and conf/local.conf. And, the build system applies the normal assignment statement rules as described in the Syntax and Operators chapter of the BitBake User Manual. Because the files are parsed in a specific order, variable assignments for the same variable could be affected. For example, if the conf/auto.conf file and the conf/local.conf set VARIABLE_1 to different values, because the build system parses conf/local.conf after conf/auto.conf, VARIABLE_1 is assigned the value from the conf/local.conf file.