ref-manual: Created new "Closer Look" chapter

Fixes [YOCTO #2808]

I extracted the section that takes a closer look at the YP
development process into its own chapter.  Feedback during the
review indicated that this information should not be buried as
it was in a section but rather pulled higher out for visibility.

So, The changes create a new chapter three that is dedicated to
this topic.

(From yocto-docs rev: 32c66976b6b84787d14d6174dab843862a0d184b)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 0 insertions, 1039 deletions

diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index bfab8a6c68..40733fae6a 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -153,1045 +153,6 @@
     </section>
 </section>
 
-<section id="a-closer-look-at-the-yocto-project-development-environment">
-    <title>A Closer Look at the Yocto Project Development Environment</title>
-
-    <para>
-        This section takes a more detailed look at the Yocto Project
-        development environment.
-        The following diagram represents the development environment at a
-        high level.
-        The remainder of this section expands on the fundamental input, output,
-        process, and
-        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>) blocks
-        in the Yocto Project development environment.
-    </para>
-
-    <para>
-        <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
-    </para>
-
-    <para>
-        The generalized Yocto Project Development Environment consists of
-        several functional areas:
-        <itemizedlist>
-            <listitem><para><emphasis>User Configuration:</emphasis>
-                Metadata you can use to control the build process.
-                </para></listitem>
-            <listitem><para><emphasis>Metadata Layers:</emphasis>
-                Various layers that provide software, machine, and
-                distro Metadata.</para></listitem>
-            <listitem><para><emphasis>Source Files:</emphasis>
-                Upstream releases, local projects, and SCMs.</para></listitem>
-            <listitem><para><emphasis>Build System:</emphasis>
-                Processes under the control of BitBake.
-                This block expands on how BitBake fetches source, applies
-                patches, completes compilation, analyzes output for package
-                generation, creates and tests packages, generates images, and
-                generates cross-development tools.</para></listitem>
-            <listitem><para><emphasis>Package Feeds:</emphasis>
-                Directories containing output packages (rpm, deb or ipk),
-                which are subsequently used in the construction of an image or
-                SDK, produced by the build system.
-                These feeds can also be copied and shared using a web server or
-                other means to facilitate extending or updating existing
-                images on devices at runtime if runtime package management is
-                enabled.</para></listitem>
-            <listitem><para><emphasis>Images:</emphasis>
-                Images produced by the development process.
-                Where do they go?
-                Can you mess with them (i.e. freely delete them or move them?).
-                </para></listitem>
-            <listitem><para><emphasis>Application Development SDK:</emphasis>
-                Cross-development tools that are produced along with an image
-                or separately with BitBake.</para></listitem>
-        </itemizedlist>
-    </para>
-
-    <section id="user-configuration">
-        <title>User Configuration</title>
-
-        <para>
-            User configuration helps define the build.
-            Through user configuration, you can tell BitBake the
-            target architecture for which you are building the image,
-            where to store downloaded source, and other build properties.
-            The following figure shows an expanded representation of the
-            user configuration box of the Yocto Project development
-            environment:
-        </para>
-
-        <para>
-            <imagedata fileref="figures/user-configuration.png" align="center" width="5.5in" depth="3.5in" />
-        </para>
-
-        <para>
-            BitBake needs some basic configuration files in order to complete
-            a build.
-            These files are <filename>*.conf</filename> files.
-            The minimally necessary ones reside as example files in the
-            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
-            For simplicity, this section refers to the Source Directory as
-            the "Poky Directory."
-        </para>
-
-        <para>
-            When you clone the <filename>poky</filename> Git repository or you
-            download and unpack a Yocto Project release, you can set up the
-            Source Directory to be named anything you want.
-            For this discussion, the cloned repository uses the default
-            name <filename>poky</filename>.
-            <note>
-                The Poky repository is primarily an aggregation of existing
-                repositories.
-                It is not a canonical upstream source.
-            </note>
-        </para>
-
-        <para>
-            The <filename>meta-yocto</filename> layer inside Poky contains
-            a <filename>conf</filename> directory that has example
-            configuration files.
-            These example files are used as a basis for creating actual
-            configuration files when you source the build environment
-            script <filename>oe-init-build-env</filename>.
-        </para>
-
-        <para>
-            Sourcing the build environment script creates a
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-            if one does not already exist.
-            BitBake uses the Build Directory for all its work during builds.
-            The Build Directory has a <filename>conf</filename> directory that
-            contains default versions of your <filename>local.conf</filename>
-            and <filename>bblayers.conf</filename> configuration files.
-            These default configuration files are created only if versions
-            do not already exist in the Build Directory at the time you
-            source the <filename>oe-init-build-env</filename> script.
-        </para>
-
-        <para>
-            Because the Poky repository is fundamentally an aggregation of
-            existing repositories, some users might be familiar with running
-            the <filename>oe-init-build-env</filename> script in the context of
-            separate OpenEmbedded-Core and BitBake repositories rather than a
-            single Poky repository.
-            This discussion assumes the script is executed from within a cloned
-            or unpacked version of Poky.
-        </para>
-
-        <para>
-            Depending on where the script is sourced, different sub-scripts
-            are called to set up the Build Directory (Yocto or OpenEmbedded).
-            Specifically, the script
-            <filename>scripts/oe-setup-builddir</filename> inside the
-            poky directory sets up the Build Directory and seeds the directory
-            (if necessary) with configuration files appropriate for the
-            Yocto Project development environment.
-            <note>
-                The <filename>scripts/oe-setup-builddir</filename> script
-                uses the <filename>$TEMPLATECONF</filename> variable to
-                determine which sample configuration files to locate.
-            </note>
-        </para>
-
-        <para>
-            The <filename>local.conf</filename> file provides many
-            basic variables that define a build environment.
-            Here is a list of a few.
-            To see the default configurations in a <filename>local.conf</filename>
-            file created by the build environment script, see the
-            <filename>local.conf.sample</filename> in the
-            <filename>meta-yocto</filename> layer:
-            <itemizedlist>
-                <listitem><para><emphasis>Parallelism Options:</emphasis>
-                    Controlled by the
-                    <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
-                    and
-                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
-                    variables.</para></listitem>
-                <listitem><para><emphasis>Target Machine Selection:</emphasis>
-                    Controlled by the
-                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
-                    variable.</para></listitem>
-                <listitem><para><emphasis>Download Directory:</emphasis>
-                    Controlled by the
-                    <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
-                    variable.</para></listitem>
-                <listitem><para><emphasis>Shared State Directory:</emphasis>
-                    Controlled by the
-                    <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
-                    variable.</para></listitem>
-                <listitem><para><emphasis>Build Output:</emphasis>
-                    Controlled by the
-                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
-                    variable.</para></listitem>
-            </itemizedlist>
-            <note>
-                Configurations set in the <filename>conf/local.conf</filename>
-                file can also be set in the
-                <filename>conf/site.conf</filename> and
-                <filename>conf/auto.conf</filename> configuration files.
-            </note>
-        </para>
-
-        <para>
-            The <filename>bblayers.conf</filename> file tells BitBake what
-            layers you want considered during the build.
-            By default, the layers listed in this file include layers
-            minimally needed by the build system.
-            However, you must manually add any custom layers you have created.
-            You can find more information on working with the
-            <filename>bblayers.conf</filename> file in the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
-            section in the Yocto Project Development Manual.
-        </para>
-
-        <para>
-            The files <filename>site.conf</filename> and
-            <filename>auto.conf</filename> are not created by the environment
-            initialization script.
-            If you want these configuration files, you must create them
-            yourself:
-            <itemizedlist>
-                <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
-                    You can use the <filename>conf/site.conf</filename>
-                    configuration file to configure multiple build directories.
-                    For example, suppose you had several build environments and
-                    they shared some common features.
-                    You can set these default build properties here.
-                    A good example is perhaps the level of parallelism you want
-                    to use through the
-                    <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
-                    and
-                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
-                    variables.</para>
-                    <para>One useful scenario for using the
-                    <filename>conf/site.conf</filename> file is to extend your
-                    <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
-                    variable to include the path to a
-                    <filename>conf/site.conf</filename>.
-                    Then, when BitBake looks for Metadata using
-                    <filename>BBPATH</filename>, it finds the
-                    <filename>conf/site.conf</filename> file and applies your
-                    common configurations found in the file.
-                    To override configurations in a particular build directory,
-                    alter the similar configurations within that build
-                    directory's <filename>conf/local.conf</filename> file.
-                    </para></listitem>
-                <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
-                    This file is not hand-created.
-                    Rather, the file is usually created and written to by
-                    an autobuilder.
-                    The settings put into the file are typically the same as
-                    you would find in the <filename>conf/local.conf</filename>
-                    or the <filename>conf/site.conf</filename> files.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-
-        <para>
-            You can edit all configuration files to further define
-            any particular build environment.
-            This process is represented by the "User Configuration Edits"
-            box in the figure.
-        </para>
-
-        <para>
-            When you launch your build with the
-            <filename>bitbake &lt;target&gt;</filename> command, BitBake
-            sorts out the configurations to ultimately define your build
-            environment.
-        </para>
-    </section>
-
-    <section id="metadata-machine-configuration-and-policy-configuration">
-        <title>Metadata, Machine Configuration, and Policy Configuration</title>
-
-        <para>
-            The previous section described the user configurations that
-            define the BitBake's global behavior.
-            This section takes a closer look at the layers the build system
-            uses to further control the build.
-            These layers provide Metadata for the software, machine, and
-            policy.
-        </para>
-
-        <para>
-            In general, three types of layer input exist:
-            <itemizedlist>
-                <listitem><para><emphasis>Policy Configuration:</emphasis>
-                    Distribution Layers provide top-level or general
-                    policies for the image or SDK being built.
-                    For example, this layer would dictate whether BitBake
-                    produces RPM or IPK packages.</para></listitem>
-                <listitem><para><emphasis>Machine Configuration:</emphasis>
-                    Board Support Package (BSP) layers provide machine
-                    configurations.
-                    This type of information is specific to a particular
-                    target architecture.</para></listitem>
-                <listitem><para><emphasis>Metadata:</emphasis>
-                    Software layers contain user-supplied recipe files,
-                    patches, and append files.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-
-        <para>
-            The following figure shows an expanded representation of the
-            Metadata, Machine Configuration, and Policy Configuration input
-            (layers) boxes of the Yocto Project development environment:
-        </para>
-
-        <para>
-            <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
-        </para>
-
-        <para>
-            In general, all layers have a similar structure.
-            They all contain a licensing file
-            (e.g. <filename>COPYING</filename>) if the layer is to be
-            distributed, a <filename>README</filename> file as good practice
-            and especially if the layer is to be distributed, a
-            configuration directory, and recipe directories.
-        </para>
-
-        <para>
-            The Yocto Project has many layers that can be used.
-            You can see a web-interface listing of them on the
-            <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
-            page.
-            The layers are shown at the bottom categorized under
-            "Yocto Metadata Layers."
-            These layers are fundamentally a subset of the
-            <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
-            which lists all layers provided by the OpenEmbedded community.
-            <note>
-                Layers exist in the Yocto Project Source Repositories that
-                cannot be found in the OpenEmbedded Metadata Index.
-                These layers are either deprecated or experimental in nature.
-            </note>
-        </para>
-
-        <para>
-            BitBake uses the <filename>conf/bblayers.conf</filename> file,
-            which is part of the user configuration, to find what layers it
-            should be using as part of the build.
-        </para>
-
-        <para>
-            For more 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 Manual.
-        </para>
-
-        <section id="distro-layer">
-            <title>Distro Layer</title>
-
-            <para>
-                The distribution layer provides policy configurations for your
-                distribution.
-                Best practices dictate that you isolate these types of
-                configurations into their own layer.
-                Settings you provide in
-                <filename>conf/&lt;distro&gt;.conf</filename> override similar
-                settings that BitBake finds in your
-                <filename>conf/local.conf</filename> file in the Build
-                Directory.
-            </para>
-
-            <para>
-                The following list provides some explanation and references
-                for what you typically find in the distribution layer:
-                <itemizedlist>
-                    <listitem><para><emphasis>classes:</emphasis>
-                        Class files (<filename>.bbclass</filename>) holds
-                        common functionality that can be shared among
-                        recipes in the distribution.
-                        When your recipes inherit a class, they take on the
-                        settings and functions for that class.
-                        You can read more about class files in the
-                        "<link linkend='ref-classes'>Classes</link>" section.
-                        </para></listitem>
-                    <listitem><para><emphasis>conf:</emphasis>
-                        This area holds configuration files for the
-                        layer (<filename>conf/layer.conf</filename>),
-                        the distribution
-                        (<filename>conf/distro/&lt;distro&gt;.conf</filename>),
-                        and any distribution-wide include files.
-                        </para></listitem>
-                    <listitem><para><emphasis>recipes-*:</emphasis>
-                        Recipes and append files that affect common
-                        functionality across the distribution.
-                        This area could include recipes and append files to
-                        to add distribution-specific configuration,
-                        initialization scripts, custom image recipes,
-                        and so forth.</para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
-
-        <section id="bsp-layer">
-            <title>BSP Layer</title>
-
-            <para>
-                The BSP Layer provides machine configurations.
-                Everything in this layer is specific to the machine for which
-                you are building the image or the SDK.
-                A common structure or form is defined for BSP layers.
-                You can learn more about this structure in the
-                <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
-                <note>
-                    In order for a BSP layer to be considered compliant with the
-                    Yocto Project, it must meet some structural requirements.
-                </note>
-            </para>
-
-            <para>
-                The BSP Layer's configuration directory contains
-                configuration files for the machine
-                (<filename>conf/machine/&lt;machine&gt;.conf</filename>) and,
-                of course, the layer (<filename>conf/layer.conf</filename>).
-            </para>
-
-            <para>
-                The remainder of the layer is dedicated to specific recipes
-                by function: <filename>recipes-bsp</filename>,
-                <filename>recipes-core</filename>,
-                <filename>recipes-graphics</filename>, and
-                <filename>recipes-kernel</filename>.
-                Metadata can exist for multiple formfactors, graphics
-                support systems, and so forth.
-                <note>
-                    While the figure shows several <filename>recipe-*</filename>
-                    directories, not all these directories appear in all
-                    BSP layers.
-                </note>
-            </para>
-        </section>
-
-        <section id="software-layer">
-            <title>Software Layer</title>
-
-            <para>
-                The software layer provides the Metadata for additional
-                software packages used during the build.
-                This layer does not include Metadata that is specific to the
-                distribution or the machine, which are found in their
-                respective layers.
-            </para>
-
-            <para>
-                This layer contains any new recipes that your project needs
-                in the form of recipe files.
-            </para>
-        </section>
-    </section>
-
-    <section id="sources-dev-environment">
-        <title>Sources</title>
-
-        <para>
-            In order for the OpenEmbedded build system to create an image or
-            any target, it must be able to access source files.
-            The main
-            <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment figure</link>
-            represents source files using the "Upstream Project Releases",
-            "Local Projects", and "SCMs (optional)" boxes.
-            The figure represents mirrors, which also play a role in locating
-            source files, with the "Source Mirror(s)" box.
-        </para>
-
-        <para>
-            The method by which source files are ultimately organized is
-            a function of the project.
-            For example, for released software, projects tend to use tarballs
-            or other archived files that can capture the state of a release
-            guaranteeing that it is statically represented.
-            On the other hand, for a project that is more dynamic or
-            experimental in nature, a project might keep source files in a
-            repository controlled by a Source Control Manager (SCM) such as
-            Git.
-            Pulling source from a repository allows you to control
-            the point in the repository (the revision) from which you want to
-            build software.
-            Finally, a combination of the two might exist, which would give the
-            consumer a choice when deciding where to get source files.
-        </para>
-
-        <para>
-            BitBake uses the
-            <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
-            variable to point to source files regardless of their location.
-            Each recipe must have a <filename>SRC_URI</filename> variable
-            that points to the source.
-        </para>
-
-        <para>
-            Another area that plays a significant role in where source files
-            comes from is pointed to by the
-            <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
-            variable.
-            This area is a cache that can hold previously downloaded source.
-            Judicious use of a <filename>DL_DIR</filename> directory can
-            save the build system a trip across the Internet when looking
-            for files.
-            A good method for using a download directory is to have
-            <filename>DL_DIR</filename> point to an area outside of your
-            Build Directory.
-            Doing so allows you to safely delete the Build Directory
-            if needed without fear of removing any downloaded source file.
-        </para>
-
-        <para>
-            The remainder of this section provides a deeper look into the
-            source files and the mirrors.
-            Here is a more detailed look at the source file area of the
-            base figure:
-            <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
-        </para>
-
-        <section id='upstream-project-releases'>
-            <title>Upstream Project Releases</title>
-
-            <para>
-                Upstream project releases exist anywhere in the form of an
-                archived file (e.g. tarball or zip file).
-                These files correspond to individual recipes.
-                For example, the figure uses specific releases each for
-                BusyBox, Qt, and Dbus.
-                An archive file can be for any released product that can be
-                built using a recipe.
-            </para>
-        </section>
-
-        <section id='local-projects'>
-            <title>Local Projects</title>
-
-            <para>
-                Local projects are custom bits of software the user provides.
-                These bits reside somewhere local to a project - perhaps
-                a directory into which the user checks in items (e.g.
-                a local directory containing a development source tree
-                used by the group).
-            </para>
-
-            <para>
-                The canonical method through which to include a local project
-                is to use the
-                <link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>
-                class to include local project.
-                You use either the <filename>local.conf</filename> or a
-                recipe's append file to override or set the
-                recipe to point to the local directory on your disk to pull
-                in the whole source tree.
-            </para>
-
-            <para>
-                For information on how to use the
-                <filename>externalsrc.bbclass</filename>, see the
-                "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
-                section.
-            </para>
-        </section>
-
-        <section id='scms'>
-            <title>Source Control Managers (Optional)</title>
-
-            <para>
-                Another place the build system can get source files from is
-                through an SCM such as Git or Subversion.
-                In this case, a repository is cloned or checked out.
-                The <filename>do_fetch</filename> task inside BitBake uses
-                the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
-                variable and the argument's prefix to determine the correct
-                fetcher module.
-            </para>
-
-            <para>
-                When fetching a repository, BitBake uses the
-                <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
-                variable to determine the specific revision from which to
-                build.
-            </para>
-        </section>
-
-        <section id='source-mirrors'>
-            <title>Source Mirror(s)</title>
-
-            <para>
-                Two kinds of mirrors exist: pre-mirrors and regular mirrors.
-                The <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
-                and
-                <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
-                variables point to these, respectively.
-                BitBake checks pre-mirrors before looking upstream for any
-                source files.
-                Pre-mirrors are appropriate when you have a shared directory
-                that is not a directory defined by the
-                <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
-                variable.
-                A Pre-mirror typically points to a shared directory that is
-                local to your organization.
-            </para>
-
-            <para>
-                Regular mirrors can be any site across the Internet that is
-                used as an alternative location for source code should the
-                primary site not be functioning for some reason or another.
-            </para>
-        </section>
-    </section>
-
-    <section id='bitbake-dev-environment'>
-        <title>BitBake</title>
-
-        <para>
-            The OpenEmbedded build system uses BitBake to produce images.
-            You can see from the
-            <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
-            figure, the BitBake area consists of several functional areas.
-            This section takes a closer look at each of those areas.
-        </para>
-
-        <section id='source-fetching-dev-environment'>
-            <title>Source Fetching</title>
-
-            <para>
-                The first stages of building a recipe are to fetch and unpack
-                the source code:
-                <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="4in" />
-            </para>
-
-            <para>
-                The <filename>do_fetch</filename> and
-                <filename>do_unpack</filename> tasks fetch the source files
-                and unpack them into a working directory.
-                By default, everything is accomplished in the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
-                which has a defined structure.
-                For additional general information on the Build Directory,
-                see the
-                "<link linkend='structure-core-build'><filename>build/</filename></link>"
-                section.
-            </para>
-
-            <para>
-                Unpacked source source files are pointed to by the
-                <link linkend='var-S'><filename>S</filename></link> variable.
-                Each recipe has an area in the Build Directory where the
-                unpacked source code resides.
-                The name of directory for any given recipe is defined from
-                several different variables.
-                You can see the variables that define these directories
-                by looking at the figure:
-                <itemizedlist>
-                    <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-PN'><filename>PN</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-PV'><filename>PV</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-PR'><filename>PR</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-S'><filename>S</filename></link>
-                        </para></listitem>
-                </itemizedlist>
-            </para>
-
-            <para>
-                Briefly, the <filename>S</filename> directory contains the
-                unpacked source files for a recipe.
-                The <filename>WORKDIR</filename> directory is where all the
-                building goes on for a given recipe.
-            </para>
-        </section>
-
-        <section id='patching-dev-environment'>
-            <title>Patching</title>
-
-            <para>
-                Once source code is fetched and unpacked, BitBake locates
-                patch files and applies them to the source files:
-                <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
-            </para>
-
-            <para>
-                The <filename>do_patch</filename> task processes recipes by
-                using the
-                <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
-                variable to locate applicable patch files, which by default
-                are <filename>*.patch</filename> or
-                <filename>*.diff</filename> files, or any file if
-                "apply=yes" is specified for the file in
-                <filename>SRC_URI</filename>.
-            </para>
-
-            <para>
-                BitBake finds and applies multiple patches for a single recipe
-                in the order in which it finds the patches.
-                Patches are applied to the recipe's source files located in the
-                <link linkend='var-S'><filename>S</filename></link> directory.
-            </para>
-
-            <para>
-                For more information on how the source directories are
-                created, see the
-                "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
-                section.
-            </para>
-        </section>
-
-        <section id='configuration-and-compilation-dev-environment'>
-            <title>Configuration and Compilation</title>
-
-            <para>
-                After source code is patched, BitBake executes tasks that
-                configure and compile the source code:
-                <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
-            </para>
-
-            <para>
-                This step in the build process consists of three tasks:
-                <itemizedlist>
-                    <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
-                        This task configures the source by enabling and
-                        disabling any build-time and configuration options for
-                        the software being built.
-                        Configurations can come from the recipe itself as well
-                        as from an inherited class.
-                        Additionally, the software itself might configure itself
-                        depending on the target for which it is being built.
-                        </para>
-
-                        <para>The configurations handled by the
-                        <filename>do_configure</filename> task are specific
-                        to source code configuration for the source code
-                        being built by the recipe.</para>
-
-                        <para>If you are using
-                        <link linkend='ref-classes-autotools'><filename>autotools.bbclass</filename></link>,
-                        you can add additional configuration options by using
-                        the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
-                        variable.
-                        For information on how this variable works within
-                        that class, see the
-                        <filename>meta/classes/autotools.bbclass</filename>.
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
-                        Once a configuration task has been satisfied, BitBake
-                        compiles the source using the
-                        <filename>do_compile</filename> task.
-                        Compilation occurs in the directory pointed to by the
-                        <link linkend='var-B'><filename>B</filename></link>
-                        variable.
-                        Realize that the <filename>B</filename> directory, by
-                        default, is the same as the
-                        <link linkend='var-S'><filename>S</filename></link>
-                        directory.</para></listitem>
-                    <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
-                        Once compilation is done, BitBake executes the
-                        <filename>do_install</filename> task.
-                        This task copies files from the <filename>B</filename>
-                        directory and places them in a holding area pointed to
-                        by the
-                        <link linkend='var-D'><filename>D</filename></link>
-                        variable.</para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
-
-        <section id='package-splitting-dev-environment'>
-            <title>Package Splitting</title>
-
-            <para>
-                After source code is configured and compiled, the
-                OpenEmbedded build system analyzes
-                the results and splits the output into packages:
-                <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
-            </para>
-
-            <para>
-                The <filename>do_package</filename> and
-                <filename>do_packagedata</filename> tasks combine to analyze
-                the files found in the
-                <link linkend='var-D'><filename>D</filename></link> directory
-                and split them into subsets based on available packages and
-                files.
-                The analyzing process involves the following as well as other
-                items: splitting out debugging symbols,
-                looking at shared library dependencies between packages,
-                and looking at package relationships.
-                The <filename>do_packagedata</filename> task creates package
-                metadata based on the analysis such that the
-                OpenEmbedded build system can generate the final packages.
-                Working, staged, and intermediate results of the analysis
-                and package splitting process use these areas:
-                <itemizedlist>
-                    <listitem><para><link linkend='var-PKGD'><filename>PKGD</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
-                        </para></listitem>
-                    <listitem><para><link linkend='var-PKGDEST'><filename>PKGDEST</filename></link>
-                        </para></listitem>
-                </itemizedlist>
-                The <link linkend='var-FILES'><filename>FILES</filename></link>
-                variable defines the files that go into each package in
-                <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
-                If you want details on how this is accomplished, you can
-                look at
-                <link linkend='ref-classes-package'><filename>package.bbclass</filename></link>.
-            </para>
-
-            <para>
-                Depending on the type of packages being created (RPM, DEB, or
-                IPK), the <filename>do_package_write_*</filename> task
-                creates the actual packages and places them in the
-                Package Feed area, which is
-                <filename>${TMPDIR}/deploy</filename>.
-                You can see the
-                "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
-                section for more detail on that part of the build process.
-                <note>
-                    Support for creating feeds directly from the
-                    <filename>deploy/*</filename> directories does not exist.
-                    Creating such feeds usually requires some kind of feed
-                    maintenance mechanism that would upload the new packages
-                    into an official package feed (e.g. the
-                    Ångström distribution).
-                    This functionality is highly distribution-specific
-                    and thus is not provided out of the box.
-                </note>
-            </para>
-        </section>
-    </section>
-
-    <section id="package-feeds-dev-environment">
-        <title>Package Feeds</title>
-
-        <para>
-            When the OpenEmbedded build system generates an image or an SDK,
-            it gets the packages from a package feed area located in the
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
-            The main
-            <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
-            figure shows this package feeds area in the upper-right corner.
-        </para>
-
-        <para>
-            This section looks a little closer into the package feeds area used
-            by the build system.
-            Here is a more detailed look at the area:
-            <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
-        </para>
-
-        <para>
-            Package feeds are an intermediary step in the build process.
-            BitBake generates packages whose type is defined by the
-            <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
-            variable.
-            Before placing the packages into package feeds,
-            the build process validates them with generated output quality
-            assurance checks through the
-            <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>
-            class.
-        </para>
-
-        <para>
-            The package feed area resides in
-            <filename>tmp/deploy</filename> of the Build Directory.
-            Folders are created that correspond to the package type
-            (IPK, DEB, or RPM) created.
-            Further organization is derived through the value of the
-            <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
-            variable for each package.
-            For example, packages can exist for the i586 or qemux86
-            architectures.
-            The package files themselves reside within the appropriate
-            architecture folder.
-        </para>
-
-        <para>
-            BitBake uses the <filename>do_package_write_*</filename> task to
-            place generated packages into the package holding area (e.g.
-            <filename>do_package_write_ipk</filename> for IPK packages).
-        </para>
-    </section>
-
-    <section id='images-dev-environment'>
-        <title>Images</title>
-
-        <para>
-            The images produced by the OpenEmbedded build system
-            are compressed forms of the
-            root filesystems that are ready to boot on a target device.
-            You can see from the main
-            <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
-            figure that BitBake output in part consists of images.
-            This section is going to look more closely at this output:
-            <imagedata fileref="figures/images.png" align="center" width="6in" depth="5in" />
-        </para>
-
-        <para>
-            For a list of example images that the Yocto Project provides,
-            the
-            "<link linkend='ref-images'>Images</link>" chapter.
-        </para>
-
-        <para>
-            Images are written out to the
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-            inside the <filename>deploy/images</filename> folder as shown
-            in the figure.
-            This folder contains any files expected to be loaded on the
-            target device.
-            The
-            <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
-            variable points to the <filename>deploy</filename> directory.
-            <itemizedlist>
-                <listitem><para><filename>&lt;kernel-image&gt;</filename>:
-                    A kernel binary file.
-                    The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
-                    variable setting determines the naming scheme for the
-                    kernel image file.
-                    Depending on that variable, the file could begin with
-                    a variety of naming strings.
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple image files.</para></listitem>
-                <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
-                    Root filesystems for the target device (e.g.
-                    <filename>*.ext3</filename> or <filename>*.bz2</filename>
-                    files).
-                    The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
-                    variable setting determines the root filesystem image
-                    type.
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple root filesystems.</para></listitem>
-                <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
-                    Tarballs that contain all the modules built for the kernel.
-                    Kernel module tarballs exist for legacy purposes and
-                    can be suppressed by setting the
-                    <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
-                    variable to "0".
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple kernel module tarballs.
-                    </para></listitem>
-                <listitem><para><filename>&lt;bootloaders&gt;</filename>:
-                    Bootloaders supporting the image, if applicable to the
-                    target machine.
-                    The <filename>deploy/images</filename> directory can
-                    contain multiple bootloaders.
-                    </para></listitem>
-                <listitem><para><filename>&lt;symlinks&gt;</filename>:
-                    The <filename>deploy/images</filename> folder contains
-                    a symbolic link that points to the most recently built file
-                    for each machine.
-                    These links might be useful for external scripts that
-                    need to obtain the latest version of each file.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='sdk-dev-environment'>
-        <title>Application Development SDK</title>
-
-        <para>
-            In the overview figure of the
-            <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
-            the output labeled "Application Development SDK" represents an
-            SDK.
-            This section is going to take a closer look at this output:
-            <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
-        </para>
-
-        <para>
-            The specific form of this output is a self-extracting
-            SDK installer (<filename>*.sh</filename>) that, when run,
-            installs the SDK, which consists of a cross-development
-            toolchain, a set of libraries and headers, and an SDK
-            environment setup script.
-            Running this installer essentially sets up your
-            cross-development environment.
-            You can think of the cross-toolchain as the "host"
-            part because it runs on the SDK machine.
-            You can think of the libraries and headers as the "target"
-            part because they are built for the target hardware.
-            The setup script is added so that you can initialize the
-            environment before using the tools.
-        </para>
-
-        <note>
-            <para>
-                The Yocto Project supports several methods by which you can
-                set up this cross-development environment.
-                These methods include downloading pre-built SDK installers,
-                building and installing your own SDK installer, or running
-                an Application Development Toolkit (ADT) installer to
-                install not just cross-development toolchains
-                but also additional tools to help in this type of
-                development.
-            </para>
-
-            <para>
-                For background information on cross-development toolchains
-                in the Yocto Project development environment, see the
-                "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
-                section.
-                For information on setting up a cross-development
-                environment, see the
-                "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
-                section in the Yocto Project Application Developer's Guide.
-            </para>
-        </note>
-
-        <para>
-            Once built, the SDK installers are written out to the
-            <filename>deploy/sdk</filename> folder inside the
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-            as shown in the figure at the beginning of this section.
-            Several variables exist that help configure these files:
-            <itemizedlist>
-                <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
-                    Points to the <filename>deploy</filename>
-                    directory.</para></listitem>
-                <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
-                    Specifies the architecture of the machine
-                    on which the cross-development tools are run to
-                    create packages for the target hardware.
-                    </para></listitem>
-                <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
-                    Lists the features to include in the "target" part
-                    of the SDK.
-                    </para></listitem>
-                <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
-                    Lists packages that make up the host
-                    part of the SDK (i.e. the part that runs on
-                    the <filename>SDKMACHINE</filename>).
-                    When you use
-                    <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
-                    to create the SDK, a set of default packages
-                    apply.
-                    This variable allows you to add more packages.
-                    </para></listitem>
-                <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
-                    Lists packages that make up the target part
-                    of the SDK (i.e. the part built for the
-                    target hardware).
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-</section>
-
 <section id="cross-development-toolchain-generation">
     <title>Cross-Development Toolchain Generation</title>