kernel-dev, dev-manual: Moved Kernel prep steps

The dev-manual had a place-holder section for getting the
build host ready for using YP and then doing kernel
development.  This stuff is better suited for the actual
kernel development manual.  I moved the section.  Moving
created several broken links in the manual set that had to
be fixed.

In the dev-manual, I updated the introductory list to include
the newly moved kernel stuff.

(From yocto-docs rev: 2e21260bb5f84e9e30eb353ec841d5962e8a7642)

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

5 files changed, 203 insertions, 17 deletions

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index c55f68bc24..8c8fe05711 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -474,15 +474,15 @@
         </para>
 
         <para>
-            The example assumes a clean build exists for the <filename>qemux86</filename>
-            machine in a
+            The example builds an extensible SDK, which is then used to
+            build, using <filename>devtool</filename>, a clean image for the
+            default <filename>qemux86</filename> machine in a
             <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
             named <filename>poky</filename>.
-            Furthermore, the
+            In the example, the
             <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
-            is <filename>build</filename> and is located in
-            <filename>poky</filename> and the kernel is based on the
-            Linux 3.4 kernel.
+            is <filename>build</filename> and is located in the default
+            <filename>poky_sdk</filename> directory.
         </para>
 
         <para>
@@ -491,12 +491,74 @@
             section.
         </para>
 
+        <section id='patch-kernel-set-up-the-build-host'>
+            <title>Set Up the Build Host</title>
+
+            <para>
+                Prior to creating any actual patches for your kernel, you
+                need to prepare the build host.
+                This example builds an extensible SDK.
+                Follow these steps:
+                <itemizedlist>
+                    <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>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>
+                </itemizedlist>
+            </para>
+        </section>
+
         <section id='create-a-layer-for-your-changes'>
             <title>Create a Layer for your Changes</title>
 
             <para>
                 The first step is to create a layer so you can isolate your
-                changes.
+                changes to the kernel.
                 Rather than use the <filename>yocto-layer</filename> script
                 to create the layer, this example steps through the process
                 by hand.
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 60d67d64fe..76f52526a3 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -416,8 +416,8 @@
                     Yocto Linux kernel tree.
                     For information on how to clone a Yocto Linux kernel
                     Git repository, see the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Setting Up to Work On a Kernel</ulink>"
-                    section in the Yocto Project Development Manual.
+                    "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
+                    section.
                     </para></listitem>
                 <listitem><para>
                     <emphasis>Temporary Source Files from a Build:</emphasis>
diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml
index 1d8dae3211..15622003e5 100644
--- a/documentation/kernel-dev/kernel-dev-examples.xml
+++ b/documentation/kernel-dev/kernel-dev-examples.xml
@@ -51,10 +51,10 @@
             <literallayout class='monospaced'>
      $ git clone git://git.yoctoproject.org/linux-yocto-3.4
             </literallayout>
-            For another example of how to set up a local Git repository of the Yocto Project
-            kernel files, see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
-            item in the Yocto Project Development Manual.
+            For more information on how to set up a local Git repository of the
+            Yocto Project kernel files, see the
+            "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
+            section.
         </para>
         <para>
             Once you have cloned the kernel Git repository on your local machine, you can
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index 899ed65db2..9080ddc1b8 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -90,6 +90,130 @@
     </para>
 </section>
 
+<section id='preparing-the-build-host-to-work-on-the-kernel'>
+    <title>Preparing the Build Host to Work on the Kernel</title>
+
+    <para>
+        Kernel development is best accomplished using
+        <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
+        and not through traditional kernel workflow methods.
+        This section provides information for both scenarios.
+    </para>
+
+    <section id='getting-ready-to-develop-using-devtool'>
+        <title>Getting Ready to Develop using <filename>devtool</filename></title>
+
+        <para role='writernotes'>
+            Need the updated wiki stuff here
+        </para>
+    </section>
+
+    <section id='getting-ready-for-traditional-kernel-development'>
+        <title>Getting Ready for Traditional Kernel Development</title>
+
+        <para>
+            For traditional kernel development using the Yocto
+            Project, you need to establish local copies of the
+            kernel source.
+            You can find Git repositories of supported Yocto Project
+            kernels organized under "Yocto Linux Kernel" in the Yocto
+            Project Source Repositories at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
+        </para>
+
+        <para>
+            This setup can involve creating a bare clone of the
+            Yocto Project kernel and then copying that cloned
+            repository.
+            You can create the bare clone and the copy of the bare
+            clone anywhere you like.
+            For simplicity, it is recommended that you create these
+            structures outside of the
+            <ulink url='&YOCTO_DOCS_REF_URL;source-directory'>Source Directory</ulink>,
+            which is usually named <filename>poky</filename>.
+        </para>
+
+        <para>
+            The following steps show how to create a bare clone of the
+            <filename>linux-yocto-4.4</filename> kernel and then
+            create a copy of that clone:
+            <note>
+                When you have a local Yocto Project kernel Git
+                repository, you can reference that repository rather than
+                the upstream Git repository as part of the
+                <filename>clone</filename> command.
+                Doing so can speed up the process.
+            </note>
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Create the Bare Clone:</emphasis>
+                    In the following example, the bare clone is named
+                    <filename>linux-yocto-4.4.git</filename>:
+                    <literallayout class='monospaced'>
+     $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-4.4 linux-yocto-4.4.git
+     Cloning into bare repository 'linux-yocto-4.4.git'...
+     remote: Counting objects: 4543903, done.
+     remote: Compressing objects: 100% (695618/695618), done.
+     remote: Total 4543903 (delta 3818435), reused 4541724 (delta 3816256)
+     Receiving objects: 100% (4543903/4543903), 801.08 MiB | 6.55 MiB/s, done.
+     Resolving deltas: 100% (3818435/3818435), done.
+     Checking connectivity... done.
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Create the Copy of the Bare Clone:</emphasis>
+                    In the following command, the copy of the bare clone
+                    is named <filename>my-linux-yocto-4.4-work</filename>:
+                    <literallayout class='monospaced'>
+     $ git clone linux-yocto-4.4.git my-linux-yocto-4.4-work
+     Cloning into 'my-linux-yocto-4.4-work'...
+     done.
+     Checking out files: 100% (52221/52221), done.
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Cloning the <filename>meta-yocto-kernel-extras</filename> Repository:</emphasis>
+                    The <filename>meta-yocto-kernel-extras</filename> Git
+                    repository contains Metadata needed only if you are
+                    modifying and building the kernel image.
+                    In particular, it contains the kernel BitBake append
+                    (<filename>.bbappend</filename>) files that you edit to
+                    point to your locally modified kernel source files and
+                    to build the kernel image.
+                    Pointing to these local files is much more efficient
+                    than requiring a download of the kernel's source files
+                    from upstream each time you make changes to the kernel.
+                    </para>
+
+                    <para>You can find the
+                    <filename>meta-yocto-kernel-extras</filename> Git
+                    Repository in the "Yocto Metadata Layers" area of the
+                    Yocto Project Source Repositories at
+                    <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
+                    It is good practice to create this Git repository
+                    inside the Source Directory.</para>
+
+                    <para>Following is an example that creates the
+                    <filename>meta-yocto-kernel-extras</filename> Git
+                    repository inside the Source Directory, which is named
+                    <filename>poky</filename>, in this case:
+                    <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
+     Cloning into 'meta-yocto-kernel-extras'...
+     remote: Counting objects: 727, done.
+     remote: Compressing objects: 100% (452/452), done.
+     remote: Total 727 (delta 260), reused 719 (delta 252)
+     Receiving objects: 100% (727/727), 536.36 KiB | 0 bytes/s, done.
+     Resolving deltas: 100% (260/260), done.
+     Checking connectivity... done.
+                    </literallayout>
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+</section>
+
 <section id='kernel-modification-workflow'>
     <title>Kernel Modification Workflow</title>
 
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
index 7cfcb45c94..446bace5ea 100644
--- a/documentation/kernel-dev/kernel-dev-maint-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -34,10 +34,10 @@
             <literallayout class='monospaced'>
      $ git clone git://git.yoctoproject.org/linux-yocto-3.19
             </literallayout>
-            For another example of how to set up a local Git repository of the Yocto Project
-            kernel files, see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
-            item in the Yocto Project Development Manual.
+            For more information on how to set up a local Git repository of
+            the Yocto Project kernel files, see the
+            "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
+            section.
         </para>
         <para>
             Once you have cloned the kernel Git repository on your local machine, you can