Yocto 2.5

Move OpenBMC to Yocto 2.5(sumo)

Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Change-Id: I5c5ad6904a16e14c1c397f0baf10c9d465594a78

1 files changed, 494 insertions, 159 deletions

diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
index 195b22d0b..d8726b485 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
@@ -4,18 +4,386 @@
 
 <chapter id='dev-manual-start'>
 
-<title>Getting Started with the Yocto Project</title>
+<title>Setting Up to Use the Yocto Project</title>
 
 <para>
     This chapter provides procedures related to getting set up to use the
     Yocto Project.
-    For a more front-to-end process that takes you from minimally preparing
-    a build host through building an image, see the
-    <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+    You can learn about creating a team environment that develops using the
+    Yocto Project, how to set up a build host, how to locate Yocto Project
+    source repositories, and how to create local Git repositories.
 </para>
 
+<section id="usingpoky-changes-collaborate">
+    <title>Creating a Team Development Environment</title>
+
+    <para>
+        It might not be immediately clear how you can use the Yocto
+        Project in a team development environment, or scale it for a large
+        team of developers.
+        One of the strengths of the Yocto Project is that it is extremely
+        flexible.
+        Thus, you can adapt it to many different use cases and scenarios.
+        However, these characteristics can cause a struggle if you are trying
+        to create a working setup that scales across a large team.
+    </para>
+
+    <para>
+        To help you understand how to set up this type of environment,
+        this section presents a procedure that gives you the information
+        to learn how to get the results you want.
+        The procedure is high-level and presents some of the project's most
+        successful experiences, practices, solutions, and available
+        technologies that work well.
+        Keep in mind, the procedure here is a starting point.
+        You can build off it and customize it to fit any
+        particular working environment and set of practices.
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Determine Who is Going to be Developing:</emphasis>
+                You need to understand who is going to be doing anything
+                related to the Yocto Project and what their roles would be.
+                Making this determination is essential to completing the
+                steps two and three, which are to get your equipment together
+                and set up your development environment's hardware topology.
+                </para>
+
+                <para>The following roles exist:
+                <itemizedlist>
+                    <listitem><para>
+                        <emphasis>Application Development:</emphasis>
+                        These types of developers do application level work
+                        on top of an existing software stack.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Core System Development:</emphasis>
+                        These types of developers work on the contents of the
+                        operating system image itself.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Build Engineer:</emphasis>
+                        This type of developer manages Autobuilders and
+                        releases.
+                        Not all environments need a Build Engineer.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Test Engineer:</emphasis>
+                        This type of developer creates and manages automated
+                        tests needed to ensure all application and core
+                        system development meets desired quality standards.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Gather the Hardware:</emphasis>
+                Based on the size and make-up of the team, get the hardware
+                together.
+                Any development, build, or test engineer should be using
+                a system that is running a supported Linux distribution.
+                Systems, in general, should be high performance (e.g. dual,
+                six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
+                You can help ensure efficiency by having any machines used
+                for testing or that run Autobuilders be as high performance
+                as possible.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
+                Once you understand the hardware involved and the make-up
+                of the team, you can understand the hardware topology of the
+                development environment.
+                You can get a visual idea of the machines and their roles
+                across the development environment.
+
+<!--
+                The following figure shows a moderately sized Yocto Project
+                development environment.
+
+                <para role="writernotes">
+                Need figure.</para>
+-->
+
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
+                Keeping your
+                <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+                and any software you are developing under the
+                control of an SCM system that is compatible
+                with the OpenEmbedded build system is advisable.
+                Of the SCMs BitBake supports, the
+                Yocto Project team strongly recommends using
+                <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
+                Git is a distributed system that is easy to backup,
+                allows you to work remotely, and then connects back to the
+                infrastructure.
+                <note>
+                    For information about BitBake, see the
+                    <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+                </note></para>
+
+                <para>It is relatively easy to set up Git services and create
+                infrastructure like
+                <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
+                which is based on server software called
+                <filename>gitolite</filename> with <filename>cgit</filename>
+                being used to generate the web interface that lets you view the
+                repositories.
+                The <filename>gitolite</filename> software identifies users
+                using SSH keys and allows branch-based
+                access controls to repositories that you can control as little
+                or as much as necessary.
+
+                <note>
+                   The setup of these services is beyond the scope of this
+                   manual.
+                   However, sites such as these exist that describe how to
+                   perform setup:
+                   <itemizedlist>
+                       <listitem><para>
+                           <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
+                           Describes how to install <filename>gitolite</filename>
+                           on the server.
+                           </para></listitem>
+                       <listitem><para>
+                           <ulink url='http://gitolite.com'>Gitolite</ulink>:
+                            Information for <filename>gitolite</filename>.
+                            </para></listitem>
+                        <listitem><para>
+                            <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
+                            Documentation on how to create interfaces and frontends
+                            for Git.
+                            </para></listitem>
+                    </itemizedlist>
+                </note>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Set up the Application Development Machines:</emphasis>
+                As mentioned earlier, application developers are creating
+                applications on top of existing software stacks.
+                Following are some best practices for setting up machines
+                that do application development:
+                <itemizedlist>
+                    <listitem><para>
+                        Use a pre-built toolchain that
+                        contains the software stack itself.
+                        Then, develop the application code on top of the
+                        stack.
+                        This method works well for small numbers of relatively
+                        isolated applications.
+                        </para></listitem>
+                    <listitem><para>
+                        When possible, use the Yocto Project
+                        plug-in for the
+                        <trademark class='trade'>Eclipse</trademark> IDE
+                        and SDK development practices.
+                        For more information, see the
+                        "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
+                        manual.
+                        </para></listitem>
+                    <listitem><para>
+                        Keep your cross-development toolchains updated.
+                        You can do this through provisioning either as new
+                        toolchain downloads or as updates through a package
+                        update mechanism using <filename>opkg</filename>
+                        to provide updates to an existing toolchain.
+                        The exact mechanics of how and when to do this are a
+                        question for local policy.
+                        </para></listitem>
+                    <listitem><para>
+                        Use multiple toolchains installed locally
+                        into different locations to allow development across
+                        versions.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Set up the Core Development Machines:</emphasis>
+                As mentioned earlier, these types of developers work on the
+                contents of the operating system itself.
+                Following are some best practices for setting up machines
+                used for developing images:
+                <itemizedlist>
+                    <listitem><para>
+                        Have the Yocto Project build system itself available on
+                        the developer workstations so developers can run their own
+                        builds and directly rebuild the software stack.
+                        </para></listitem>
+                    <listitem><para>
+                        Keep the core system unchanged as much as
+                        possible and do your work in layers on top of the
+                        core system.
+                        Doing so gives you a greater level of portability when
+                        upgrading to new versions of the core system or Board
+                        Support Packages (BSPs).
+                        </para></listitem>
+                    <listitem><para>
+                        Share layers amongst the developers of a
+                        particular project and contain the policy configuration
+                        that defines the project.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Set up an Autobuilder:</emphasis>
+                Autobuilders are often the core of the development
+                environment.
+                It is here that changes from individual developers are brought
+                together and centrally tested and subsequent decisions about
+                releases can be made.
+                Autobuilders also allow for "continuous integration" style
+                testing of software components and regression identification
+                and tracking.</para>
+
+                <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
+                for more information and links to buildbot.
+                The Yocto Project team has found this implementation
+                works well in this role.
+                A public example of this is the Yocto Project
+                Autobuilders, which we use to test the overall health of the
+                project.</para>
+
+                <para>The features of this system are:
+                <itemizedlist>
+                    <listitem><para>
+                         Highlights when commits break the build.
+                         </para></listitem>
+                    <listitem><para>
+                        Populates an sstate cache from which
+                        developers can pull rather than requiring local
+                        builds.
+                        </para></listitem>
+                    <listitem><para>
+                        Allows commit hook triggers,
+                        which trigger builds when commits are made.
+                        </para></listitem>
+                    <listitem><para>
+                        Allows triggering of automated image booting
+                        and testing under the QuickEMUlator (QEMU).
+                        </para></listitem>
+                    <listitem><para>
+                        Supports incremental build testing and
+                        from-scratch builds.
+                        </para></listitem>
+                    <listitem><para>
+                        Shares output that allows developer
+                        testing and historical regression investigation.
+                        </para></listitem>
+                    <listitem><para>
+                        Creates output that can be used for releases.
+                        </para></listitem>
+                    <listitem><para>
+                        Allows scheduling of builds so that resources
+                        can be used efficiently.
+                        </para></listitem>
+               </itemizedlist>
+               </para></listitem>
+           <listitem><para>
+               <emphasis>Set up Test Machines:</emphasis>
+               Use a small number of shared, high performance systems
+               for testing purposes.
+               Developers can use these systems for wider, more
+               extensive testing while they continue to develop
+               locally using their primary development system.
+               </para></listitem>
+           <listitem><para>
+               <emphasis>Document Policies and Change Flow:</emphasis>
+               The Yocto Project itself uses a hierarchical structure and a
+                pull model.
+                Scripts exist to create and send pull requests
+                (i.e. <filename>create-pull-request</filename> and
+                <filename>send-pull-request</filename>).
+                This model is in line with other open source projects where
+                maintainers are responsible for specific areas of the project
+                and a single maintainer handles the final "top-of-tree" merges.
+                <note>
+                    You can also use a more collective push model.
+                    The <filename>gitolite</filename> software supports both the
+                    push and pull models quite easily.
+                </note></para>
+
+                <para>As with any development environment, it is important
+                to document the policy used as well as any main project
+                guidelines so they are understood by everyone.
+                It is also a good idea to have well structured
+                commit messages, which are usually a part of a project's
+                guidelines.
+                Good commit messages are essential when looking back in time and
+                trying to understand why changes were made.</para>
+
+                <para>If you discover that changes are needed to the core
+                layer of the project, it is worth sharing those with the
+                community as soon as possible.
+                Chances are if you have discovered the need for changes,
+                someone else in the community needs them also.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Development Environment Summary:</emphasis>
+                Aside from the previous steps, some best practices exist
+                within the Yocto Project development environment.
+                Consider the following:
+                <itemizedlist>
+                    <listitem><para>
+                        Use
+                        <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
+                        as the source control system.
+                        </para></listitem>
+                    <listitem><para>
+                        Maintain your Metadata in layers that make sense
+                        for your situation.
+                        See the "<link linkend='understanding-and-creating-layers'>Understanding
+                        and Creating Layers</link>" section for more information on
+                        layers.
+                        </para></listitem>
+                    <listitem><para>
+                        Separate the project's Metadata and code by using
+                        separate Git repositories.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+                        section for information on these repositories.
+                        See the
+                        "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>"
+                        section for information on how to set up local Git
+                        repositories for related upstream Yocto Project
+                        Git repositories.
+                        </para></listitem>
+                    <listitem><para>
+                        Set up the directory for the shared state cache
+                        (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
+                        where it makes sense.
+                        For example, set up the sstate cache on a system used
+                        by developers in the same organization and share the
+                        same source directories on their machines.
+                        </para></listitem>
+                    <listitem><para>
+                        Set up an Autobuilder and have it populate the
+                        sstate cache and source directories.
+                        </para></listitem>
+                    <listitem><para>
+                        The Yocto Project community encourages you
+                        to send patches to the project to fix bugs or add features.
+                        If you do submit patches, follow the project commit
+                        guidelines for writing good commit messages.
+                        See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para>
+                        Send changes to the core sooner than later
+                        as others are likely to run into the same issues.
+                        For some guidance on mailing lists to use, see the list in the
+                        "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+                        section.
+                        For a description of the available mailing lists, see the
+                        "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+                        section in the Yocto Project Reference Manual.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
 <section id='setting-up-the-development-host-to-use-the-yocto-project'>
-    <title>Setting Up the Development Host to Use the Yocto Project</title>
+    <title>Preparing the Build Host</title>
 
     <para>
         This section provides procedures to set up your development host to
@@ -177,7 +545,7 @@
                     site.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Go the Install Site for Your Platform:</emphasis>
+                    <emphasis>Go to the Install Site for Your Platform:</emphasis>
                     Click the link for the Docker edition associated with
                     your development host machine's native software.
                     For example, if your machine is running Microsoft
@@ -213,8 +581,8 @@
                     the type of the software you need to install.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Optionally Orient Yourself With Dockers:</emphasis>
-                    If you are unfamiliar with Dockers and the container
+                    <emphasis>Optionally Orient Yourself With Docker:</emphasis>
+                    If you are unfamiliar with Docker and the container
                     concept, you can learn more here -
                     <ulink url='https://docs.docker.com/get-started/'></ulink>.
                     You should be able to launch Docker or the Docker Toolbox
@@ -250,25 +618,25 @@
     </section>
 </section>
 
-<section id='working-with-yocto-project-source-files'>
-    <title>Working With Yocto Project Source Files</title>
+<section id='locating-yocto-project-source-files'>
+    <title>Locating Yocto Project Source Files</title>
 
     <para>
-        This section contains procedures related to locating and securing
-        Yocto Project files.
+        This section contains procedures related to locating Yocto Project
+        files.
         You establish and use these local files to work on projects.
         <note><title>Notes</title>
             <itemizedlist>
                 <listitem><para>
                     For concepts and introductory information about Git as it
                     is used in the Yocto Project, see the
-                    "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
-                    section in the Yocto Project Reference Manual.
+                    "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
+                    section in the Yocto Project Overview and Concepts Manual.
                     </para></listitem>
                 <listitem><para>
                     For concepts on Yocto Project source repositories, see the
-                    "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
-                    section in the Yocto Project Reference Manual."
+                    "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+                    section in the Yocto Project Overview and Concepts Manual."
                     </para></listitem>
             </itemizedlist>
         </note>
@@ -278,9 +646,20 @@
         <title>Accessing Source Repositories</title>
 
         <para>
-            Yocto Project maintains upstream Git
-            <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
-            that you can examine and access using a browser-based UI:
+            Working from a copy of the upstream Yocto Project
+            <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
+            is the preferred method for obtaining and using a Yocto Project
+            release.
+            You can view the Yocto Project Source Repositories at
+            <ulink url='&YOCTO_GIT_URL;'></ulink>.
+            In particular, you can find the
+            <filename>poky</filename> repository at
+            <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
+        </para>
+
+        <para>
+            Use the following procedure to locate the latest upstream copy of
+            the <filename>poky</filename> Git repository:
             <orderedlist>
                 <listitem><para>
                     <emphasis>Access Repositories:</emphasis>
@@ -290,24 +669,21 @@
                     repositories.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Select a Repository:</emphasis>
-                    Click on any repository in which you are interested (e.g.
+                    <emphasis>Select the Repository:</emphasis>
+                    Click on the repository in which you are interested (i.e.
                     <filename>poky</filename>).
                     </para></listitem>
                 <listitem><para>
                     <emphasis>Find the URL Used to Clone the Repository:</emphasis>
                     At the bottom of the page, note the URL used to
-                    <ulink url='&YOCTO_DOCS_REF_URL;#git-commands-clone'>clone</ulink>
+                    <ulink url='&YOCTO_DOCS_OM_URL;#git-commands-clone'>clone</ulink>
                     that repository (e.g.
                     <filename>&YOCTO_GIT_URL;/poky</filename>).
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Examine Change History of the Repository:</emphasis>
-                    At the top of the page, click on any branch in which you
-                    might be interested (e.g.
-                    <filename>&DISTRO_NAME_NO_CAP;</filename>).
-                    You can then view the commit log or tree view for that
-                    development branch.
+                    <note>
+                        For information on cloning a repository, see the
+                        "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+                        section.
+                    </note>
                     </para></listitem>
             </orderedlist>
         </para>
@@ -319,12 +695,12 @@
         <para>
             Yocto Project maintains an Index of Releases area that contains
             related files that contribute to the Yocto Project.
-            Rather than Git repositories, these files represent snapshot
-            tarballs.
+            Rather than Git repositories, these files are tarballs that
+            represent snapshots in time of a given component.
             <note><title>Tip</title>
                 The recommended method for accessing Yocto Project
-                components is to use Git to clone a repository and work from
-                within that local repository.
+                components is to use Git to clone the upstream repository and
+                work from within that locally cloned repository.
                 The procedure in this section exists should you desire a
                 tarball snapshot of any given component.
             </note>
@@ -342,8 +718,8 @@
                         full array of released Poky tarballs.
                         The <filename>poky</filename> directory in the
                         Index of Releases was historically used for very
-                        early releases and exists for retroactive
-                        completeness only.
+                        early releases and exists now only for retroactive
+                        completeness.
                     </note>
                     </para></listitem>
                 <listitem><para>
@@ -361,7 +737,7 @@
                     </para></listitem>
                 <listitem><para>
                     <emphasis>Download the Tarball:</emphasis>
-                    Click a tarball to download and save a snapshot of a
+                    Click the tarball to download and save a snapshot of the
                     given component.
                     </para></listitem>
             </orderedlist>
@@ -374,7 +750,7 @@
         <para>
             The
             <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
-            uses a "Downloads" area from which you can locate and download
+            uses a "DOWNLOADS" page from which you can locate and download
             tarballs of any Yocto Project release.
             Rather than Git repositories, these files represent snapshot
             tarballs.
@@ -394,50 +770,98 @@
                     </para></listitem>
                 <listitem><para>
                     <emphasis>Get to the Downloads Area:</emphasis>
-                    Click the "Downloads" tab.
+                    Select the "DOWNLOADS" item from the pull-down
+                    "SOFTWARE" tab menu.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Select the Type of Files:</emphasis>
-                    Click the type of files you want (i.e "Build System",
-                    "Tools", or "Board Support Packages (BSPs)".
+                    <emphasis>Select a Yocto Project Release:</emphasis>
+                    Use the menu next to "RELEASE" to display and choose
+                    a Yocto Project release (e.g. sumo, rocko, pyro, and
+                    so forth.
+                    For a "map" of Yocto Project releases to version numbers,
+                    see the
+                    <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink>
+                    wiki page.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Locate and Download the Tarball:</emphasis>
-                    From the list of releases, locate the appropriate
-                    download link and download the files.
+                    <emphasis>Download Tools or Board Support Packages (BSPs):</emphasis>
+                    From the "DOWNLOADS" page, you can download tools or
+                    BSPs as well.
+                    Just scroll down the page and look for what you need.
                     </para></listitem>
             </orderedlist>
         </para>
     </section>
 
-    <section id='cloning-the-poky-repository'>
-        <title>Cloning the <filename>poky</filename> Repository</title>
+    <section id='accessing-nightly-builds'>
+        <title>Accessing Nightly Builds</title>
 
         <para>
-            To use the Yocto Project, you need a release of the Yocto Project
-            locally installed on your development system.
-            The locally installed set of files is referred to as the
-            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-            in the Yocto Project documentation.
+            Yocto Project maintains an area for nightly builds that contains
+            tarball releases at <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>.
+            These builds include Yocto Project releases, SDK installation
+            scripts, and experimental builds.
         </para>
 
         <para>
-            You create your Source Directory by using
-            <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to clone a local
-            copy of the upstream <filename>poky</filename> repository.
-            <note><title>Tip</title>
-                The preferred method of getting the Yocto Project Source
-                Directory set up is to clone the repository.
-            </note>
-            Working from a copy of the upstream repository allows you
-            to contribute back into the Yocto Project or simply work with
-            the latest software on a development branch.
-            Because Git maintains and creates an upstream repository with
-            a complete history of changes and you are working with a local
-            clone of that repository, you have access to all the Yocto
-            Project development branches and tag names used in the upstream
-            repository.
+            Should you ever want to access a nightly build of a particular
+            Yocto Project component, use the following procedure:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Access the Nightly Builds:</emphasis>
+                    Open a browser and go to
+                    <ulink url='&YOCTO_AB_NIGHTLY_URL;'/> to access the
+                    Nightly Builds.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Select a Build:</emphasis>
+                    Click on any build by date in which you are interested.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Find the Tarball:</emphasis>
+                    Drill down to find the associated tarball.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Download the Tarball:</emphasis>
+                    Click the tarball to download and save a snapshot of the
+                    given component.
+                    </para></listitem>
+            </orderedlist>
         </para>
+    </section>
+</section>
+
+<section id='cloning-and-checking-out-branchs'>
+    <title>Cloning and Checking Out Branches</title>
+
+    <para>
+        To use the Yocto Project, you need a release of the Yocto Project
+        locally installed on your development system.
+        The locally installed set of files is referred to as the
+        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+        in the Yocto Project documentation.
+    </para>
+
+    <para>
+        You create your Source Directory by using
+        <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local
+        copy of the upstream <filename>poky</filename> repository.
+        <note><title>Tip</title>
+            The preferred method of getting the Yocto Project Source
+            Directory set up is to clone the repository.
+        </note>
+        Working from a copy of the upstream repository allows you
+        to contribute back into the Yocto Project or simply work with
+        the latest software on a development branch.
+        Because Git maintains and creates an upstream repository with
+        a complete history of changes and you are working with a local
+        clone of that repository, you have access to all the Yocto
+        Project development branches and tag names used in the upstream
+        repository.
+    </para>
+
+    <section id='cloning-the-poky-repository'>
+        <title>Cloning the <filename>poky</filename> Repository</title>
 
         <para>
             Follow these steps to create a local version of the
@@ -473,8 +897,8 @@
                     branch based on a tag name, see the
                     "<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>"
                     and
-                    <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>",
-                    respectively.</para>
+                    <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>"
+                    sections, respectively.</para>
 
                     <para>Once the repository is created, you can change to
                     that directory and check its status.
@@ -635,7 +1059,7 @@
                 <listitem><para>
                     <emphasis>Checkout the Branch:</emphasis>
                     <literallayout class='monospaced'>
-     $ git checkout tags/&DISTRO; -b my_yocto_&DISTRO;
+     $ git checkout tags/&DISTRO_REL_TAG; -b my_yocto_&DISTRO;
      Switched to a new branch 'my_yocto_&DISTRO;'
      $ git branch
        master
@@ -656,95 +1080,6 @@
     </section>
 </section>
 
-<section id='performing-a-simple-build'>
-    <title>Performing a Simple Build</title>
-
-    <para>
-        Several methods exist that allow you to build an image within the
-        Yocto Project.
-        This procedure shows how to build an image using BitBake from a
-        Linux host.
-        <note><title>Notes</title>
-            <itemizedlist>
-                <listitem><para>
-                    For information on how to build an image using
-                    <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
-                    see the
-                    <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
-                    </para></listitem>
-                <listitem><para>
-                    For information on how to use
-                    <filename>devtool</filename> to build images, see the
-                    "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>"
-                    section in the Yocto Project Application Development and
-                    the Extensible Software Development Kit (eSDK) manual.
-                    </para></listitem>
-            </itemizedlist>
-        </note>
-    </para>
-
-    <para>
-        The build process creates an entire Linux distribution from source
-        and places it in your
-        <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
-        under <filename>tmp/deploy/images</filename>.
-        For detailed information on the build process using BitBake, see the
-        "<ulink url='&YOCTO_DOCS_REF_URL;#images-dev-environment'>Images</ulink>"
-        section in the Yocto Project Reference Manual.
-        You can also reference the
-        "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
-        section in the Yocto Project Quick Start.
-    </para>
-
-    <para>
-        The following figure and list overviews the build process:
-        <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" />
-        <orderedlist>
-            <listitem><para>
-                <emphasis>Set up Your Host Development System to Support
-                Development Using the Yocto Project</emphasis>:
-                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 for options on how
-                to get a build host ready to use the Yocto Project.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Initialize the Build Environment:</emphasis>
-                Initialize the build environment by sourcing the build
-                environment script (i.e.
-                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Make Sure Your <filename>local.conf</filename>
-                File is Correct:</emphasis>
-                Ensure the <filename>conf/local.conf</filename> configuration
-                file, which is found in the
-                <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
-                is set up how you want it.
-                This file defines many aspects of the build environment
-                including the target machine architecture through the
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
-                the packaging format used during the build
-                (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
-                and a centralized tarball download directory through the
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Build the Image:</emphasis>
-                Build the image using the <filename>bitbake</filename> command.
-                For example, the following command builds the
-                <filename>core-image-minimal</filename> image:
-                <literallayout class='monospaced'>
-     $ bitbake core-image-minimal
-                </literallayout>
-                For information on BitBake, see the
-                <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
-                </para></listitem>
-        </orderedlist>
-    </para>
-</section>
-
--->
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4