poky/documentation/ref-manual/terms.rst

.. SPDX-License-Identifier: CC-BY-SA-2.0-UK

*******************
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:

.. glossary::

   :term:`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    ":ref:`dev-manual/common-tasks: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:

      .. code-block:: shell

         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.

   :term:`BitBake`
      The task executor and scheduler used by the OpenEmbedded build system to
      build images. For more information on BitBake, see the :doc:`BitBake User
      Manual <bitbake:index>`.

   :term:`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 :doc:`/bsp-guide/index`.

   :term:`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. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The
      :term:`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 :term:`Source Directory` is named ``poky``:

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

            .. code-block:: shell

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

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

            .. code-block:: shell

               $ 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-&DISTRO;`` within the existing directory ``mybuilds``:

            .. code-block:: shell

               $ source poky/oe-init-build-env mybuilds/YP-&DISTRO;

      .. note::

         By default, the Build Directory contains :term:`TMPDIR`, which is a
         temporary directory the build system uses for its work. :term:`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 :term:`TMPDIR` in your ``local.conf`` file to use a local
         drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the
         Build Directory.

   :term:`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.

   :term:`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 ":ref:`ref-manual/classes:Classes`" chapter. Class files end with the
      ``.bbclass`` filename extension.

   :term:`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
      :file:`conf/local.conf` configuration file in the :term:`Build Directory`
      contains user-defined variables that affect every build. The
      :file:`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
      :term:`Source Directory`, define variables for specific hardware and are
      only used when building for that target (e.g. the
      :file:`machine/beaglebone.conf` configuration file defines variables for
      the Texas Instruments ARM Cortex-A8 development board).

   :term:`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 <https://github.com/openembedded/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 <https://github.com/openembedded/meta-openembedded/tree/master/meta-oe>`_,
      `meta-openembedded/meta-python <https://github.com/openembedded/meta-openembedded/tree/master/meta-python>`_
      and so on.

      On the other hand, some container layers (such as
      :yocto_git:`meta-security </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.

   :term:`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
      ":ref:`overview-manual/concepts: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 :doc:`/sdk-manual/index` manual.

   :term:`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 :doc:`/sdk-manual/index` manual.

   :term:`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
      ":ref:`ref-manual/images:Images`" chapter.

   :term:`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
      ":ref:`overview-manual/yp-intro:The Yocto Project Layer
      Model`" section in the Yocto Project Overview and Concepts Manual. For
      more detailed information on layers, see the
      ":ref:`dev-manual/common-tasks:Understanding and Creating
      Layers`" section in the Yocto Project Development Tasks Manual. For a
      discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
      Layers`" section in the Yocto Project Board Support Packages (BSP)
      Developer's Guide.

   :term:`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 :term:`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_git:`yocto-kernel-cache </yocto-kernel-cache>`
      Git repository.

   :term:`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 :yocto_git:`Source Repositories </poky>`.

   :term:`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 :term:`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 :term:`Poky` term.

   :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
      ":ref:`ref-manual/system-requirements: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.
      :term:`PR`, :term:`PV`, and
      :term:`PE`).

   :term:`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.

   :term:`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.

   :term:`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.

   :term:`Reference Kit`
      A working example of a system, which includes a
      :term:`BSP<Board Support Package (BSP)>` as well as a
      :term:`build host<Build Host>` and other components, that can
      work on specific hardware.

   :term:`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
     :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/`
     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
     ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
     section in the Yocto Project Overview and Concepts Manual.

   :term:`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 :term:`SYSROOT_* <SYSROOT_DESTDIR>` variables controlling
      how sysroots are created and stored.

   :term:`Task`
      A per-recipe unit of execution for BitBake (e.g.
      :ref:`ref-tasks-compile`,
      :ref:`ref-tasks-fetch`,
      :ref:`ref-tasks-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.

   :term:`Toaster`
      A web interface to the Yocto Project's :term:`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
      :doc:`/toaster-manual/index`.

   :term:`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.