mirror of
https://git.yoctoproject.org/poky
synced 2026-02-09 10:13:03 +01:00
c387f0c254
(From yocto-docs rev: 0aeb7a94abcef3cb3850c753dd0a243f381e6675) Signed-off-by: Quentin Schulz <foss@0leil.net> Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
526 lines
28 KiB
XML
526 lines
28 KiB
XML
<!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
|
|
-->
|