| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| <!--SPDX-License-Identifier: CC-BY-2.0-UK--> |
| |
| <chapter id='ref-terms'> |
| <title>Yocto Project Terms</title> |
| |
| <para> |
| 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: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Append Files:</emphasis> |
| Files that append build information to a recipe file. |
| Append files are known as BitBake append files and |
| <filename>.bbappend</filename> files. |
| The OpenEmbedded build system expects every append file to have |
| a corresponding recipe (<filename>.bb</filename>) 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. |
| <filename>formfactor_0.0.bb</filename> and |
| <filename>formfactor_0.0.bbappend</filename>).</para> |
| |
| <para>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 |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" |
| section in the Yocto Project Development Tasks Manual.</para> |
| |
| <para>When you name an append file, you can use the |
| "<filename>%</filename>" wildcard character to allow for |
| matching recipe names. |
| For example, suppose you have an append file named as follows: |
| <literallayout class='monospaced'> |
| busybox_1.21.%.bbappend |
| </literallayout> |
| That append file would match any |
| <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename> |
| version of the recipe. |
| So, the append file would match any of the following recipe names: |
| <literallayout class='monospaced'> |
| 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 |
| </literallayout> |
| <note><title>Important</title> |
| The use of the "<filename>%</filename>" character |
| is limited in that it only works directly in front of the |
| <filename>.bbappend</filename> portion of the append file's |
| name. |
| You cannot use the wildcard character in any other |
| location of the name. |
| </note> |
| </para></listitem> |
| <listitem><para id='bitbake-term'> |
| <emphasis>BitBake:</emphasis> |
| The task executor and scheduler used by the OpenEmbedded build |
| system to build images. |
| For more information on BitBake, see the |
| <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. |
| </para></listitem> |
| <listitem><para id='board-support-package-bsp-term'> |
| <emphasis>Board Support Package (BSP):</emphasis> |
| A group of drivers, definitions, and other components that |
| provide support for a specific hardware configuration. |
| For more information on BSPs, see the |
| <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. |
| </para></listitem> |
| <listitem> |
| <para id='build-directory'> |
| <emphasis>Build Directory:</emphasis> |
| This term refers to the area used by the OpenEmbedded build |
| system for builds. |
| The area is created when you <filename>source</filename> the |
| setup environment script that is found in the Source Directory |
| (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). |
| The |
| <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> |
| variable points to the Build Directory.</para> |
| |
| <para>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 |
| <link linkend='source-directory'>Source Directory</link> is |
| named <filename>poky</filename>: |
| <itemizedlist> |
| <listitem><para>Create the Build Directory inside your |
| Source Directory and let the name of the Build |
| Directory default to <filename>build</filename>: |
| <literallayout class='monospaced'> |
| $ cd $HOME/poky |
| $ source &OE_INIT_FILE; |
| </literallayout> |
| </para></listitem> |
| <listitem><para>Create the Build Directory inside your |
| home directory and specifically name it |
| <filename>test-builds</filename>: |
| <literallayout class='monospaced'> |
| $ cd $HOME |
| $ source poky/&OE_INIT_FILE; test-builds |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| 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 |
| <filename>YP-&POKYVERSION;</filename> |
| in your home directory within the existing |
| directory <filename>mybuilds</filename>: |
| <literallayout class='monospaced'> |
| $ cd $HOME |
| $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| <note> |
| By default, the Build Directory contains |
| <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, |
| which is a temporary directory the build system uses for |
| its work. |
| <filename>TMPDIR</filename> 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 <filename>TMPDIR</filename> |
| in your <filename>local.conf</filename> file |
| to use a local drive. |
| Doing so effectively separates <filename>TMPDIR</filename> |
| from <filename>TOPDIR</filename>, which is the Build |
| Directory. |
| </note> |
| </para></listitem> |
| <listitem><para id='hardware-build-system-term'> |
| <emphasis>Build Host:</emphasis> |
| The system used to build images in a Yocto Project |
| Development environment. |
| The build system is sometimes referred to as the |
| <firstterm>development host</firstterm>. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Classes:</emphasis> |
| 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 |
| "<link linkend='ref-classes'>Classes</link>" chapter. |
| Class files end with the <filename>.bbclass</filename> |
| filename extension. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Configuration File:</emphasis> |
| 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.</para> |
| |
| <para>Configuration files end with a <filename>.conf</filename> |
| filename extension. |
| The <filename>conf/local.conf</filename> configuration file in |
| the |
| <link linkend='build-directory'>Build Directory</link> |
| contains user-defined variables that affect every build. |
| The <filename>meta-poky/conf/distro/poky.conf</filename> |
| configuration file defines Yocto "distro" configuration |
| variables used only when building with this policy. |
| Machine configuration files, which |
| are located throughout the |
| <link linkend='source-directory'>Source Directory</link>, define |
| variables for specific hardware and are only used when building |
| for that target (e.g. the |
| <filename>machine/beaglebone.conf</filename> configuration |
| file defines variables for the Texas Instruments ARM Cortex-A8 |
| development board). |
| </para></listitem> |
| <listitem><para id='term-container-layer'> |
| <emphasis>Container Layer:</emphasis> |
| Layers that hold other layers. |
| An example of a container layer is OpenEmbedded's |
| <ulink url='https://github.com/openembedded/meta-openembedded'><filename>meta-openembedded</filename></ulink> |
| layer. |
| The <filename>meta-openembedded</filename> layer contains |
| many <filename>meta-*</filename> layers. |
| </para></listitem> |
| <listitem><para id='cross-development-toolchain'> |
| <emphasis>Cross-Development Toolchain:</emphasis> |
| 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.</para> |
| |
| <para>The Yocto Project supports two different cross-development |
| toolchains: |
| <itemizedlist> |
| <listitem><para> |
| A toolchain only used by and within |
| BitBake when building an image for a target |
| architecture. |
| </para></listitem> |
| <listitem><para>A relocatable toolchain used outside of |
| BitBake by developers when developing applications |
| that will run on a targeted device. |
| </para></listitem> |
| </itemizedlist></para> |
| |
| <para>Creation of these toolchains is simple and automated. |
| For information on toolchain concepts as they apply to the |
| Yocto Project, see the |
| "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" |
| section in the Yocto Project Overview and Concepts Manual. |
| You can also find more information on using the |
| relocatable toolchain in the |
| <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> |
| manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Extensible Software Development Kit (eSDK):</emphasis> |
| 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.</para> |
| |
| <para>For information on the eSDK, see the |
| <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> |
| manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Image:</emphasis> |
| 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 |
| "<link linkend='ref-images'>Images</link>" |
| chapter. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Layer:</emphasis> |
| 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.</para> |
| |
| <para>For introductory information on layers, see the |
| "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" |
| section in the Yocto Project Overview and Concepts Manual. |
| For more detailed information on layers, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| For a discussion specifically on BSP Layers, see the |
| "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" |
| section in the Yocto Project Board Support Packages (BSP) |
| Developer's Guide. |
| </para></listitem> |
| <listitem><para id='metadata'> |
| <emphasis>Metadata:</emphasis> |
| 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 |
| <link linkend='build-system-term'>OpenEmbedded build system</link> |
| 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.</para> |
| |
| <para>In the context of the kernel ("kernel Metadata"), the |
| term refers to the kernel config fragments and features |
| contained in the |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink> |
| Git repository. |
| </para></listitem> |
| <listitem><para id='oe-core'> |
| <emphasis>OpenEmbedded-Core (OE-Core):</emphasis> |
| 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.</para> |
| |
| <para>You can see the Metadata in the |
| <filename>meta</filename> directory of the Yocto Project |
| <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>. |
| </para></listitem> |
| <listitem><para id='build-system-term'> |
| <emphasis>OpenEmbedded Build System:</emphasis> |
| The build system specific to the Yocto Project. |
| The OpenEmbedded build system is based on another project known |
| as "Poky", which uses |
| <link linkend='bitbake-term'>BitBake</link> 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 |
| <link linkend='poky'>Poky</link> term. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Package:</emphasis> |
| 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.</para> |
| |
| <para>It is worth noting that the term "package" can, |
| in general, have subtle meanings. |
| For example, the packages referred to in the |
| "<link linkend='required-packages-for-the-build-host'>Required Packages for the Build Host</link>" |
| section are compiled binaries that, when installed, add |
| functionality to your Linux distribution.</para> |
| |
| <para>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. <link linkend='var-PR'><filename>PR</filename></link>, |
| <link linkend='var-PV'><filename>PV</filename></link>, and |
| <link linkend='var-PE'><filename>PE</filename></link>). |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Package Groups:</emphasis> |
| 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 |
| <filename>.bb</filename> filename extension. |
| </para></listitem> |
| <listitem><para id='poky'> |
| <emphasis>Poky:</emphasis> |
| Poky, which is pronounced <emphasis>Pock</emphasis>-ee, |
| is a reference embedded distribution and a reference |
| test configuration. |
| Poky provides the following: |
| <itemizedlist> |
| <listitem><para> |
| A base-level functional distro used to illustrate |
| how to customize a distribution. |
| </para></listitem> |
| <listitem><para> |
| A means by which to test the Yocto Project |
| components (i.e. Poky is used to validate |
| the Yocto Project). |
| </para></listitem> |
| <listitem><para> |
| A vehicle through which you can download |
| the Yocto Project. |
| </para></listitem> |
| </itemizedlist> |
| 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. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Recipe:</emphasis> |
| 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 |
| <filename>.bb</filename> file extension. |
| </para></listitem> |
| <listitem><para id='reference-kit-term'> |
| <emphasis>Reference Kit:</emphasis> |
| A working example of a system, which includes a |
| <link linkend='board-support-package-bsp-term'>BSP</link> |
| as well as a |
| <link linkend='hardware-build-system-term'>build host</link> |
| and other components, that can work on specific hardware. |
| </para></listitem> |
| <listitem> |
| <para id='source-directory'> |
| <emphasis>Source Directory:</emphasis> |
| This term refers to the directory structure created as a result |
| of creating a local copy of the <filename>poky</filename> Git |
| repository <filename>git://git.yoctoproject.org/poky</filename> |
| or expanding a released <filename>poky</filename> tarball. |
| <note> |
| Creating a local copy of the <filename>poky</filename> |
| Git repository is the recommended method for setting up |
| your Source Directory. |
| </note> |
| 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. |
| </note></para> |
| |
| <para>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.</para> |
| |
| <para>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 <filename>poky</filename> Git |
| repository results in a local Git repository whose top-level |
| folder is also named "poky".</para> |
| |
| <para>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 |
| <filename>&YOCTO_POKY_TARBALL;</filename> results in a |
| Source Directory whose root folder is named |
| <filename>&YOCTO_POKY;</filename>.</para> |
| |
| <para>It is important to understand the differences between the |
| Source Directory created by unpacking a released tarball as |
| compared to cloning |
| <filename>git://git.yoctoproject.org/poky</filename>. |
| 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 <filename>poky</filename> |
| 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 <filename>poky</filename> Git |
| repository.</para> |
| |
| <para>For more information on concepts related to Git |
| repositories, branches, and tags, see the |
| "<ulink url='&YOCTO_DOCS_OM_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>" |
| section in the Yocto Project Overview and Concepts Manual. |
| </para></listitem> |
| <listitem><para><emphasis>Task:</emphasis> |
| A unit of execution for BitBake (e.g. |
| <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, |
| <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>, |
| <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>, |
| and so forth). |
| </para></listitem> |
| <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis> |
| A web interface to the Yocto Project's |
| <link linkend='build-system-term'>OpenEmbedded Build System</link>. |
| 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 |
| <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Upstream:</emphasis> |
| 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. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |