Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/overview-manual/overview-manual-yp-intro.xml b/poky/documentation/overview-manual/overview-manual-yp-intro.xml
new file mode 100644
index 0000000..a2a1f49
--- /dev/null
+++ b/poky/documentation/overview-manual/overview-manual-yp-intro.xml
@@ -0,0 +1,1333 @@
+<!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='overview-yp'>
+ <title>Introducing the Yocto Project</title>
+
+ <section id='what-is-the-yocto-project'>
+ <title>What is the Yocto Project?</title>
+
+ <para>
+ The Yocto Project is an open source collaboration project
+ that helps developers create custom Linux-based systems that are
+ designed for embedded products regardless of the product's hardware
+ architecture.
+ Yocto Project provides a flexible toolset and a development
+ environment that allows embedded device developers across the
+ world to collaborate through shared technologies, software stacks,
+ configurations, and best practices used to create these tailored
+ Linux images.
+ </para>
+
+ <para>
+ Thousands of developers worldwide have discovered that Yocto
+ Project provides advantages in both systems and applications
+ development, archival and management benefits, and customizations
+ used for speed, footprint, and memory utilization.
+ The project is a standard when it comes to delivering embedded
+ software stacks.
+ The project allows software customizations and build interchange
+ for multiple hardware platforms as well as software stacks that
+ can be maintained and scaled.
+ </para>
+
+ <para id='yp-key-dev-elements'>
+ <imagedata fileref="figures/key-dev-elements.png" format="PNG" align='center' width="8in"/>
+ </para>
+
+ <para>
+ For further introductory information on the Yocto Project, you
+ might be interested in this
+ <ulink url='https://www.embedded.com/electronics-blogs/say-what-/4458600/Why-the-Yocto-Project-for-my-IoT-Project-'>article</ulink>
+ by Drew Moseley and in this short introductory
+ <ulink url='https://www.youtube.com/watch?v=utZpKM7i5Z4'>video</ulink>.
+ </para>
+
+ <para>
+ The remainder of this section overviews advantages and challenges
+ tied to the Yocto Project.
+ </para>
+
+ <section id='gs-features'>
+ <title>Features</title>
+
+ <para>
+ The following list describes features and advantages of the
+ Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Widely Adopted Across the Industry:</emphasis>
+ Semiconductor, operating system, software, and
+ service vendors exist whose products and services
+ adopt and support the Yocto Project.
+ For a look at the Yocto Project community and
+ the companies involved with the Yocto
+ Project, see the "COMMUNITY" and "ECOSYSTEM" tabs
+ on the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
+ home page.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Architecture Agnostic:</emphasis>
+ Yocto Project supports Intel, ARM, MIPS, AMD, PPC
+ and other architectures.
+ Most ODMs, OSVs, and chip vendors create and supply
+ BSPs that support their hardware.
+ If you have custom silicon, you can create a BSP
+ that supports that architecture.</para>
+
+ <para>Aside from lots of architecture support, the
+ Yocto Project fully supports a wide range of device
+ emulation through the Quick EMUlator (QEMU).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Images and Code Transfer Easily:</emphasis>
+ Yocto Project output can easily move between
+ architectures without moving to new development
+ environments.
+ Additionally, if you have used the Yocto Project to
+ create an image or application and you find yourself
+ not able to support it, commercial Linux vendors such
+ as Wind River, Mentor Graphics, Timesys, and ENEA could
+ take it and provide ongoing support.
+ These vendors have offerings that are built using
+ the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Flexibility:</emphasis>
+ Corporations use the Yocto Project many different ways.
+ One example is to create an internal Linux distribution
+ as a code base the corporation can use across multiple
+ product groups.
+ Through customization and layering, a project group
+ can leverage the base Linux distribution to create
+ a distribution that works for their product needs.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Ideal for Constrained Embedded and IoT devices:</emphasis>
+ Unlike a full Linux distribution, you can use the
+ Yocto Project to create exactly what you need for
+ embedded devices.
+ You only add the feature support or packages that you
+ absolutely need for the device.
+ For devices that have display hardware, you can use
+ available system components such as X11, GTK+, Qt,
+ Clutter, and SDL (among others) to create a rich user
+ experience.
+ For devices that do not have a display or where you
+ want to use alternative UI frameworks, you can choose
+ to not install these components.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Comprehensive Toolchain Capabilities:</emphasis>
+ Toolchains for supported architectures satisfy most
+ use cases.
+ However, if your hardware supports features that are
+ not part of a standard toolchain, you can easily
+ customize that toolchain through specification of
+ platform-specific tuning parameters.
+ And, should you need to use a third-party toolchain,
+ mechanisms built into the Yocto Project allow for that.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Mechanism Rules Over Policy:</emphasis>
+ Focusing on mechanism rather than policy ensures that
+ you are free to set policies based on the needs of your
+ design instead of adopting decisions enforced by some
+ system software provider.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Uses a Layer Model:</emphasis>
+ The Yocto Project
+ <link linkend='the-yocto-project-layer-model'>layer infrastructure</link>
+ groups related functionality into separate bundles.
+ You can incrementally add these grouped functionalities
+ to your project as needed.
+ Using layers to isolate and group functionality
+ reduces project complexity and redundancy, allows you
+ to easily extend the system, make customizations,
+ and keep functionality organized.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Supports Partial Builds:</emphasis>
+ You can build and rebuild individual packages as
+ needed.
+ Yocto Project accomplishes this through its
+ <link linkend='shared-state-cache'>shared-state cache</link>
+ (sstate) scheme.
+ Being able to build and debug components individually
+ eases project development.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Releases According to a Strict Schedule:</emphasis>
+ Major releases occur on a
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>six-month cycle</ulink>
+ predictably in October and April.
+ The most recent two releases support point releases
+ to address common vulnerabilities and exposures.
+ This predictability is crucial for projects based on
+ the Yocto Project and allows development teams to
+ plan activities.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Rich Ecosystem of Individuals and Organizations:</emphasis>
+ For open source projects, the value of community is
+ very important.
+ Support forums, expertise, and active developers who
+ continue to push the Yocto Project forward are readily
+ available.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Binary Reproducibility:</emphasis>
+ The Yocto Project allows you to be very specific about
+ dependencies and achieves very high percentages of
+ binary reproducibility (e.g. 99.8% for
+ <filename>core-image-minimal</filename>).
+ When distributions are not specific about which
+ packages are pulled in and in what order to support
+ dependencies, other build systems can arbitrarily
+ include packages.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>License Manifest:</emphasis>
+ The Yocto Project provides a
+ <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>license manifest</ulink>
+ for review by people who need to track the use of open
+ source licenses (e.g.legal teams).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-challenges'>
+ <title>Challenges</title>
+
+ <para>
+ The following list presents challenges you might encounter
+ when developing using the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Steep Learning Curve:</emphasis>
+ The Yocto Project has a steep learning curve and has
+ many different ways to accomplish similar tasks.
+ It can be difficult to choose how to proceed when
+ varying methods exist by which to accomplish a given
+ task.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Understanding What Changes You Need to Make
+ For Your Design Requires Some Research:</emphasis>
+ Beyond the simple tutorial stage, understanding what
+ changes need to be made for your particular design
+ can require a significant amount of research and
+ investigation.
+ For information that helps you transition from
+ trying out the Yocto Project to using it for your
+ project, see the
+ "<ulink url='&YOCTO_DOCS_URL;/what-i-wish-id-known/'>What I wish I'd Known</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_URL;/transitioning-to-a-custom-environment/'>Transitioning to a Custom Environment for Systems Development</ulink>"
+ documents on the Yocto Project website.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Project Workflow Could Be Confusing:</emphasis>
+ The
+ <link linkend='overview-development-environment'>Yocto Project workflow</link>
+ could be confusing if you are used to traditional
+ desktop and server software development.
+ In a desktop development environment, mechanisms exist
+ to easily pull and install new packages, which are
+ typically pre-compiled binaries from servers accessible
+ over the Internet.
+ Using the Yocto Project, you must modify your
+ configuration and rebuild to add additional packages.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Working in a Cross-Build Environment Can
+ Feel Unfamiliar:</emphasis>
+ When developing code to run on a target, compilation,
+ execution, and testing done on the actual target
+ can be faster than running a BitBake build on a
+ development host and then deploying binaries to the
+ target for test.
+ While the Yocto Project does support development tools
+ on the target, the additional step of integrating your
+ changes back into the Yocto Project build environment
+ would be required.
+ Yocto Project supports an intermediate approach that
+ involves making changes on the development system
+ within the BitBake environment and then deploying only
+ the updated packages to the target.</para>
+
+ <para>The Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ produces packages in standard formats (i.e. RPM,
+ DEB, IPK, and TAR).
+ You can deploy these packages into the running system
+ on the target by using utilities on the target such
+ as <filename>rpm</filename> or
+ <filename>ipk</filename>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initial Build Times Can be Significant:</emphasis>
+ Long initial build times are unfortunately unavoidable
+ due to the large number of packages initially built
+ from scratch for a fully functioning Linux system.
+ Once that initial build is completed, however, the
+ shared-state (sstate) cache mechanism Yocto Project
+ uses keeps the system from rebuilding packages that
+ have not been "touched" since the last build.
+ The sstate mechanism significantly reduces times
+ for successive builds.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id='the-yocto-project-layer-model'>
+ <title>The Yocto Project Layer Model</title>
+
+ <para>
+ The Yocto Project's "Layer Model" is a development model for
+ embedded and IoT Linux creation that distinguishes the
+ Yocto Project from other simple build systems.
+ The Layer Model simultaneously supports collaboration and
+ customization.
+ Layers are repositories that contain related sets of instructions
+ that tell the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ what to do.
+ You can collaborate, share, and reuse layers.
+ </para>
+
+ <para>
+ Layers can contain changes to previous instructions or settings
+ at any time.
+ This powerful override capability is what allows you to customize
+ previously supplied collaborative or community layers to suit your
+ product requirements.
+ </para>
+
+ <para>
+ You use different layers to logically separate information in your
+ build.
+ As an example, you could have BSP, GUI, distro configuration,
+ middleware, or application layers.
+ Putting your entire build into one layer limits and complicates
+ future customization and reuse.
+ Isolating information into layers, on the other hand, helps
+ simplify future customizations and reuse.
+ You might find it tempting to keep everything in one layer when
+ working on a single project.
+ However, the more modular your Metadata, the easier
+ it is to cope with future changes.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Use Board Support Package (BSP) layers from silicon
+ vendors when possible.
+ </para></listitem>
+ <listitem><para>
+ Familiarize yourself with the
+ <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project curated layer index</ulink>
+ or the
+ <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded layer index</ulink>.
+ The latter contains more layers but they are less
+ universally validated.
+ </para></listitem>
+ <listitem><para>
+ Layers support the inclusion of technologies, hardware
+ components, and software components.
+ The
+ <ulink url='&YOCTO_DOCS_DEV_URL;#making-sure-your-layer-is-compatible-with-yocto-project'>Yocto Project Compatible</ulink>
+ designation provides a minimum level of standardization
+ that contributes to a strong ecosystem.
+ "YP Compatible" is applied to appropriate products and
+ software components such as BSPs, other OE-compatible
+ layers, and related open-source projects, allowing the
+ producer to use Yocto Project badges and branding
+ assets.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ To illustrate how layers are used to keep things modular, consider
+ machine customizations.
+ These types of customizations typically reside in a special layer,
+ rather than a general layer, called a BSP Layer.
+ Furthermore, the machine customizations should be isolated from
+ recipes and Metadata that support a new GUI environment,
+ for example.
+ This situation gives you a couple of layers: one for the machine
+ configurations, and one for the GUI environment.
+ It is important to understand, however, that the BSP layer can
+ still make machine-specific additions to recipes within the GUI
+ environment layer without polluting the GUI layer itself
+ with those machine-specific changes.
+ You can accomplish this through a recipe that is a BitBake append
+ (<filename>.bbappend</filename>) file, which is described later
+ in this section.
+ <note>
+ For general information on BSP layer structure, see the
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>.
+ </note>
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ contains both general layers and BSP layers right out of the box.
+ You can easily identify layers that ship with a Yocto Project
+ release in the Source Directory by their names.
+ Layers typically have names that begin with the string
+ <filename>meta-</filename>.
+ <note>
+ It is not a requirement that a layer name begin with the
+ prefix <filename>meta-</filename>, but it is a commonly
+ accepted standard in the Yocto Project community.
+ </note>
+ For example, if you were to examine the
+ <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/'>tree view</ulink>
+ of the <filename>poky</filename> repository, you will see several
+ layers: <filename>meta</filename>,
+ <filename>meta-skeleton</filename>,
+ <filename>meta-selftest</filename>,
+ <filename>meta-poky</filename>, and
+ <filename>meta-yocto-bsp</filename>.
+ Each of these repositories represents a distinct layer.
+ </para>
+
+ <para>
+ For procedures on how to create 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.
+ </para>
+ </section>
+
+ <section id='components-and-tools'>
+ <title>Components and Tools</title>
+
+ <para>
+ The Yocto Project employs a collection of components and
+ tools used by the project itself, by project developers,
+ and by those using the Yocto Project.
+ These components and tools are open source projects and
+ metadata that are separate from the reference distribution
+ (<ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>)
+ and the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+ Most of the components and tools are downloaded separately.
+ </para>
+
+ <para>
+ This section provides brief overviews of the components and
+ tools associated with the Yocto Project.
+ </para>
+
+ <section id='gs-development-tools'>
+ <title>Development Tools</title>
+
+ <para>
+ The following list consists of tools that help you develop
+ images and applications using the Yocto Project:
+ <itemizedlist>
+ <listitem><para id='gs-crops-overview'>
+ <emphasis>CROPS:</emphasis>
+ <ulink url='https://github.com/crops/poky-container/'>CROPS</ulink>
+ is an open source, cross-platform development framework
+ that leverages
+ <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
+ CROPS provides an easily managed, extensible environment
+ that allows you to build binaries for a variety of
+ architectures on Windows, Linux and Mac OS X hosts.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>devtool</filename>:</emphasis>
+ This command-line tool is available as part of the
+ extensible SDK (eSDK) and is its cornerstone.
+ You can use <filename>devtool</filename> to help build,
+ test, and package software within the eSDK.
+ You can use the tool to optionally integrate what you
+ build into an image built by the OpenEmbedded build
+ system.</para>
+
+ <para>The <filename>devtool</filename> command employs
+ a number of sub-commands that allow you to add, modify,
+ and upgrade recipes.
+ As with the OpenEmbedded build system, "recipes"
+ represent software packages within
+ <filename>devtool</filename>.
+ When you use <filename>devtool add</filename>, a recipe
+ is automatically created.
+ When you use <filename>devtool modify</filename>, the
+ specified existing recipe is used in order to determine
+ where to get the source code and how to patch it.
+ In both cases, an environment is set up so that when
+ you build the recipe a source tree that is under your
+ control is used in order to allow you to make changes
+ to the source as desired.
+ By default, both new recipes and the source go into
+ a "workspace" directory under the eSDK.
+ The <filename>devtool upgrade</filename> command
+ updates an existing recipe so that you can build it
+ for an updated set of source files.</para>
+
+ <para>You can read about the
+ <filename>devtool</filename> workflow in the Yocto
+ Project Application Development and Extensible
+ Software Development Kit (eSDK) Manual in the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow'</ulink>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
+ The eSDK provides a cross-development toolchain and
+ libraries tailored to the contents of a specific image.
+ The eSDK makes it easy to add new applications and
+ libraries to an image, modify the source for an
+ existing component, test changes on the target
+ hardware, and integrate into the rest of the
+ OpenEmbedded build system.
+ The eSDK gives you a toolchain experience supplemented
+ with the powerful set of <filename>devtool</filename>
+ commands tailored for the Yocto Project environment.
+ </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>Toaster:</emphasis>
+ Toaster is a web interface to the Yocto Project
+ OpenEmbedded build system.
+ Toaster allows you to configure, run, and view
+ information about builds.
+ For information on Toaster, see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-production-tools'>
+ <title>Production Tools</title>
+
+ <para>
+ The following list consists of tools that help production
+ related activities using the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Auto Upgrade Helper:</emphasis>
+ This utility when used in conjunction with the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ (BitBake and OE-Core) automatically generates upgrades
+ for recipes that are based on new versions of the
+ recipes published upstream.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Recipe Reporting System:</emphasis>
+ The Recipe Reporting System tracks recipe versions
+ available for Yocto Project.
+ The main purpose of the system is to help you
+ manage the recipes you maintain and to offer a dynamic
+ overview of the project.
+ The Recipe Reporting System is built on top of the
+ <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Layer Index</ulink>,
+ which is a website that indexes OpenEmbedded-Core
+ layers.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Patchwork:</emphasis>
+ <ulink url='http://jk.ozlabs.org/projects/patchwork/'>Patchwork</ulink>
+ is a fork of a project originally started by
+ <ulink url='http://ozlabs.org/'>OzLabs</ulink>.
+ The project is a web-based tracking system designed
+ to streamline the process of bringing contributions
+ into a project.
+ The Yocto Project uses Patchwork as an organizational
+ tool to handle patches, which number in the thousands
+ for every release.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>AutoBuilder:</emphasis>
+ AutoBuilder is a project that automates build tests
+ and quality assurance (QA).
+ By using the public AutoBuilder, anyone can determine
+ the status of the current "master" branch of Poky.
+ <note>
+ AutoBuilder is based on
+ <ulink url='https://buildbot.net/'>buildbot</ulink>.
+ </note></para>
+
+ <para>A goal of the Yocto Project is to lead the
+ open source industry with a project that automates
+ testing and QA procedures.
+ In doing so, the project encourages a development
+ community that publishes QA and test plans, publicly
+ demonstrates QA and test plans, and encourages
+ development of tools that automate and test and QA
+ procedures for the benefit of the development
+ community.</para>
+
+ <para>You can learn more about the AutoBuilder used
+ by the Yocto Project
+ <ulink url='&YOCTO_AB_URL;'>here</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Cross-Prelink:</emphasis>
+ Prelinking is the process of pre-computing the load
+ addresses and link tables generated by the dynamic
+ linker as compared to doing this at runtime.
+ Doing this ahead of time results in performance
+ improvements when the application is launched and
+ reduced memory usage for libraries shared by many
+ applications.</para>
+
+ <para>Historically, cross-prelink is a variant of
+ prelink, which was conceived by
+ <ulink url='http://people.redhat.com/jakub/prelink.pdf'>Jakub Jelínek</ulink>
+ a number of years ago.
+ Both prelink and cross-prelink are maintained in the
+ same repository albeit on separate branches.
+ By providing an emulated runtime dynamic linker
+ (i.e. <filename>glibc</filename>-derived
+ <filename>ld.so</filename> emulation), the
+ cross-prelink project extends the prelink software's
+ ability to prelink a sysroot environment.
+ Additionally, the cross-prelink software enables the
+ ability to work in sysroot style environments.</para>
+
+ <para>The dynamic linker determines standard load
+ address calculations based on a variety of factors
+ such as mapping addresses, library usage, and library
+ function conflicts.
+ The prelink tool uses this information, from the
+ dynamic linker, to determine unique load addresses
+ for executable and linkable format (ELF) binaries
+ that are shared libraries and dynamically linked.
+ The prelink tool modifies these ELF binaries with the
+ pre-computed information.
+ The result is faster loading and often lower memory
+ consumption because more of the library code can
+ be re-used from shared Copy-On-Write (COW) pages.
+ </para>
+
+ <para>The original upstream prelink project only
+ supports running prelink on the end target device
+ due to the reliance on the target device's dynamic
+ linker.
+ This restriction causes issues when developing a
+ cross-compiled system.
+ The cross-prelink adds a synthesized dynamic loader
+ that runs on the host, thus permitting cross-prelinking
+ without ever having to run on a read-write target
+ filesystem.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Pseudo:</emphasis>
+ Pseudo is the Yocto Project implementation of
+ <ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>,
+ which is used to run commands in an environment
+ that seemingly has root privileges.</para>
+
+ <para>During a build, it can be necessary to perform
+ operations that require system administrator
+ privileges.
+ For example, file ownership or permissions might need
+ definition.
+ Pseudo is a tool that you can either use directly or
+ through the environment variable
+ <filename>LD_PRELOAD</filename>.
+ Either method allows these operations to succeed as
+ if system administrator privileges exist even
+ when they do not.</para>
+
+ <para>You can read more about Pseudo in the
+ "<link linkend='fakeroot-and-pseudo'>Fakeroot and Pseudo</link>"
+ section.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-openembedded-build-system'>
+ <title>Open-Embedded Build System Components</title>
+
+ <para>
+ The following list consists of components associated with the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>BitBake:</emphasis>
+ BitBake is a core component of the Yocto Project and is
+ used by the OpenEmbedded build system to build images.
+ While BitBake is key to the build system, BitBake
+ is maintained separately from the Yocto Project.</para>
+
+ <para>BitBake is a generic task execution engine that
+ allows shell and Python tasks to be run efficiently
+ and in parallel while working within complex inter-task
+ dependency constraints.
+ In short, BitBake is a build engine that works
+ through recipes written in a specific format in order
+ to perform sets of tasks.</para>
+
+ <para>You can learn more about BitBake in the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>OpenEmbedded-Core:</emphasis>
+ OpenEmbedded-Core (OE-Core) is a common layer of
+ metadata (i.e. recipes, classes, and associated files)
+ used by OpenEmbedded-derived systems, which includes
+ the Yocto Project.
+ The Yocto Project and the OpenEmbedded Project both
+ maintain the OpenEmbedded-Core.
+ You can find the OE-Core metadata in the Yocto Project
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta'>Source Repositories</ulink>.
+ </para>
+
+ <para>Historically, the Yocto Project integrated the
+ OE-Core metadata throughout the Yocto Project
+ source repository reference system (Poky).
+ After Yocto Project Version 1.0, the Yocto Project
+ and OpenEmbedded agreed to work together and share a
+ common core set of metadata (OE-Core), which contained
+ much of the functionality previously found in Poky.
+ This collaboration achieved a long-standing
+ OpenEmbedded objective for having a more tightly
+ controlled and quality-assured core.
+ The results also fit well with the Yocto Project
+ objective of achieving a smaller number of fully
+ featured tools as compared to many different ones.
+ </para>
+
+ <para>Sharing a core set of metadata results in Poky
+ as an integration layer on top of OE-Core.
+ You can see that in this
+ <link linkend='yp-key-dev-elements'>figure</link>.
+ The Yocto Project combines various components such as
+ BitBake, OE-Core, script "glue", and documentation
+ for its build system.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-reference-distribution-poky'>
+ <title>Reference Distribution (Poky)</title>
+
+ <para>
+ Poky is the Yocto Project reference distribution.
+ It contains the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>
+ (BitBake and OE-Core) as well as a set of metadata to get you
+ started building your own distribution.
+ See the
+ <link linkend='what-is-the-yocto-project'>figure</link> in
+ "What is the Yocto Project?" section for an illustration
+ that shows Poky and its relationship with other parts of the
+ Yocto Project.</para>
+
+ <para>To use the Yocto Project tools and components, you
+ can download (<filename>clone</filename>) Poky and use it
+ to bootstrap your own distribution.
+ <note>
+ Poky does not contain binary files.
+ It is a working example of how to build your own custom
+ Linux distribution from source.
+ </note>
+ You can read more about Poky in the
+ "<link linkend='reference-embedded-distribution'>Reference Embedded Distribution (Poky)</link>"
+ section.
+ </para>
+ </section>
+
+ <section id='gs-packages-for-finished-targets'>
+ <title>Packages for Finished Targets</title>
+
+ <para>
+ The following lists components associated with packages
+ for finished targets:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Matchbox:</emphasis>
+ Matchbox is an Open Source, base environment for the
+ X Window System running on non-desktop, embedded
+ platforms such as handhelds, set-top boxes, kiosks,
+ and anything else for which screen space, input
+ mechanisms, or system resources are limited.</para>
+
+ <para>Matchbox consists of a number of interchangeable
+ and optional applications that you can tailor to a
+ specific, non-desktop platform to enhance usability
+ in constrained environments.</para>
+
+ <para>You can find the Matchbox source in the Yocto
+ Project
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Opkg</emphasis>
+ Open PacKaGe management (opkg) is a lightweight
+ package management system based on the itsy package
+ (ipkg) management system.
+ Opkg is written in C and resembles Advanced Package
+ Tool (APT) and Debian Package (dpkg) in operation.
+ </para>
+
+ <para>Opkg is intended for use on embedded Linux
+ devices and is used in this capacity in the
+ <ulink url='http://www.openembedded.org/wiki/Main_Page'>OpenEmbedded</ulink>
+ and
+ <ulink url='https://openwrt.org/'>OpenWrt</ulink>
+ projects, as well as the Yocto Project.
+ <note>
+ As best it can, opkg maintains backwards
+ compatibility with ipkg and conforms to a subset
+ of Debian's policy manual regarding control files.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-archived-components'>
+ <title>Archived Components</title>
+
+ <para>
+ The Build Appliance is a virtual machine image that enables
+ you to build and boot a custom embedded Linux image with
+ the Yocto Project using a non-Linux development system.
+ </para>
+
+ <para>
+ Historically, the Build Appliance was the second of three
+ methods by which you could use the Yocto Project on a system
+ that was not native to Linux.
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Hob:</emphasis>
+ Hob, which is now deprecated and is no longer available
+ since the 2.1 release of the Yocto Project provided
+ a rudimentary, GUI-based interface to the Yocto
+ Project.
+ Toaster has fully replaced Hob.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build Appliance:</emphasis>
+ Post Hob, the Build Appliance became available.
+ It was never recommended that you use the Build
+ Appliance as a day-to-day production development
+ environment with the Yocto Project.
+ Build Appliance was useful as a way to try out
+ development in the Yocto Project environment.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>CROPS:</emphasis>
+ The final and best solution available now for
+ developing using the Yocto Project on a system
+ not native to Linux is with
+ <link linkend='gs-crops-overview'>CROPS</link>.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id='gs-development-methods'>
+ <title>Development Methods</title>
+
+ <para>
+ The Yocto Project development environment usually involves a
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
+ and target hardware.
+ You use the Build Host to build images and develop applications,
+ while you use the target hardware to test deployed software.
+ </para>
+
+ <para>
+ This section provides an introduction to the choices or
+ development methods you have when setting up your Build Host.
+ Depending on the your particular workflow preference and the
+ type of operating system your Build Host runs, several choices
+ exist that allow you to use the Yocto Project.
+ <note>
+ For additional detail about the Yocto Project development
+ environment, see the
+ "<link linkend='overview-development-environment'>The Yocto Project Development Environment</link>"
+ chapter.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Native Linux Host:</emphasis>
+ By far the best option for a Build Host.
+ A system running Linux as its native operating system
+ allows you to develop software by directly using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ tool.
+ You can accomplish all aspects of development from a
+ familiar shell of a supported Linux distribution.</para>
+
+ <para>For information on how to set up a Build Host on
+ a system running Linux as its native operating system,
+ see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>CROss PlatformS (CROPS):</emphasis>
+ Typically, you use
+ <ulink url='https://github.com/crops/poky-container/'>CROPS</ulink>,
+ which leverages
+ <ulink url='https://www.docker.com/'>Docker Containers</ulink>,
+ to set up a Build Host that is not running Linux (e.g.
+ <trademark class='registered'>Microsoft</trademark>
+ <trademark class='trademark'>Windows</trademark>
+ or
+ <trademark class='registered'>macOS</trademark>).
+ <note>
+ You can, however, use CROPS on a Linux-based system.
+ </note>
+ CROPS is an open source, cross-platform development
+ framework that provides an easily managed, extensible
+ environment for building binaries targeted for a variety
+ of architectures on Windows, macOS, or Linux hosts.
+ Once the Build Host is set up using CROPS, you can prepare
+ a shell environment to mimic that of a shell being used
+ on a system natively running Linux.</para>
+
+ <para>For information on how to set up a Build Host with
+ CROPS, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Windows Subsystem For Linux (WSLv2):</emphasis>
+ You may use Windows Subsystem For Linux v2 to set up a build
+ host using Windows 10.
+ <note>
+ The Yocto Project is not compatible with WSLv1, it is
+ compatible but not officially supported nor validated
+ with WSLv2, if you still decide to use WSL please upgrade
+ to WSLv2.
+ </note>
+ The Windows Subsystem For Linux allows Windows 10 to run a real
+ Linux kernel inside of a lightweight utility virtual
+ machine (VM) using virtualization technology.</para>
+ <para>For information on how to set up a Build Host with
+ WSLv2, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl'>Setting Up to Use Windows Subsystem For Linux</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Toaster:</emphasis>
+ Regardless of what your Build Host is running, you can
+ use Toaster to develop software using the Yocto Project.
+ Toaster is a web interface to the Yocto Project's
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>.
+ The interface enables you to configure and run your
+ builds.
+ Information about builds is collected and stored in a
+ database.
+ You can use Toaster to configure and start builds on
+ multiple remote build servers.</para>
+
+ <para>For information about and how to use Toaster,
+ see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='reference-embedded-distribution'>
+ <title>Reference Embedded Distribution (Poky)</title>
+
+ <para>
+ "Poky", which is pronounced <emphasis>Pock</emphasis>-ee, is the
+ name of the Yocto Project's reference distribution or Reference OS
+ Kit.
+ Poky contains the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded Build System</ulink>
+ (<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> and
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>)
+ as well as a set of
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>metadata</ulink> to get
+ you started building your own distro.
+ In other words, Poky is a base specification of the functionality
+ needed for a typical embedded system as well as the components
+ from the Yocto Project that allow you to build a distribution into
+ a usable binary image.
+ </para>
+
+ <para>
+ Poky is a combined repository of BitBake, OpenEmbedded-Core
+ (which is found in <filename>meta</filename>),
+ <filename>meta-poky</filename>,
+ <filename>meta-yocto-bsp</filename>, and documentation provided
+ all together and known to work well together.
+ You can view these items that make up the Poky repository in the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/'>Source Repositories</ulink>.
+ <note>
+ If you are interested in all the contents of the
+ <filename>poky</filename> Git repository, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core'>Top-Level Core Components</ulink>"
+ section in the Yocto Project Reference Manual.
+ </note>
+ </para>
+
+ <para id='gs-poky-reference-distribution'>
+ The following figure illustrates what generally comprises Poky:
+ <imagedata fileref="figures/poky-reference-distribution.png" format="PNG" align='center' width="8in"/>
+ <itemizedlist>
+ <listitem><para>
+ BitBake is a task executor and scheduler that is the heart of
+ the OpenEmbedded build system.
+ </para></listitem>
+ <listitem><para>
+ <filename>meta-poky</filename>, which is Poky-specific
+ metadata.
+ </para></listitem>
+ <listitem><para>
+ <filename>meta-yocto-bsp</filename>, which are Yocto
+ Project-specific Board Support Packages (BSPs).
+ </para></listitem>
+ <listitem><para>
+ OpenEmbedded-Core (OE-Core) metadata, which includes
+ shared configurations, global variable definitions,
+ shared classes, packaging, and recipes.
+ Classes define the encapsulation and inheritance of build
+ logic.
+ Recipes are the logical units of software and images
+ to be built.
+ </para></listitem>
+ <listitem><para>
+ Documentation, which contains the Yocto Project source
+ files used to make the set of user manuals.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ While Poky is a "complete" distribution specification and is
+ tested and put through QA, you cannot use it as a product
+ "out of the box" in its current form.
+ </note>
+ </para>
+
+ <para>
+ To use the Yocto Project tools, you can use Git to clone (download)
+ the Poky repository then use your local copy of the reference
+ distribution to bootstrap your own distribution.
+ <note>
+ Poky does not contain binary files.
+ It is a working example of how to build your own custom Linux distribution
+ from source.
+ </note>
+ </para>
+
+ <para>
+ Poky has a regular, well established, six-month release cycle
+ under its own version.
+ Major releases occur at the same time major releases (point
+ releases) occur for the Yocto Project, which are typically in the
+ Spring and Fall.
+ For more information on the Yocto Project release schedule and
+ cadence, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>Yocto Project Releases and the Stable Release Process</ulink>"
+ chapter in the Yocto Project Reference Manual.
+ </para>
+
+ <para>
+ Much has been said about Poky being a "default configuration."
+ A default configuration provides a starting image footprint.
+ You can use Poky out of the box to create an image ranging from a
+ shell-accessible minimal image all the way up to a Linux
+ Standard Base-compliant image that uses a GNOME Mobile and
+ Embedded (GMAE) based reference user interface called Sato.
+ </para>
+
+ <para>
+ One of the most powerful properties of Poky is that every aspect
+ of a build is controlled by the metadata.
+ You can use metadata to augment these base image types by
+ adding metadata
+ <link linkend='the-yocto-project-layer-model'>layers</link>
+ that extend functionality.
+ These layers can provide, for example, an additional software
+ stack for an image type, add a board support package (BSP) for
+ additional hardware, or even create a new image type.
+ </para>
+
+ <para>
+ Metadata is loosely grouped into configuration files or package
+ recipes.
+ A recipe is a collection of non-executable metadata used by
+ BitBake to set variables or define additional build-time tasks.
+ A recipe contains fields such as the recipe description, the recipe
+ version, the license of the package and the upstream source
+ repository.
+ A recipe might also indicate that the build process uses autotools,
+ make, distutils or any other build process, in which case the basic
+ functionality can be defined by the classes it inherits from
+ the OE-Core layer's class definitions in
+ <filename>./meta/classes</filename>.
+ Within a recipe you can also define additional tasks as well as
+ task prerequisites.
+ Recipe syntax through BitBake also supports both
+ <filename>_prepend</filename> and <filename>_append</filename>
+ operators as a method of extending task functionality.
+ These operators inject code into the beginning or end of a task.
+ For information on these BitBake operators, see the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending-override-style-syntax'>Appending and Prepending (Override Style Syntax)</ulink>"
+ section in the BitBake User's Manual.
+ </para>
+ </section>
+
+ <section id='openembedded-build-system-workflow'>
+ <title>The OpenEmbedded Build System Workflow</title>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ uses a "workflow" to accomplish image and SDK generation.
+ The following figure overviews that workflow:
+ <imagedata fileref="figures/YP-flow-diagram.png"
+ format="PNG" align='center' width="8in"/>
+ Following is a brief summary of the "workflow":
+ <orderedlist>
+ <listitem><para>
+ Developers specify architecture, policies, patches and
+ configuration details.
+ </para></listitem>
+ <listitem><para>
+ The build system fetches and downloads the source code
+ from the specified location.
+ The build system supports standard methods such as tarballs
+ or source code repositories systems such as Git.
+ </para></listitem>
+ <listitem><para>
+ Once source code is downloaded, the build system extracts
+ the sources into a local work area where patches are
+ applied and common steps for configuring and compiling
+ the software are run.
+ </para></listitem>
+ <listitem><para>
+ The build system then installs the software into a
+ temporary staging area where the binary package format you
+ select (DEB, RPM, or IPK) is used to roll up the software.
+ </para></listitem>
+ <listitem><para>
+ Different QA and sanity checks run throughout entire
+ build process.
+ </para></listitem>
+ <listitem><para>
+ After the binaries are created, the build system
+ generates a binary package feed that is used to create
+ the final root file image.
+ </para></listitem>
+ <listitem><para>
+ The build system generates the file system image and a
+ customized Extensible SDK (eSDK) for application
+ development in parallel.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ For a very detailed look at this workflow, see the
+ "<link linkend='openembedded-build-system-build-concepts'>OpenEmbedded Build System Concepts</link>"
+ section.
+ </para>
+ </section>
+
+
+ <section id='some-basic-terms'>
+ <title>Some Basic Terms</title>
+
+ <para>
+ It helps to understand some basic fundamental terms when
+ learning the Yocto Project.
+ Although a list of terms exists in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-terms'>Yocto Project Terms</ulink>"
+ section of the Yocto Project Reference Manual, this section
+ provides the definitions of some terms helpful for getting started:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Configuration Files:</emphasis>
+ Files that hold global definitions of variables,
+ user-defined variables, and hardware configuration
+ information.
+ These files tell the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>
+ what to build and what to put into the image to support a
+ particular platform.
+ </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.
+ 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>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 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>
+ <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 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.
+ </para></listitem>
+ <listitem><para id='gs-term-openembedded-build-system'>
+ <emphasis>OpenEmbedded Build System:</emphasis>
+ The terms "BitBake" and "build system" are sometimes
+ used for the OpenEmbedded Build System.</para>
+
+ <para>BitBake is a task scheduler and execution engine
+ that parses instructions (i.e. recipes) and configuration
+ data.
+ After a parsing phase, BitBake creates a dependency tree
+ to order the compilation, schedules the compilation of
+ the included code, and finally executes the building
+ of the specified custom Linux image (distribution).
+ BitBake is similar to the <filename>make</filename>
+ tool.</para>
+
+ <para>During a build process, the build system tracks
+ dependencies and performs a native or cross-compilation
+ of the package.
+ As a first step in a cross-build setup, the framework
+ attempts to create a cross-compiler toolchain
+ (i.e. Extensible SDK) suited for the target platform.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>OpenEmbedded-Core (OE-Core):</emphasis>
+ OE-Core is metadata comprised of foundation 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 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>
+ <emphasis>Packages:</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_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"
+ section in the Yocto Project Reference Manual 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. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Poky:</emphasis>
+ Poky 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 is an integration layer on top of OE-Core.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Recipe:</emphasis>
+ The most common form of metadata.
+ A recipe contains a list of settings and tasks
+ (i.e. instructions) for building packages that are then
+ used to build the binary image.
+ A recipe describes where you get source code and which
+ patches to apply.
+ Recipes describe dependencies for libraries or for other
+ recipes as well as configuration and compilation options.
+ Related recipes are consolidated into a layer.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->