| .. 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:: |
| |
| 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/dev-manual-common-tasks:Using .bbappend Files in |
| 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. |
| |
| 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>`. |
| |
| 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 :ref:`bsp-guide/bsp-guide: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. :ref:`ref-manual/ref-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 $HOME/poky |
| $ source oe-init-build-env |
| |
| - Create the Build Directory inside your home directory and |
| specifically name it ``test-builds``: |
| |
| .. code-block:: shell |
| |
| $ cd $HOME |
| $ 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-POKYVERSION`` in your home directory within the existing |
| directory ``mybuilds``: |
| |
| .. code-block:: shell |
| |
| $ cd $HOME |
| $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION |
| |
| .. note:: |
| |
| By default, the Build Directory contains :term:`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 ":ref:`ref-manual/ref-classes: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 |
| :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). |
| |
| Container Layer |
| Layers that hold other layers. An example of a container layer is |
| OpenEmbedded's `meta-openembedded |
| <https://github.com/openembedded/meta-openembedded>`_ layer. The |
| ``meta-openembedded`` layer contains many ``meta-*`` 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 |
| ":ref:`overview-manual/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 :ref:`sdk-manual/sdk-manual: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 :ref:`sdk-manual/sdk-manual: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 |
| ":ref:`ref-manual/ref-images: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 |
| ":ref:`overview-manual/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/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. |
| |
| 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 </cgit/cgit.cgi/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 :yocto_git:`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 :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 |
| 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 <#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`). |
| |
| 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 |
| :term:`BSP<Board Support Package (BSP)>` as well as a |
| :term:`build host<Build Host>` and other components, that can |
| work on specific hardware. |
| |
| 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 expansion 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 |
| :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2` |
| 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/overview-manual-development-environment:repositories, tags, and branches`" |
| section in the Yocto Project Overview and Concepts Manual. |
| |
| Task |
| A unit of execution for BitBake (e.g. |
| :ref:`ref-tasks-compile`, |
| :ref:`ref-tasks-fetch`, |
| :ref:`ref-tasks-patch`, and so forth). |
| |
| 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/toaster-manual`. |
| |
| Upstream |
| A reference to source code or repositories that are not |
| local to the development system but located in a master 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. |