bsp-guide, dev-manual: Moved BSP Layer prep steps to bsp-guide

The YP Development Manual had some build host preparation steps
as part of the chapter that talks about getting a host ready
for using YP.  These steps are better suited in the BSP Guide.
I moved them there and filled out the steps to be more complete.

(From yocto-docs rev: 2277812d0dd411a103a4a4252d4cb90c471901c9)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 151 insertions, 2 deletions

diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index c6591cc284..6450c9d0aa 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -145,6 +145,155 @@
             </para>
         </section>
 
+        <section id='preparing-your-build-host-to-work-with-bsp-layers'>
+            <title>Preparing Your Build Host to Work With BSP Layers</title>
+
+            <para>
+                This section describes how to get your build host ready
+                to work with BSP layers.
+                Once you have the host set up, you can create the layer
+                as described in the
+                "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</link>"
+                section.
+                <note>
+                    For structural information on BSPs, see the
+                    <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
+                    section.
+                </note>
+                <orderedlist>
+                    <listitem><para>
+                        <emphasis>Set Up the Build Environment:</emphasis>
+                        Be sure you are set up to use BitBake in a shell.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
+                        section in the Yocto Project Development Manual for information
+                        on how to get a build host ready that is either a native
+                        Linux machine or a machine that uses CROPS.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
+                        You need to have a local copy of the Yocto Project
+                        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+                        (i.e. a local <filename>poky</filename> repository).
+                        See the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
+                        and possibly the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
+                        and
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
+                        sections all in the Yocto Project Development Manual for
+                        information on how to clone the <filename>poky</filename>
+                        repository and check out the appropriate branch for your work.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Determine the BSP Layer You Want:</emphasis>
+                        The Yocto Project supports many BSPs, which are maintained in
+                        their own layers or in layers designed to contain several
+                        BSPs.
+                        To get an idea of machine support through BSP layers, you can
+                        look at the
+                        <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
+                        for the release.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Optionally Clone the
+                        <filename>meta-intel</filename> BSP Layer:</emphasis>
+                        If your hardware is based on current Intel CPUs and devices,
+                        you can leverage this BSP layer.
+                        For details on the <filename>meta-intel</filename> BSP layer,
+                        see the layer's
+                        <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
+                        file.
+                        <orderedlist>
+                            <listitem><para>
+                                <emphasis>Navigate to Your Source Directory:</emphasis>
+                                Typically, you set up the
+                                <filename>meta-intel</filename> Git repository
+                                inside the
+                                <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+                                (e.g. <filename>poky</filename>).
+                                </para></listitem>
+                            <listitem><para>
+                                <emphasis>Clone the Layer:</emphasis>
+                                <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/meta-intel.git
+     Cloning into 'meta-intel'...
+     remote: Counting objects: 14224, done.
+     remote: Compressing objects: 100% (4591/4591), done.
+     remote: Total 14224 (delta 8245), reused 13985 (delta 8006)
+     Receiving objects: 100% (14224/14224), 4.29 MiB | 2.90 MiB/s, done.
+     Resolving deltas: 100% (8245/8245), done.
+     Checking connectivity... done.
+                                </literallayout>
+                                </para></listitem>
+                            <listitem><para>
+                                <emphasis>Check Out the Proper Branch:</emphasis>
+                                The branch you check out for
+                                <filename>meta-intel</filename> must match the same
+                                branch you are using for the Yocto Project release
+                                (e.g. &DISTRO_NAME_NO_CAP;):
+                                <literallayout class='monospaced'>
+     $ git checkout <replaceable>branch_name</replaceable>
+                                </literallayout>
+                                For an example on how to discover branch names and
+                                checkout on a branch, see the
+                                "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
+                                section.
+                                </para></listitem>
+                        </orderedlist>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
+                        If your hardware can be more closely leveraged to an
+                        existing BSP not within the <filename>meta-intel</filename>
+                        BSP layer, you can clone that BSP layer.</para>
+
+                        <para>The process is identical to the process used for the
+                        <filename>meta-intel</filename> layer except for the layer's
+                        name.
+                        For example, if you determine that your hardware most
+                        closely matches the <filename>meta-minnow</filename>,
+                        clone that layer:
+                        <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/meta-minnow
+     Cloning into 'meta-minnow'...
+     remote: Counting objects: 456, done.
+     remote: Compressing objects: 100% (283/283), done.
+     remote: Total 456 (delta 163), reused 384 (delta 91)
+     Receiving objects: 100% (456/456), 96.74 KiB | 0 bytes/s, done.
+     Resolving deltas: 100% (163/163), done.
+     Checking connectivity... done.
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Initialize the Build Environment:</emphasis>
+                        While in the root directory of the Source Directory (i.e.
+                        <filename>poky</filename>), run the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                        environment setup script to define the OpenEmbedded
+                        build environment on your build host.
+                        <literallayout class='monospaced'>
+     $ source &OE_INIT_FILE;
+                        </literallayout>
+                        Among other things, the script creates the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+                        which is <filename>build</filename> in this case
+                        and is located in the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+                        After the script runs, your current working directory
+                        is set to the <filename>build</filename> directory.
+                        <note>
+                            For information on running a memory-resident
+                            <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>,
+                            see the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
+                            setup script.
+                        </note>
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
         <section id="bsp-filelayout">
             <title>Example Filesystem Layout</title>
 
@@ -756,8 +905,8 @@
                         your system gives you access to layers you might be able
                         to build on or modify to create your BSP.
                         For information on how to get these files, see the
-                        "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-bsp-layers'>Setting Up BSP Layers</ulink>"
-                        section in the Yocto Project Development Manual.
+                        "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
+                        section.
                         </para></listitem>
                     <listitem><para>
                         <emphasis>Create Your Own BSP Layer Using the