Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko)
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml
index eec6cb3..29ef2d5 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml
@@ -5,119 +5,160 @@
<chapter id='ref-manual-intro'>
<title>Introduction</title>
-<section id='intro-welcome'>
- <title>Introduction</title>
+<section id='ref-welcome'>
+ <title>Welcome</title>
<para>
+ Welcome to the Yocto Project Reference Manual.
This manual provides reference information for the current release
of the Yocto Project.
- The Yocto Project is an open-source collaboration project focused
- on embedded Linux developers.
- Amongst other things, the Yocto Project uses the OpenEmbedded build
- system, which is based on the Poky project, to construct complete
- Linux images.
- You can find complete introductory and getting started information
- on the Yocto Project by reading the
+ This manual is best used after you have an understanding
+ of the basics of the Yocto Project.
+ The manual is neither meant to be read as a starting point to the
+ Yocto Project nor read from start to finish.
+ Use this manual to find concepts, variable definitions, class
+ descriptions, and so forth as needed during the course of using
+ the Yocto Project.
+ </para>
+
+ <para>
+ For introductory information on the Yocto Project, see the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the
+ "<link linkend='yp-intro'>Introducing the Yocto Project Development Environment</link>"
+ section.
+ </para>
+
+ <para>
+ If you want to use the Yocto Project to test run building an image
+ without having to understand concepts, work through the
<ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
- </para>
-
- <para>
- For task-based information using the Yocto Project, see the
- <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
- and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
- For Board Support Package (BSP) structure information, see the
- <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
- For information on how to use a Software Development Kit, (SDK), see the
- <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
- You can find information on tracing and profiling in the
- <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
- For information on BitBake, which is the task execution tool the
- OpenEmbedded build system is based on, see the
- <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
- Finally, you can also find lots of Yocto Project information on the
- <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
+ You can find "how-to" information in the
+ <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>.
+ <note><title>Tip</title>
+ For more information about the Yocto Project Documentation set,
+ see the
+ "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>"
+ section.
+ </note>
</para>
</section>
-<section id='intro-manualoverview'>
- <title>Documentation Overview</title>
+<section id='yp-intro'>
+ <title>Introducing the Yocto Project Development Environment</title>
+
<para>
- This reference manual consists of the following:
- <itemizedlist>
- <listitem><para><emphasis>
- <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis>
- Provides an overview of the components that make up the Yocto Project
- followed by information about debugging images created in the Yocto Project.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:</emphasis>
- Provides a more detailed look at the Yocto Project development
- environment within the context of development.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='technical-details'>Technical Details</link>:</emphasis>
- Describes fundamental Yocto Project components as well as an explanation
- behind how the Yocto Project uses shared state (sstate) cache to speed build time.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='migration'>Migrating to a Newer Yocto Project Release</link>:</emphasis>
- Describes release-specific information that helps you move from
- one Yocto Project Release to another.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
- Describes the
- <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> created
- either by unpacking a released Yocto Project tarball on your host development system,
- or by cloning the upstream
- <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-classes'>Classes</link>:</emphasis>
- Describes the classes used in the Yocto Project.</para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-tasks'>Tasks</link>:</emphasis>
- Describes the tasks defined by the OpenEmbedded build system.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:</emphasis>
- Provides a quick reference for the <filename>devtool</filename>
- command.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis>
- Lists and describes QA warning and error messages.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-images'>Images</link>:</emphasis>
- Describes the standard images that the Yocto Project supports.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-features'>Features</link>:</emphasis>
- Describes mechanisms for creating distribution, machine, and image
- features during the build process using the OpenEmbedded build system.</para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
- Presents most variables used by the OpenEmbedded build system, which
- uses BitBake.
- Entries describe the function of the variable and how to apply them.
- </para></listitem>
- <listitem><para><emphasis>
- <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
- Provides variable locality or context.</para></listitem>
- <listitem><para><emphasis>
- <link linkend='faq'>FAQ</link>:</emphasis>
- Provides answers for commonly asked questions in the Yocto Project
- development environment.</para></listitem>
- <listitem><para><emphasis>
- <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
- Provides guidance on how you can contribute back to the Yocto
- Project.</para></listitem>
- </itemizedlist>
+ The Yocto Project is an open-source collaboration project whose
+ focus is for developers of embedded Linux systems.
+ Among other things, the Yocto Project uses an
+ <link linkend='build-system-term'>OpenEmbedded build system</link>.
+ The build system, which is based on the OpenEmbedded (OE) project and
+ uses the
+ <link linkend='bitbake-term'>BitBake</link> tool, constructs complete
+ Linux images for architectures based on ARM, MIPS, PowerPC, x86 and
+ x86-64.
+ <note>
+ Historically, the OpenEmbedded build system, which is the
+ combination of BitBake and OE components, formed a reference
+ build host that was known as
+ "<link linkend='poky'>Poky</link>" (<emphasis>Pah</emphasis>-kee).
+ The term "Poky", as used throughout the Yocto Project Documentation
+ set, can have different meanings.
+ </note>
+ The Yocto Project provides various ancillary tools for the embedded
+ developer and also features the Sato reference User Interface, which
+ is optimized for stylus-driven, low-resolution screens.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/YP-flow-diagram.png"
+ format="PNG" align='center' width="8in"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ Here are some highlights for the Yocto Project:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ Provides a recent Linux kernel along with a set of system
+ commands and libraries suitable for the embedded
+ environment.
+ </para></listitem>
+ <listitem><para>
+ Makes available system components such as X11, GTK+, Qt,
+ Clutter, and SDL (among others) so you can create a rich user
+ experience on devices that have display hardware.
+ For devices that do not have a display or where you wish to
+ use alternative UI frameworks, these components need not be
+ installed.
+ </para></listitem>
+ <listitem><para>
+ Creates a focused and stable core compatible with the
+ OpenEmbedded project with which you can easily and reliably
+ build and develop.
+ </para></listitem>
+ <listitem><para>
+ Fully supports a wide range of hardware and device emulation
+ through the Quick EMUlator (QEMU).
+ </para></listitem>
+ <listitem><para>
+ Provides a layer mechanism that allows you to easily extend
+ the system, make customizations, and keep them organized.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ You can use the Yocto Project to generate images for many kinds
+ of devices.
+ As mentioned earlier, the Yocto Project supports creation of
+ reference images that you can boot within and emulate using QEMU.
+ The standard example machines target QEMU full-system
+ emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and
+ PowerPC architectures.
+ Beyond emulation, you can use the layer mechanism to extend
+ support to just about any platform that Linux can run on and that
+ a toolchain can target.
+ </para>
+
+ <para>
+ Another Yocto Project feature is the Sato reference User
+ Interface.
+ This optional UI that is based on GTK+ is intended for devices with
+ restricted screen sizes and is included as part of the
+ OpenEmbedded Core layer so that developers can test parts of the
+ software stack.
+ </para>
+
+ <para>
+ While the Yocto Project does not provide a strict testing framework,
+ it does provide or generate for you artifacts that let you perform
+ target-level and emulated testing and debugging.
+ Additionally, if you are an
+ <trademark class='trade'>Eclipse</trademark> IDE user, you can
+ install an Eclipse Yocto Plug-in to allow you to develop within that
+ familiar environment.
+ </para>
+
+ <para>
+ By default, using the Yocto Project to build an image creates a Poky
+ distribution.
+ However, you can create your own distribution by providing key
+ <link link='metadata'>Metadata</link>.
+ A good example is Angstrom, which has had a distribution
+ based on the Yocto Project since its inception.
+ Other examples include commercial distributions like
+ <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
+ <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
+ <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
+ and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
+ See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>"
+ section in the Yocto Project Development Tasks Manual for more
+ information.
</para>
</section>
-
<section id='intro-requirements'>
<title>System Requirements</title>
<para>
@@ -163,12 +204,12 @@
<listitem><para>Ubuntu 10.04</para></listitem>
<listitem><para>Ubuntu 11.10</para></listitem>
<listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
- <listitem><para>Ubuntu 13.10</para></listitem> -->
- <listitem><para>Ubuntu 14.04 (LTS)</para></listitem>
+ <listitem><para>Ubuntu 13.10</para></listitem>
+ <listitem><para>Ubuntu 14.04 (LTS)</para></listitem> -->
<listitem><para>Ubuntu 14.10</para></listitem>
<listitem><para>Ubuntu 15.04</para></listitem>
<listitem><para>Ubuntu 15.10</para></listitem>
- <listitem><para>Ubuntu 16.04</para></listitem>
+ <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
<listitem><para>Fedora 17 (Spherical)</para></listitem>
<listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
@@ -185,6 +226,7 @@
<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem>
<listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem> -->
<listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
+ <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
<!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
<listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
<listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
@@ -413,7 +455,7 @@
Python:
<itemizedlist>
<listitem><para>Git 1.8.3.1 or greater</para></listitem>
- <listitem><para>tar 1.24 or greater</para></listitem>
+ <listitem><para>tar 1.27 or greater</para></listitem>
<listitem><para>Python 3.4.0 or greater</para></listitem>
</itemizedlist>
</para>
@@ -492,9 +534,7 @@
On the machine that is able to run BitBake,
be sure you have set up your build environment with
the setup script
- (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
- or
- <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+ (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
</para></listitem>
<listitem><para>
Run the BitBake command to build the tarball:
@@ -512,7 +552,7 @@
<filename>.sh</filename> file that installs
the tools in the <filename>tmp/deploy/sdk</filename>
subdirectory of the
- <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+ <link linkend='build-directory'>Build Directory</link>.
The installer file has the string "buildtools"
in the name.
</para></listitem>
@@ -600,12 +640,441 @@
<title>Development Checkouts</title>
<para>
Development using the Yocto Project requires a local
- <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+ <link linkend='source-directory'>Source Directory</link>.
You can set up the Source Directory by cloning a copy of the upstream
- <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> Git repository.
+ <link linkend='poky'>poky</link> Git repository.
For information on how to do this, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
- section in the Yocto Project Development Manual.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='yocto-project-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.
+ <note>
+ Append files can also use wildcard patterns in their
+ version numbers so they can be applied to more than one
+ version of the underlying recipe file.
+ </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 System:</emphasis>
+ The system used to build images in a Yocto Project
+ Development environment.
+ The build system is sometimes referred to as the
+ development host.
+ </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>
+ Configuration information in various <filename>.conf</filename>
+ files provides global definitions of variables.
+ 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).
+ Configuration files end with a <filename>.conf</filename>
+ filename extension.
+ </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
+ "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+ section.
+ 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>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 recipes representing the core,
+ a BSP, or an application stack.
+ 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>
+ The files that BitBake parses when building an image.
+ In general, Metadata includes recipes, classes, and
+ configuration files.
+ 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>OE-Core:</emphasis>
+ A core set of Metadata originating with OpenEmbedded (OE)
+ that is shared between OE and the Yocto Project.
+ This Metadata is found in the <filename>meta</filename>
+ directory of the
+ <link linkend='source-directory'>Source Directory</link>.
+ </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
+ "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
+ section in the Yocto Project Quick Start 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>
+ The term "poky", which is pronounced
+ <emphasis>Pah</emphasis>-kee, can mean several things:
+ <itemizedlist>
+ <listitem><para>
+ In its most general sense, poky is an open-source
+ project that was initially developed by OpenedHand.
+ OpenedHand developed poky off of 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.
+ </para></listitem>
+ <listitem><para>
+ Within the Yocto Project
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>,
+ "poky" exists as a separate Git
+ repository from which you can clone to yield a local
+ Git repository that is a copy on your host system.
+ Thus, "poky" can refer to the upstream or
+ local copy of the files used for development within
+ the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ Finally, "poky" can refer to the default
+ <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
+ (i.e. distribution) created when you use the Yocto
+ Project in conjunction with the
+ <filename>poky</filename> repository to build an image.
+ </para></listitem>
+ </itemizedlist>
+ </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 system</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
+ "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
+ section.
+ </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;'>Yocto Project Toaster 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>
</section>