Revert "poky: subtree update:b23aa6b753..ad30a6d470"

This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.

This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.

Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c

1 files changed, 1288 insertions, 0 deletions

diff --git a/poky/documentation/dev-manual/dev-manual-start.xml b/poky/documentation/dev-manual/dev-manual-start.xml
new file mode 100644
index 000000000..9ff9ac4c8
--- /dev/null
+++ b/poky/documentation/dev-manual/dev-manual-start.xml
@@ -0,0 +1,1288 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='dev-manual-start'>
+
+<title>Setting Up to Use the Yocto Project</title>
+
+<para>
+    This chapter provides guidance on how to prepare to use the
+    Yocto Project.
+    You can learn about creating a team environment that develops using the
+    Yocto Project, how to set up a
+    <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>,
+    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 how to scale it for a
+        large team of developers.
+        You can adapt the Yocto Project to many different use cases and
+        scenarios;
+        however, this flexibility could cause difficulties if you are trying
+        to create a working setup that scales effectively.
+    </para>
+
+    <para>
+        To help you understand how to set up this type of environment,
+        this section presents a procedure that gives you information
+        that can help you 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 have proved to work well in the past;
+        however, keep in mind, the procedure here is simply a starting point.
+        You can build off these steps and customize the procedure to fit any
+        particular working environment and set of practices.
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Determine Who is Going to be Developing:</emphasis>
+                You first need to understand who is going to be doing anything
+                related to the Yocto Project and determine their roles.
+                Making this determination is essential to completing
+                subsequent steps, 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 Developer:</emphasis>
+                            This type of developer does application level work
+                            on top of an existing software stack.
+                            </para></listitem>
+                        <listitem><para>
+                            <emphasis>Core System Developer:</emphasis>
+                            This type of developer works 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. Depending on the specifics of the environment,
+                            not all situations might need a Build Engineer.
+                            </para></listitem>
+                        <listitem><para>
+                            <emphasis>Test Engineer:</emphasis>
+                            This type of developer creates and manages automated
+                            tests that are used 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.
+                Ideally, any development, build, or test engineer uses
+                a system that runs a supported Linux distribution.
+                These 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.
+                <note>
+                    Given sufficient processing power, you might also consider
+                    building Yocto Project development containers to be run
+                    under Docker, which is described later.
+                </note>
+                </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>
+                (i.e. recipes, configuration files, classes, and so forth)
+                and any software you are developing under the control of an SCM
+                system that is compatible   with the OpenEmbedded build system
+                is advisable.
+                Of all of the SCMs supported by BitBake, 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 back up,
+                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 the following 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
+                used for 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>
+                        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 depend
+                        on 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, core 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
+                        <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+                        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.
+                Based on this automated build and test environment, 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 the Yocto Project team uses 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
+                        <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate cache</ulink>
+                        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 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
+                        "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+                        section in the Yocto Project Overview and Concepts
+                        Manual and 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 in the Yocto Project Overview and Concepts
+                        Manual 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='dev-preparing-the-build-host'>
+    <title>Preparing the Build Host</title>
+
+    <para>
+        This section provides procedures to set up a system to be used as your
+        <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+        for development using the Yocto Project.
+        Your build host can be a native Linux machine (recommended), it can
+        be a machine (Linux, Mac, or Windows) that uses
+        <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>,
+        which leverages
+        <ulink url='https://www.docker.com/'>Docker Containers</ulink> or it can
+        be a Windows machine capable of running Windows Subsystem For Linux v2 (WSL).
+        <note>
+          The Yocto Project is not compatible with
+          <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux v1</ulink>.
+          It is compatible but not officially supported nor validated with WSLv2.
+          If you still decide to use WSL please upgrade to
+          <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>WSLv2</ulink>.
+        </note>
+    </para>
+
+    <para>
+        Once your build host is set up to use the Yocto Project,
+        further steps are necessary depending on what you want to
+        accomplish.
+        See the following references for information on how to prepare for
+        Board Support Package (BSP) development and kernel development:
+        <itemizedlist>
+            <listitem><para>
+                <emphasis>BSP Development:</emphasis>
+                See the
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>"
+                section in the Yocto Project Board Support Package (BSP)
+                Developer's Guide.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Kernel Development:</emphasis>
+                See the
+                "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>"
+                section in the Yocto Project Linux Kernel Development Manual.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <section id='setting-up-a-native-linux-host'>
+        <title>Setting Up a Native Linux Host</title>
+
+        <para>
+            Follow these steps to prepare a native Linux machine as your
+            Yocto Project Build Host:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Use a Supported Linux Distribution:</emphasis>
+                    You should have a reasonably current Linux-based host
+                    system.
+                    You will have the best results with a recent release of
+                    Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS as these
+                    releases are frequently tested against the Yocto Project
+                    and officially supported.
+                    For a list of the distributions under validation and their
+                    status, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
+                    in the Yocto Project Reference Manual and the wiki page at
+                    <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Have Enough Free Memory:</emphasis>
+                    Your system should have at least 50 Gbytes of free disk
+                    space for building images.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Meet Minimal Version Requirements:</emphasis>
+                    The OpenEmbedded build system should be able to run on any
+                    modern distribution that has the following versions for
+                    Git, tar, Python and gcc.
+                    <itemizedlist>
+                        <listitem><para>
+                            Git 1.8.3.1 or greater
+                            </para></listitem>
+                        <listitem><para>
+                            tar 1.28 or greater
+                            </para></listitem>
+                        <listitem><para>
+                            Python 3.5.0 or greater.
+                        </para></listitem>
+                        <listitem><para>
+                            gcc 5.0 or greater.
+                        </para></listitem>
+                    </itemizedlist>
+                    If your build host does not meet any of these three listed
+                    version requirements, you can take steps to prepare the
+                    system so that you can still use the Yocto Project.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</ulink>"
+                    section in the Yocto Project Reference Manual for
+                    information.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Install Development Host Packages:</emphasis>
+                    Required development host packages vary depending on your
+                    build host and what you want to do with the Yocto
+                    Project.
+                    Collectively, the number of required packages is large
+                    if you want to be able to cover all cases.</para>
+
+                    <para>For lists of required packages for all scenarios,
+                    see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"
+                    section in the Yocto Project Reference Manual.
+                    </para></listitem>
+            </orderedlist>
+            Once you have completed the previous steps, you are ready to
+            continue using a given development path on your native Linux
+            machine.
+            If you are going to use BitBake, see the
+            "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+            section.
+            If you are going to use the Extensible SDK, see the
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+            Chapter in the Yocto Project Application Development and the
+            Extensible Software Development Kit (eSDK) manual.
+            If you want to work on the kernel, see the
+            <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
+            If you are going to use Toaster, see the
+            "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+            section in the Toaster User Manual.
+        </para>
+    </section>
+
+    <section id='setting-up-to-use-crops'>
+        <title>Setting Up to Use CROss PlatformS (CROPS)</title>
+
+        <para>
+            With
+            <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>,
+            which leverages
+            <ulink url='https://www.docker.com/'>Docker Containers</ulink>,
+            you can create a Yocto Project development environment that
+            is operating system agnostic.
+            You can set up a container in which you can develop using the
+            Yocto Project on a Windows, Mac, or Linux  machine.
+        </para>
+
+        <para>
+            Follow these general steps to prepare a Windows, Mac, or Linux
+            machine as your Yocto Project build host:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Determine What Your Build Host Needs:</emphasis>
+                    <ulink url='https://www.docker.com/what-docker'>Docker</ulink>
+                    is a software container platform that you need to install
+                    on the build host.
+                    Depending on your build host, you might have to install
+                    different software to support Docker containers.
+                    Go to the Docker installation page and read about the
+                    platform requirements in
+                    "<ulink url='https://docs.docker.com/install/#supported-platforms'>Supported Platforms</ulink>"
+                    your build host needs to run containers.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Choose What To Install:</emphasis>
+                    Depending on whether or not your build host meets system
+                    requirements, you need to install "Docker CE Stable" or
+                    the "Docker Toolbox".
+                    Most situations call for Docker CE.
+                    However, if you have a build host that does not meet
+                    requirements (e.g. Pre-Windows 10 or Windows 10 "Home"
+                    version), you must install Docker Toolbox instead.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Go to the Install Site for Your Platform:</emphasis>
+                    Click the link for the Docker edition associated with
+                    your build host's native software.
+                    For example, if your build host is running Microsoft
+                    Windows Version 10 and you want the Docker CE Stable
+                    edition, click that link under "Supported Platforms".
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Install the Software:</emphasis>
+                    Once you have understood all the pre-requisites, you can
+                    download and install the appropriate software.
+                    Follow the instructions for your specific machine and
+                    the type of the software you need to install:
+                    <itemizedlist>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/docker-for-windows/install/#install-docker-for-windows-desktop-app'>Docker CE for Windows</ulink>
+                            for Windows build hosts that meet requirements.
+                            </para></listitem>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-for-mac'>Docker CE for Macs</ulink>
+                            for Mac build hosts that meet requirements.
+                            </para></listitem>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/toolbox/toolbox_install_windows/'>Docker Toolbox for Windows</ulink>
+                            for Windows build hosts that do not meet Docker
+                            requirements.
+                            </para></listitem>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/toolbox/toolbox_install_mac/'>Docker Toolbox for MacOS</ulink>
+                            for Mac build hosts that do not meet Docker
+                            requirements.
+                            </para></listitem>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/install/linux/docker-ce/centos/'>Docker CE for CentOS</ulink>
+                            for Linux build hosts running the CentOS
+                            distribution.
+                            </para></listitem>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/install/linux/docker-ce/debian/'>Docker CE for Debian</ulink>
+                            for Linux build hosts running the Debian
+                            distribution.
+                            </para></listitem>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/install/linux/docker-ce/fedora/'>Docker CE for Fedora</ulink>
+                            for Linux build hosts running the Fedora
+                            distribution.
+                            </para></listitem>
+                        <listitem><para>
+                            Install
+                            <ulink url='https://docs.docker.com/install/linux/docker-ce/ubuntu/'>Docker CE for Ubuntu</ulink>
+                            for Linux build hosts running the Ubuntu
+                            distribution.
+                            </para></listitem>
+                    </itemizedlist>
+                    </para></listitem>
+                <listitem><para>
+                    <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>.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Launch Docker or Docker Toolbox:</emphasis>
+                    You should be able to launch Docker or the Docker Toolbox
+                    and have a terminal shell on your development host.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Set Up the Containers to Use the Yocto Project:</emphasis>
+                    Go to
+                    <ulink url='https://github.com/crops/docker-win-mac-docs/wiki'></ulink>
+                    and follow the directions for your particular
+                    build host (i.e. Linux, Mac, or Windows).</para>
+
+                    <para>Once you complete the setup instructions for your
+                    machine, you have the Poky, Extensible SDK, and Toaster
+                    containers available.
+                    You can click those links from the page and learn more
+                    about using each of those containers.
+                    </para></listitem>
+            </orderedlist>
+            Once you have a container set up, everything is in place to
+            develop just as if you were running on a native Linux machine.
+            If you are going to use the Poky container, see the
+            "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+            section.
+            If you are going to use the Extensible SDK container, see the
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+            Chapter in the Yocto Project Application Development and the
+            Extensible Software Development Kit (eSDK) manual.
+            If you are going to use the Toaster container, see the
+            "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+            section in the Toaster User Manual.
+        </para>
+    </section>
+
+    <section id='setting-up-to-use-wsl'>
+        <title>Setting Up to Use Windows Subsystem For Linux (WSLv2)</title>
+
+        <para>
+            With <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'>
+            Windows Subsystem for Linux (WSLv2)</ulink>, you can create a
+            Yocto Project development environment that allows you to build
+            on Windows. You can set up a Linux distribution inside Windows
+            in which you can develop using the Yocto Project.
+        </para>
+
+        <para>
+            Follow these general steps to prepare a Windows machine using WSLv2
+            as your Yocto Project build host:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Make sure your Windows 10 machine is capable of running WSLv2:</emphasis>
+                  
+                    WSLv2 is only available for Windows 10 builds > 18917. To
+                    check which build version you are running, you may open a
+                    command prompt on Windows and execute the command "ver".
+                    <literallayout class='monospaced'>
+    C:\Users\myuser> ver
+
+    Microsoft Windows [Version 10.0.19041.153]
+                    </literallayout>
+                    If your build is capable of running WSLv2 you may continue,
+                    for more information on this subject or instructions on how
+                    to upgrade to WSLv2 visit <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>Windows 10 WSLv2</ulink>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Install the Linux distribution of your choice inside Windows 10:</emphasis>
+                    Once you know your version of Windows 10 supports WSLv2,
+                    you can install the distribution of your choice from the
+                    Microsoft Store.
+                    Open the Microsoft Store and search for Linux. While there
+                    are several Linux distributions available, the assumption
+                    is that your pick will be one of the distributions supported
+                    by the Yocto Project as stated on the instructions for
+                    using a native Linux host.
+                    After making your selection, simply click "Get" to download
+                    and install the distribution.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Check your Linux distribution is using WSLv2:</emphasis>
+                    Open a Windows PowerShell and run:
+                    <literallayout class='monospaced'>
+    C:\WINDOWS\system32> wsl -l -v
+    NAME      STATE           VERSION
+    *Ubuntu    Running         2
+                    </literallayout>
+                    Note the version column which says the WSL version being used by
+                    your distribution, on compatible systems, this can be changed back
+                    at any point in time.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Optionally Orient Yourself on WSL:</emphasis>
+                    If you are unfamiliar with WSL, you can learn more here -
+                    <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'></ulink>.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Launch your WSL Distibution:</emphasis>
+                    From the Windows start menu simply launch your WSL distribution
+                    just like any other application.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Optimize your WSLv2 storage often:</emphasis>
+                    Due to the way storage is handled on WSLv2, the storage
+                    space used by the undelying Linux distribution is not
+                    reflected immedately, and since bitbake heavily uses
+                    storage, after several builds, you may be unaware you
+                    are running out of space. WSLv2 uses a VHDX file for
+                    storage, this issue can be easily avoided by manually
+                    optimizing this file often, this can be done in the
+                    following way:
+                    <orderedlist>
+                        <listitem><para>
+                            <emphasis>Find the location of your VHDX file:</emphasis>
+                            First you need to find the distro app package directory,
+                            to achieve this open a Windows Powershell as Administrator
+                            and run:
+                            <literallayout class='monospaced'>
+    C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
+    PackageFamilyName
+    -----------------
+    CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
+                            </literallayout>
+                            You should now replace the <replaceable>PackageFamilyName</replaceable>
+                            and your <replaceable>user</replaceable> on the following
+                            path to find your VHDX file: <filename>C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\</filename>
+                            For example:
+                            <literallayout class='monospaced'>
+    ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
+    Mode                 LastWriteTime         Length Name
+    -a----         3/14/2020   9:52 PM    57418973184 ext4.vhdx                      
+                            </literallayout>
+                            Your VHDX file path is: <filename>C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx</filename>
+                            </para></listitem>
+                        <listitem><para><emphasis>Optimize your VHDX file:</emphasis>
+                            Open a Windows Powershell as Administrator to optimize
+                            your VHDX file, shutting down WSL first:
+                            <literallayout class='monospaced'>
+    C:\WINDOWS\system32> wsl --shutdown
+    C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full
+                            </literallayout>
+                            A progress bar should be shown while optimizing the VHDX file,
+                            and storage should now be reflected correctly on the Windows
+                            Explorer.
+                            </para></listitem>
+                    </orderedlist>
+                </para></listitem>
+            </orderedlist>
+            <note>
+              The current implementation of WSLv2 does not have out-of-the-box
+              access to external devices such as those connected through a
+              USB port, but it automatically mounts your <filename>C:</filename>
+              drive on <filename>/mnt/c/</filename> (and others), which
+              you can use to share deploy artifacts to be later flashed on
+              hardware through Windows, but your build directory should not
+              reside inside this mountpoint.
+            </note>
+            Once you have WSLv2 set up, everything is in place to
+            develop just as if you were running on a native Linux machine.
+            If you are going to use the Extensible SDK container, see the
+            "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+            Chapter in the Yocto Project Application Development and the
+            Extensible Software Development Kit (eSDK) manual.
+            If you are going to use the Toaster container, see the
+            "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+            section in the Toaster User Manual.
+        </para>
+    </section>
+</section>
+
+<section id='locating-yocto-project-source-files'>
+    <title>Locating Yocto Project Source Files</title>
+
+    <para>
+        This section shows you how to locate, fetch and configure the source
+        files you'll need to work with the Yocto Project.
+        <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_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_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+                    section in the Yocto Project Overview and Concepts Manual."
+                    </para></listitem>
+            </itemizedlist>
+        </note>
+    </para>
+
+    <section id='accessing-source-repositories'>
+        <title>Accessing Source Repositories</title>
+
+        <para>
+            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>
+                    Open a browser and go to
+                    <ulink url='&YOCTO_GIT_URL;'></ulink> to access the
+                    GUI-based interface into the Yocto Project source
+                    repositories.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Select the Repository:</emphasis>
+                    Click on the repository in which you are interested (e.g.
+                    <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_OM_URL;#git-commands-clone'>clone</ulink>
+                    that repository (e.g.
+                    <filename>&YOCTO_GIT_URL;/poky</filename>).
+                    <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>
+    </section>
+
+    <section id='accessing-index-of-releases'>
+        <title>Accessing Index of Releases</title>
+
+        <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 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 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>
+            Follow these steps to locate and download a particular tarball:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Access the Index of Releases:</emphasis>
+                    Open a browser and go to
+                    <ulink url='&YOCTO_DL_URL;/releases'></ulink> to access the
+                    Index of Releases.
+                    The list represents released components (e.g.
+                    <filename>bitbake</filename>,
+                    <filename>sato</filename>, and so on).
+                    <note>
+                        The <filename>yocto</filename> directory contains the
+                        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 now only for retroactive
+                        completeness.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Select a Component:</emphasis>
+                    Click on any released component in which you are interested
+                    (e.g. <filename>yocto</filename>).
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Find the Tarball:</emphasis>
+                    Drill down to find the associated tarball.
+                    For example, click on <filename>yocto-&DISTRO;</filename> to
+                    view files associated with the Yocto Project &DISTRO;
+                    release (e.g. <filename>poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;.tar.bz2</filename>,
+                    which is the released Poky 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 id='using-the-downloads-page'>
+        <title>Using the Downloads Page</title>
+
+        <para>
+            The
+            <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+            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 similar to the tarballs located in the Index of Releases
+            described in the
+            "<link linkend='accessing-index-of-releases'>Accessing Index of Releases</link>"
+            section.
+            <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.
+                The procedure in this section exists should you desire a
+                tarball snapshot of any given component.
+            </note>
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Go to the Yocto Project Website:</emphasis>
+                    Open The
+                    <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+                    in your browser.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Get to the Downloads Area:</emphasis>
+                    Select the "DOWNLOADS" item from the pull-down
+                    "SOFTWARE" tab menu near the top of the page.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Select a Yocto Project Release:</emphasis>
+                    Use the menu next to "RELEASE" to display and choose
+                    a recent or past supported Yocto Project release
+                    (e.g. &DISTRO_NAME_NO_CAP;,
+                    &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth).
+                    <note><title>Tip</title>
+                        For a "map" of Yocto Project releases to version
+                        numbers, see the
+                        <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink>
+                        wiki page.
+                    </note>
+                    You can use the "RELEASE ARCHIVE" link to reveal a menu of
+                    all Yocto Project releases.
+                </para></listitem>
+                <listitem><para>
+                    <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='accessing-nightly-builds'>
+        <title>Accessing Nightly Builds</title>
+
+        <para>
+            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 ("poky"),
+            toolchains, and builds for supported machines.
+        </para>
+
+        <para>
+            Should you ever want to access a nightly build of a particular
+            Yocto Project component, use the following procedure:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Locate the Index of 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 Date:</emphasis>
+                    Click on the date in which you are interested.
+                    If you want the latest builds, use "CURRENT".
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Select a Build:</emphasis>
+                    Choose the area in which you are interested.
+                    For example, if you are looking for the most recent
+                    toolchains, select the "toolchain" link.
+                    </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-branches'>
+    <title>Cloning and Checking Out Branches</title>
+
+    <para>
+        To use the Yocto Project for development, you need a release locally
+        installed on your development system.
+        This 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>
+        The preferred method of creating your Source Directory is by using
+        <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local
+        copy of the upstream <filename>poky</filename> repository.
+        Working from a cloned copy of the upstream repository allows you
+        to contribute back into the Yocto Project or to 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
+            upstream
+            <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink>
+            Git repository.
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Set Your Directory:</emphasis>
+                    Change your working directory to where you want to
+                    create your local copy of
+                    <filename>poky</filename>.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Clone the Repository:</emphasis>
+                    The following example command clones the
+                    <filename>poky</filename> repository and uses
+                    the default name "poky" for your local repository:
+                    <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky
+     Cloning into 'poky'...
+     remote: Counting objects: 432160, done.
+     remote: Compressing objects: 100% (102056/102056), done.
+     remote: Total 432160 (delta 323116), reused 432037 (delta 323000)
+     Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
+     Resolving deltas: 100% (323116/323116), done.
+     Checking connectivity... done.
+                    </literallayout>
+                    Unless you specify a specific development branch or
+                    tag name, Git clones the "master" branch, which results
+                    in a snapshot of the latest development changes for
+                    "master".
+                    For information on how to check out a specific
+                    development branch or on how to check out a local
+                    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>"
+                    sections, respectively.</para>
+
+                    <para>Once the local repository is created, you can
+                    change to that directory and check its status.
+                    Here, the single "master" branch exists on your system
+                    and by default, it is checked out:
+                    <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ git status
+     On branch master
+     Your branch is up-to-date with 'origin/master'.
+     nothing to commit, working directory clean
+     $ git branch
+     * master
+                    </literallayout>
+                    Your local repository of poky is identical to the
+                    upstream poky repository at the time from which it was
+                    cloned.
+                    As you work with the local branch, you can periodically
+                    use the <filename>git pull &dash;&dash;rebase</filename>
+                    command to be sure you are up-to-date with the upstream
+                    branch.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='checking-out-by-branch-in-poky'>
+        <title>Checking Out by Branch in Poky</title>
+
+        <para>
+            When you clone the upstream poky repository, you have access to
+            all its development branches.
+            Each development branch in a repository is unique as it forks
+            off the "master" branch.
+            To see and use the files of a particular development branch
+            locally, you need to know the branch name and then specifically
+            check out that development branch.
+            <note>
+                Checking out an active development branch by branch name
+                gives you a snapshot of that particular branch at the time
+                you check it out.
+                Further development on top of the branch that occurs after
+                check it out can occur.
+            </note>
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Switch to the Poky Directory:</emphasis>
+                    If you have a local poky Git repository, switch to that
+                    directory.
+                    If you do not have the local copy of poky, see the
+                    "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+                    section.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Determine Existing Branch Names:</emphasis>
+                    <literallayout class='monospaced'>
+     $ git branch -a
+     * master
+       remotes/origin/1.1_M1
+       remotes/origin/1.1_M2
+       remotes/origin/1.1_M3
+       remotes/origin/1.1_M4
+       remotes/origin/1.2_M1
+       remotes/origin/1.2_M2
+       remotes/origin/1.2_M3
+           .
+           .
+           .
+       remotes/origin/thud
+       remotes/origin/thud-next
+       remotes/origin/warrior
+       remotes/origin/warrior-next
+       remotes/origin/zeus
+       remotes/origin/zeus-next
+       ... and so on ...
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Check out the Branch:</emphasis>
+                    Check out the development branch in which you want to work.
+                    For example, to access the files for the Yocto Project
+                    &DISTRO; Release (&DISTRO_NAME;), use the following command:
+                    <literallayout class='monospaced'>
+     $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
+     Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
+     Switched to a new branch '&DISTRO_NAME_NO_CAP;'
+                    </literallayout>
+                    The previous command checks out the "&DISTRO_NAME_NO_CAP;"
+                    development branch and reports that the branch is tracking
+                    the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.</para>
+
+                    <para>The following command displays the branches
+                    that are now part of your local poky repository.
+                    The asterisk character indicates the branch that is
+                    currently checked out for work:
+                    <literallayout class='monospaced'>
+     $ git branch
+       master
+     * &DISTRO_NAME_NO_CAP;
+                    </literallayout>
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='checkout-out-by-tag-in-poky'>
+        <title>Checking Out by Tag in Poky</title>
+
+        <para>
+            Similar to branches, the upstream repository uses tags
+            to mark specific commits associated with significant points in
+            a development branch (i.e. a release point or stage of a
+            release).
+            You might want to set up a local branch based on one of those
+            points in the repository.
+            The process is similar to checking out by branch name except you
+            use tag names.
+            <note>
+                Checking out a branch based on a tag gives you a
+                stable set of files not affected by development on the
+                branch above the tag.
+            </note>
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Switch to the Poky Directory:</emphasis>
+                    If you have a local poky Git repository, switch to that
+                    directory.
+                    If you do not have the local copy of poky, see the
+                    "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+                    section.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Fetch the Tag Names:</emphasis>
+                    To checkout the branch based on a tag name, you need to
+                    fetch the upstream tags into your local repository:
+                    <literallayout class='monospaced'>
+     $ git fetch --tags
+     $
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>List the Tag Names:</emphasis>
+                    You can list the tag names now:
+                    <literallayout class='monospaced'>
+     $ git tag
+     1.1_M1.final
+     1.1_M1.rc1
+     1.1_M1.rc2
+     1.1_M2.final
+     1.1_M2.rc1
+        .
+        .
+        .
+     yocto-2.5
+     yocto-2.5.1
+     yocto-2.5.2
+     yocto-2.5.3
+     yocto-2.6
+     yocto-2.6.1
+     yocto-2.6.2
+     yocto-2.7
+     yocto_1.5_M5.rc8
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Check out the Branch:</emphasis>
+                    <literallayout class='monospaced'>
+     $ git checkout tags/&DISTRO_REL_TAG; -b my_yocto_&DISTRO;
+     Switched to a new branch 'my_yocto_&DISTRO;'
+     $ git branch
+       master
+     * my_yocto_&DISTRO;
+                    </literallayout>
+                    The previous command creates and checks out a local
+                    branch named "my_yocto_&DISTRO;", which is based on
+                    the commit in the upstream poky repository that has
+                    the same tag.
+                    In this example, the files you have available locally
+                    as a result of the <filename>checkout</filename>
+                    command are a snapshot of the
+                    "&DISTRO_NAME_NO_CAP;" development branch at the point
+                    where Yocto Project &DISTRO; was released.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->