2 Yocto Project Terms

Following is a list of terms and definitions users new to the Yocto Project development environment might find helpful. While some of these terms are universal, the list includes them just in case:

Append Files

Files that append build information to a recipe file. Append files are known as BitBake append files and .bbappend files. The OpenEmbedded build system expects every append file to have a corresponding recipe (.bb) file. Furthermore, the append file and corresponding recipe file must use the same root filename. The filenames can differ only in the file type suffix used (e.g. formfactor_0.0.bb and formfactor_0.0.bbappend).

Information in append files extends or overrides the information in the similarly-named recipe file. For an example of an append file in use, see the “Appending Other Layers Metadata With Your Layer” section in the Yocto Project Development Tasks Manual.

When you name an append file, you can use the “%” wildcard character to allow for matching recipe names. For example, suppose you have an append file named as follows:

busybox_1.21.%.bbappend

That append file would match any busybox_1.21.x.bb version of the recipe. So, the append file would match any of the following recipe names:

busybox_1.21.1.bb
busybox_1.21.2.bb
busybox_1.21.3.bb
busybox_1.21.10.bb
busybox_1.21.25.bb

Note

The use of the “%” character is limited in that it only works directly in front of the .bbappend portion of the append file’s name. You cannot use the wildcard character in any other location of the name.

BitBake

The task executor and scheduler used by the OpenEmbedded build system to build images. For more information on BitBake, see the BitBake User Manual.

Board Support Package (BSP)

A group of drivers, definitions, and other components that provide support for a specific hardware configuration. For more information on BSPs, see the Yocto Project Board Support Package Developer’s Guide.

Build Directory

This term refers to the area used by the OpenEmbedded build system for builds. The area is created when you source the setup environment script that is found in the Source Directory (i.e. oe-init-build-env). The TOPDIR variable points to the Build Directory.

You have a lot of flexibility when creating the Build Directory. Following are some examples that show how to create the directory. The examples assume your Source Directory is named poky:

• Create the Build Directory inside your Source Directory and let the name of the Build Directory default to build:

  $ cd poky
  $ source oe-init-build-env
  

• Create the Build Directory inside your home directory and specifically name it test-builds:

  $ source poky/oe-init-build-env test-builds
  

• Provide a directory path and specifically name the Build Directory. Any intermediate folders in the pathname must exist. This next example creates a Build Directory named YP-4.1.3 within the existing directory mybuilds:

  $ source poky/oe-init-build-env mybuilds/YP-4.1.3
  

Note

By default, the Build Directory contains TMPDIR, which is a temporary directory the build system uses for its work. TMPDIR cannot be under NFS. Thus, by default, the Build Directory cannot be under NFS. However, if you need the Build Directory to be under NFS, you can set this up by setting TMPDIR in your local.conf file to use a local drive. Doing so effectively separates TMPDIR from TOPDIR, which is the Build Directory.

Build Host

The system used to build images in a Yocto Project Development environment. The build system is sometimes referred to as the development host.

Classes

Files that provide for logic encapsulation and inheritance so that commonly used patterns can be defined once and then easily used in multiple recipes. For reference information on the Yocto Project classes, see the “Classes” chapter. Class files end with the .bbclass filename extension.

Configuration File

Files that hold global definitions of variables, user-defined variables, and hardware configuration information. These files tell the OpenEmbedded build system what to build and what to put into the image to support a particular platform.

Configuration files end with a .conf filename extension. The conf/local.conf configuration file in the Build Directory contains user-defined variables that affect every build. The meta-poky/conf/distro/poky.conf configuration file defines Yocto “distro” configuration variables used only when building with this policy. Machine configuration files, which are located throughout the Source Directory, define variables for specific hardware and are only used when building for that target (e.g. the machine/beaglebone.conf configuration file defines variables for the Texas Instruments ARM Cortex-A8 development board).

Container Layer

A flexible definition that typically refers to a single Git checkout which contains multiple (and typically related) sub-layers which can be included independently in your project’s bblayers.conf file.

In some cases, such as with OpenEmbedded’s meta-openembedded layer, the top level meta-openembedded/ directory is not itself an actual layer, so you would never explicitly include it in a bblayers.conf file; rather, you would include any number of its layer subdirectories, such as meta-openembedded/meta-oe, meta-openembedded/meta-python and so on.

On the other hand, some container layers (such as meta-security) have a top-level directory that is itself an actual layer, as well as a variety of sub-layers, both of which could be included in your bblayers.conf file.

In either case, the phrase “container layer” is simply used to describe a directory structure which contains multiple valid OpenEmbedded layers.

Cross-Development Toolchain

In general, a cross-development toolchain is a collection of software development tools and utilities that run on one architecture and allow you to develop software for a different, or targeted, architecture. These toolchains contain cross-compilers, linkers, and debuggers that are specific to the target architecture.

The Yocto Project supports two different cross-development toolchains:

• A toolchain only used by and within BitBake when building an image for a target architecture.

• A relocatable toolchain used outside of BitBake by developers when developing applications that will run on a targeted device.

Creation of these toolchains is simple and automated. For information on toolchain concepts as they apply to the Yocto Project, see the “Cross-Development Toolchain Generation” section in the Yocto Project Overview and Concepts Manual. You can also find more information on using the relocatable toolchain in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual.

Extensible Software Development Kit (eSDK)

A custom SDK for application developers. This eSDK allows developers to incorporate their library and programming changes back into the image to make their code available to other application developers.

For information on the eSDK, see the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual.

Image

An image is an artifact of the BitBake build process given a collection of recipes and related Metadata. Images are the binary output that run on specific hardware or QEMU and are used for specific use-cases. For a list of the supported image types that the Yocto Project provides, see the “Images” chapter.

Layer

A collection of related recipes. Layers allow you to consolidate related metadata to customize your build. Layers also isolate information used when building for multiple architectures. Layers are hierarchical in their ability to override previous specifications. You can include any number of available layers from the Yocto Project and customize the build by adding your layers after them. You can search the Layer Index for layers used within Yocto Project.

For introductory information on layers, see the “The Yocto Project Layer Model” section in the Yocto Project Overview and Concepts Manual. For more detailed information on layers, see the “Understanding and Creating Layers” section in the Yocto Project Development Tasks Manual. For a discussion specifically on BSP Layers, see the “BSP Layers” section in the Yocto Project Board Support Packages (BSP) Developer’s Guide.

Metadata

A key element of the Yocto Project is the Metadata that is used to construct a Linux distribution and is contained in the files that the OpenEmbedded Build System parses when building an image. In general, Metadata includes recipes, configuration files, and other information that refers to the build instructions themselves, as well as the data used to control what things get built and the effects of the build. Metadata also includes commands and data used to indicate what versions of software are used, from where they are obtained, and changes or additions to the software itself (patches or auxiliary files) that are used to fix bugs or customize the software for use in a particular situation. OpenEmbedded-Core is an important set of validated metadata.

In the context of the kernel (“kernel Metadata”), the term refers to the kernel config fragments and features contained in the yocto-kernel-cache Git repository.

OpenEmbedded-Core (OE-Core)

OE-Core is metadata comprised of foundational recipes, classes, and associated files that are meant to be common among many different OpenEmbedded-derived systems, including the Yocto Project. OE-Core is a curated subset of an original repository developed by the OpenEmbedded community that has been pared down into a smaller, core set of continuously validated recipes. The result is a tightly controlled and an quality-assured core set of recipes.

You can see the Metadata in the meta directory of the Yocto Project Source Repositories.

OpenEmbedded Build System

The build system specific to the Yocto Project. The OpenEmbedded build system is based on another project known as “Poky”, which uses BitBake as the task executor. Throughout the Yocto Project documentation set, the OpenEmbedded build system is sometimes referred to simply as “the build system”. If other build systems, such as a host or target build system are referenced, the documentation clearly states the difference.

Note

For some historical information about Poky, see the Poky term.

Package

In the context of the Yocto Project, this term refers to a recipe’s packaged output produced by BitBake (i.e. a “baked recipe”). A package is generally the compiled binaries produced from the recipe’s sources. You “bake” something by running it through BitBake.

It is worth noting that the term “package” can, in general, have subtle meanings. For example, the packages referred to in the “Required Packages for the Build Host” section are compiled binaries that, when installed, add functionality to your Linux distribution.

Another point worth noting is that historically within the Yocto Project, recipes were referred to as packages — thus, the existence of several BitBake variables that are seemingly mis-named, (e.g. PR, PV, and PE).

Package Groups

Arbitrary groups of software Recipes. You use package groups to hold recipes that, when built, usually accomplish a single task. For example, a package group could contain the recipes for a company’s proprietary or value-add software. Or, the package group could contain the recipes that enable graphics. A package group is really just another recipe. Because package group files are recipes, they end with the .bb filename extension.

Poky

Poky, which is pronounced Pock-ee, is a reference embedded distribution and a reference test configuration. Poky provides the following:

• A base-level functional distro used to illustrate how to customize a distribution.

• A means by which to test the Yocto Project components (i.e. Poky is used to validate the Yocto Project).

• A vehicle through which you can download the Yocto Project.

Poky is not a product level distro. Rather, it is a good starting point for customization.

Note

Poky began as an open-source project initially developed by OpenedHand. OpenedHand developed Poky from the existing OpenEmbedded build system to create a commercially supportable build system for embedded Linux. After Intel Corporation acquired OpenedHand, the poky project became the basis for the Yocto Project’s build system.

Recipe

A set of instructions for building packages. A recipe describes where you get source code, which patches to apply, how to configure the source, how to compile it and so on. Recipes also describe dependencies for libraries or for other recipes. Recipes represent the logical unit of execution, the software to build, the images to build, and use the .bb file extension.

Reference Kit

A working example of a system, which includes a BSP as well as a build host and other components, that can work on specific hardware.

SBOM

This term means Software Bill of Materials. When you distribute software, it offers a description of all the components you used, their corresponding licenses, their dependencies, the changes that were applied and the known vulnerabilities that were fixed.

This can be used by the recipients of the software to assess their exposure to license compliance and security vulnerability issues.

See the Software Supply Chain article on Wikipedia for more details.

The OpenEmbedded Build System can generate such documentation for your project, in SPDX format, based on all the metadata it used to build the software images. See the “Creating a Software Bill of Materials” section of the Development Tasks manual.

Source Directory

This term refers to the directory structure created as a result of creating a local copy of the poky Git repository git://git.yoctoproject.org/poky or expanding a released poky tarball.

Note

Creating a local copy of the poky Git repository is the recommended method for setting up your Source Directory.

Sometimes you might hear the term “poky directory” used to refer to this directory structure.

Note

The OpenEmbedded build system does not support file or directory names that contain spaces. Be sure that the Source Directory you use does not contain these types of names.

The Source Directory contains BitBake, Documentation, Metadata and other files that all support the Yocto Project. Consequently, you must have the Source Directory in place on your development system in order to do any development using the Yocto Project.

When you create a local copy of the Git repository, you can name the repository anything you like. Throughout much of the documentation, “poky” is used as the name of the top-level folder of the local copy of the poky Git repository. So, for example, cloning the poky Git repository results in a local Git repository whose top-level folder is also named “poky”.

While it is not recommended that you use tarball extraction to set up the Source Directory, if you do, the top-level directory name of the Source Directory is derived from the Yocto Project release tarball. For example, downloading and unpacking poky tarballs from https://downloads.yoctoproject.org/releases/yocto/yocto-4.1.3/ results in a Source Directory whose root folder is named poky.

It is important to understand the differences between the Source Directory created by unpacking a released tarball as compared to cloning git://git.yoctoproject.org/poky. When you unpack a tarball, you have an exact copy of the files based on the time of release — a fixed release point. Any changes you make to your local files in the Source Directory are on top of the release and will remain local only. On the other hand, when you clone the poky Git repository, you have an active development repository with access to the upstream repository’s branches and tags. In this case, any local changes you make to the local Source Directory can be later applied to active development branches of the upstream poky Git repository.

For more information on concepts related to Git repositories, branches, and tags, see the “Repositories, Tags, and Branches” section in the Yocto Project Overview and Concepts Manual.

SPDX

This term means Software Package Data Exchange, and is used as a open standard for providing a Software Bill of Materials (SBOM). This standard is developed through a Linux Foundation project and is used by the OpenEmbedded Build System to provide an SBOM associated to each a software image.

For details, see Wikipedia’s SPDX page and the “Creating a Software Bill of Materials” section of the Development Tasks manual.

Sysroot

When cross-compiling, the target file system may be differently laid out and contain different things compared to the host system. The concept of a sysroot is directory which looks like the target filesystem and can be used to cross-compile against.

In the context of cross-compiling toolchains, a sysroot typically contains C library and kernel headers, plus the compiled binaries for the C library. A multilib toolchain can contain multiple variants of the C library binaries, each compiled for a target instruction set (such as armv5, armv7 and armv8), and possibly optimized for a specific CPU core.

In the more specific context of the OpenEmbedded build System and of the Yocto Project, each recipe has two sysroots:

• A target sysroot contains all the target libraries and headers needed to build the recipe.

• A native sysroot contains all the host files and executables needed to build the recipe.

See the SYSROOT_* variables controlling how sysroots are created and stored.

Task

A per-recipe unit of execution for BitBake (e.g. do_compile, do_fetch, do_patch, and so forth). One of the major benefits of the build system is that, since each recipe will typically spawn the execution of numerous tasks, it is entirely possible that many tasks can execute in parallel, either tasks from separate recipes or independent tasks within the same recipe, potentially up to the parallelism of your build system.

Toaster

A web interface to the Yocto Project’s OpenEmbedded Build System. The interface enables you to configure and run your builds. Information about builds is collected and stored in a database. For information on Toaster, see the Toaster User Manual.

Upstream

A reference to source code or repositories that are not local to the development system but located in a remote area that is controlled by the maintainer of the source code. For example, in order for a developer to work on a particular piece of code, they need to first get a copy of it from an “upstream” source.