Browse Source

ref-manual: Separated terms into separate chapter

Pulling out some introductory information from the old "Introduction"
chapter of the ref-manual has isolated the system requirements and
term definitions sections.  I have decided to create a new chapter
for terms as they are a reference item.  This leaves system requirements
also alone as a new chapter.  So, I dumped the introduction.xml chapter
in favor of the two new chapters.

(From yocto-docs rev: 35c41b3008845c94e10be19b37409b0d1a469ff5)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Scott Rifenbark 7 years ago
parent
commit
60cfd0785b

+ 4 - 1
documentation/mega-manual/mega-manual.xml

@@ -231,7 +231,10 @@
     </para>
 
     <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/introduction.xml"/>
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-system-requirements.xml"/>
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-terms.xml"/>
 
     <xi:include
         xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/usingpoky.xml"/>

+ 3 - 1
documentation/ref-manual/ref-manual.xml

@@ -166,7 +166,9 @@
 
     </bookinfo>
 
-    <xi:include href="introduction.xml"/>
+    <xi:include href="ref-system-requirements.xml"/>
+
+    <xi:include href="ref-terms.xml"/>
 
     <xi:include href="usingpoky.xml"/>
 

+ 5 - 450
documentation/ref-manual/introduction.xml → documentation/ref-manual/ref-system-requirements.xml

@@ -2,21 +2,18 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
 
-<chapter id='ref-manual-intro'>
-<title>Introduction</title>
-
-<section id='ref-welcome'>
-    <title>Welcome</title>
+<chapter id='ref-manual-system-requirements'>
+<title>System Requirements</title>
 
     <para>
-        Welcome to the Yocto Project Reference Manual.
+        Welcome to the Yocto Project Reference Manual!
         This manual provides reference information for the current release
         of the Yocto Project.
-        This manual is best used after you have an understanding
+        The 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
+        Use this manual to find variable definitions, class
         descriptions, and so forth as needed during the course of using
         the Yocto Project.
     </para>
@@ -41,17 +38,6 @@
             section.
         </note>
     </para>
-</section>
-
-<section id='intro-requirements'>
-<title>System Requirements</title>
-    <para>
-        For general Yocto Project system requirements, see the
-        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section
-        in the Yocto Project Quick Start.
-        The remainder of this section provides details on system requirements
-        not covered in the Yocto Project Quick Start.
-    </para>
 
     <section id='detailed-supported-distros'>
         <title>Supported Linux Distributions</title>
@@ -500,437 +486,6 @@
             </para>
         </section>
     </section>
-</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
-                "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
-                section in the Yocto Project Overview 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;'>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>
-
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4

+ 436 - 0
documentation/ref-manual/ref-terms.xml

@@ -0,0 +1,436 @@
+<!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; ] >
+
+<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.
+                <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
+                "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
+                section in the Yocto Project Overview 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;'>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>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->