documentation/adt-manual/adt-prepare.xml: toolchain enhancements

After working through this stuff I was still confused as to how to
guide the user toward proper toolchain installation and on what they
needed to do for collecting their kernel and filesystem images.
These changes included some information on when and how to extract
the rootfs when the user is booting to NFS.  Plus some other
general items like the significance of meta-toolchain-sdk as
compared to meta-toolchain.

(From yocto-docs rev: 2cc88b5193888a074ffd87cb253b9cfe08146877)

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

1 files changed, 76 insertions, 46 deletions

diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index 5e403aa84b..a2618c6ae2 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -194,7 +194,8 @@
         <para>
             If you want to simply install the cross-toolchain by hand, you can do so by using an existing 
             cross-toolchain tarball.  
-            If you install the cross-toolchain by hand, you will have to set up the target sysroot separately.
+            If you use this method to install the cross-toolchain and you still need to install the target 
+            sysroot, you will have to install sysroot separately.
         </para>
 
         <para>
@@ -213,14 +214,21 @@
                     <literallayout class='monospaced'>
      yocto-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2
                    </literallayout>
-                    <note>As an alternative to steps one and two, you can build the toolchain tarball 
+                   The cross-toolchain tarballs provided by the Yocto Project support development
+                   of GNOME platorms on mobile devices (GMAE).
+                    <note><para>As an alternative to steps one and two, you can build the toolchain tarball 
                         if you have a Yocto Project build tree.
-                        Use the <filename>bitbake meta-toolchain</filename> command after you have 
+                        If you need GMAE, you should use the <filename>bitbake meta-toolchain-gmae</filename>
+                        command. 
+                        The resulting tarball will support such development.
+                        However, if you not concerned with GMAE, 
+                        you can generate the tarball using <filename>bitbake meta-toolchain</filename>.</para>
+                        <para>Use the appropriate <filename>bitbake</filename> command only after you have 
                         sourced the <filename>oe-build-init script</filename> located in the Yocto 
                         Project files.  
                         When the <filename>bitbake</filename> command completes, the toolchain tarball will 
                         be in <filename>tmp/deploy/sdk</filename> in the Yocto Project build tree.
-                        </note></para></listitem>
+                        </para></note></para></listitem>
                 <listitem><para>Make sure you are in the root directory with root privileges and then expand 
                     the tarball.  
                     The tarball expands into <filename>/opt/poky/$SDKVERSION</filename>.
@@ -229,11 +237,6 @@
                     </para></listitem>
             </orderedlist>
         </para>
-
-        <para>
-            After installing the toolchain, you must locate the target sysroot tarball and unpack it
-            into a location of your choice.
-        </para>  
     </section>
 
     <section id='using-the-toolchain-from-within-the-build-tree'>
@@ -242,7 +245,14 @@
         <para>
             A final way of installing just the cross-toolchain is to use BitBake within an existing 
             Yocto Project build tree.
-            Follow these steps:
+            This method installs the toolchain into the Yocto Project build tree, not the 
+            <filename>/opt</filename> directory.
+            As with the previous method, if you need to install the target sysroot, you must 
+            do this separately.
+        </para>
+
+        <para>
+            Follow these steps to install the toolchain into the build tree:
             <orderedlist>
                 <listitem><para>Source the environment setup script located in the Yocto Project
                     files.
@@ -268,27 +278,14 @@
                         Be sure to run the <filename>bitbake</filename> command immediately 
                         after checking or editing the <filename>local.conf</filename> but without 
                         changing your working directory.</note>
-                    Once BitBake finishes, the cross-toolchain is installed.
+                    Once BitBake finishes, the cross-toolchain is installed within the Yocto Project
+                    build tree.
                     You will notice environment setup files for the cross-toolchain in the 
                     Yocto Project build tree in the <filename>tmp</filename> directory.
                     Setup script filenames contain the strings <filename>environment-setup</filename>.
                     </para></listitem>
             </orderedlist>
         </para>
-
-        <para>
-            After installing the toolchain, you must locate the target sysroot tarball and unpack
-            it in a directory of your choice.  
-        </para>
-
-        <para>
-            WRITER'S NOTE:  Right now I am a little fuzzy on just how you do this.  
-            I am not sure if you just grab what is in <filename>build/tmp/deploy/images</filename>
-            and then unpack it with the <filename>tar -xjvf [tarball] [directory]</filename> or 
-            if you have to run the tarball environment setup script found in 
-            <filename>build/tmp</filename> and then run the 
-            <filename>runqemu-extract-sdk [tarball] [directory]</filename> command.
-        </para>
     </section>
 </section>
 
@@ -301,9 +298,8 @@
         If you used the ADT Installer or used an existing ADT tarball to install the ADT,
         then you can find this script in the <filename>/opt/poky/$SDKVERSION</filename>
         directory.  
-        If you used BitBake and the Yocto Project Build Tree to install the cross-toolchain,
-        then you can find the environment setup scripts in in the Yocto Project build tree 
-        in the <filename>tmp</filename> directory.
+        If you installed the toolchain in the build tree, you can find the environment setup 
+        scripts in the Yocto Project build tree's <filename>tmp</filename> directory.
     </para>
 
     <para> 
@@ -324,18 +320,29 @@
 
     <para>
         You will need to have a kernel and filesystem image to boot using your 
-        hardware or the QEMU emulator.  
-        That means you either have to build them or know where to get them.
-        You can find a quick example of how to build an image in the 
-        "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section of   
-        <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
-        The Yocto Project Quick Start</ulink>.
-        <note><para> 
-            The Yocto Project provides basic kernels and filesystem images for several 
+        hardware or the QEMU emulator.
+        Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem
+        as the target sysroot, you need to extract the root filesystem.
+        This section describes how to get set up with the kernel and filesystem images.
+    </para>
+
+    <section id='getting-the-images'>
+        <title>Getting the Images</title>
+
+        <para>
+            To get the kernel and filesystem images you either have to build them or download
+            pre-built versions.
+            You can find examples for both these situations in the 
+            "<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#test-run'>A
+            Quick Test Run</ulink>" section of   
+            <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
+            The Yocto Project Quick Start</ulink>.
+            <note><para> 
+            The Yocto Project provides basic kernel and filesystem images for several 
             architectures (<filename>x86</filename>, <filename>x86-64</filename>, 
             <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>) 
             that you can use unaltered in the QEMU emulator.  
-            These kernels and filesystem images reside in the Yocto Project release 
+            These kernel images reside in the Yocto Project release 
             area - <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.1/machines/'></ulink>
             and are ideal for experimentation within Yocto Project.</para>
             <para>If you plan on remotely deploying and debugging your application from within the 
@@ -345,16 +352,39 @@
             Reference: Images</ulink> in  
             <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'>
             The Yocto Project Reference Manual</ulink>.</para>
-        </note>
-    </para>
+            </note>
+        </para>
+    </section>
 
-    <para>
-        WRITER'S NOTE:  It seems to me that you need to take steps to unpack the image filesystem
-        at this point.  
-        This would involve running the tarball environment setup script found in 
-        <filename>build/tmp</filename> and then running the 
-        <filename>runqemu-extract-sdk [tarball] [directory]</filename> command.
-    </para>
+    <section id='extracting-the-root-filesystem'>
+        <title>Extracting the Root Filesystem</title>
+
+        <para>
+            You must extract the root filesystem if you want to boot the image using NFS or you 
+            want to use the root filesystem as the target sysroot.
+            For example, the Eclipse IDE environment with the Eclipse Yocto Plug-in installed allows you 
+            to boot under NFS.
+            Another example is if you want to test your image against actual hardware with the 
+            root filesystem as the target sysroot. 
+        </para>
+
+        <para> 
+            To extract the root filesystem you use the <filename>runqemu-extract-sdk</filename> command on the 
+            filesystem image. 
+            For example, the following command extracts the root filesystem from a previously built
+            filesystem image tarball named  
+            <filename>core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2</filename>.
+            The example extracts the root filesystem into the <filename>$HOME/qemux86-sato</filename>
+            directory:
+            <literallayout class='monospaced'>
+     $ runqemu-extract-sdk \
+        tmp/deploy/images/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
+        $HOME/qemux86-sato
+            </literallayout>
+            In this case, you could now point to the target sysroot at 
+            <filename>$HOME/qemux86-sato</filename>.
+        </para>
+    </section>
 </section>
 
 </chapter>