documentation/adt-manual/adt-prepare.xml: Updates to ADT install steps

Significant re-write to every section in this chapter except the
"Setting Up the Environment" and "Kernels and Filesystem Images"
chapters.  I established some terms to communicate the build and
source trees and the build and source top-level directories for
YP.  These terms had not been consitently communicated.  I also
stepped through each of the three methods by which a user can
install ADT (and the cross-toolchain) and meticulously documented
the steps.  The result is a much more complete and clear set
of procedures.

(From yocto-docs rev: 37076a07ccc748ceb416c4bc3a57b698f6e8d80a)

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

1 files changed, 247 insertions, 143 deletions

diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index f27f603..99085d2 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -6,74 +6,159 @@
 <title>Preparing to Use the Application Development Toolkit (ADT)</title>
 
 <para>
-    In order to use the ADT it must be installed, the environment setup script must be 
-    sourced, and the kernel and filesystem image specific to the target architecture must exist.  
-    This section describes how to install the ADT, set up the environment, and provides 
-    some reference information on kernels and filesystem images.
+    In order to use the ADT you must install it, source a script to set up the 
+    environment, and be sure the kernel and filesystem image specific to the target architecture 
+    exists. 
+</para>
+
+<para> 
+    This section describes how to be sure you meet these requirements.
+    Througout this section two important terms are used:
+    <itemizedlist>
+        <listitem><para><emphasis>Yocto Project Source Tree:</emphasis>
+        This term refers to the directory structure created as a result of downloading 
+        and unpacking a Yocto Project release tarball.
+        The Yocto Project source tree contains Bitbake, Documentation, Meta-data and 
+        other files. 
+        The name of the top-level directory of the Yocto Project source tree  
+        is derived from the Yocto Project release tarball.
+        For example, downloading and unpacking <filename>poky-bernard-5.0.1.tar.bz2</filename>
+        results in a Yocto Project source tree whose Yocto Project source directory is named 
+        <filename>poky-bernard-5.0.1</filename>.</para></listitem>
+        <listitem><para><emphasis>Yocto Project Build Tree:</emphasis>
+        This term refers to the area where you run your builds.  
+        The area is created when you source the Yocto Project setup environment script
+        that is found in the Yocto Project source directory 
+        (e.g. <filename>poky-init-build-env</filename>).
+        You can create the Yocto Project build tree anywhere you want on your 
+        development system.
+        Here is an example that creates the tree in <filename>mybuilds</filename> 
+        and names the Yocto Project build directory <filename>YP-5.0.1</filename>:
+        <literallayout class='monospaced'> 
+     $ source poky-bernard-5.0.1/poky-init-build-env $HOME/mybuilds/YP-5.0.1
+        </literallayout>
+        If you don't specifically name the build directory then Bitbake creates it 
+        in the current directory and uses the name <filename>build</filename>.
+        Also, if you supply an existing directory then Bitbake uses that 
+        directory as the Yocto Project build directory and populates the build tree
+        beneath it.</para></listitem>
+    </itemizedlist>
 </para>
 
 <section id='installing-the-adt'>
     <title>Installing the ADT</title>
+
     <para>
-        You can install the ADT three ways.  
-        However, we recommend configuring and running the ADT Installer script.  
-        Running this script automates much of the process for you.  
-        For example, the script allows you to install the QEMU emulator and 
-        user-space NFS, define which root filesystem profiles to download, 
-        and allows you to define the target sysroot location.
+        The following list describes how you can install the ADT, which includes the cross-toolchain.
+        Regardless of the installation you choose, however, you must source the cross-toolchain
+        environment setup script before you use the toolchain.
+        See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> 
+        section for more information.
+        <itemizedlist>
+            <listitem><para><emphasis>Use the ADT Installer Script:</emphasis>
+            This method is the recommended way to install the ADT because it
+            automates much of the process for you.
+            For example, you can configure the installation to install the QEMU emulator
+            and the user-space NFS, specify which root filesystem profiles to download, 
+            and define the target sysroot location.
+            </para></listitem>
+            <listitem><para><emphasis>Use an Existing Toolchain Tarball:</emphasis>
+            Using this method you select and download an architecture-specific
+            toolchain tarball and then hand-install the toolchain.
+            If you use this method you just get the cross-toolchain and QEMU - you do not 
+            get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
+            <listitem><para><emphasis>Use the Toolchain from Within a Yocto Project Build Tree:</emphasis>
+            If you already have a Yocto Project build tree you can install the cross-toolchain 
+            using that tree.
+            However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you 
+            do not get any of the other benefits without taking separate steps.</para></listitem>
+        </itemizedlist>
     </para>
-    <note>
-        If you need to generate the ADT tarball you can do so using the following command:
-        <literallayout class='monospaced'>
-     $ bitbake adt-installer
-        </literallayout>
-        This command generates the file <filename>adt-installer.tar.bz2</filename>
-        in the <filename>../build/tmp/deploy/sdk</filename> directory.
-    </note>
 
-    <section id='configuring-and-running-the-adt-installer'>
-        <title>Configuring and Running the ADT Installer</title>
+    <section id='using-the-adt-installer'>
+        <title>Using the ADT Installer</title>
+
         <para>
-            The ADT Installer is contained in a tarball that can be built using 
-            <filename>bitbake adt-installer</filename>. 
-            Yocto Project has a pre-built ADT Installer tarball that you can download 
-            from <filename>tmp/deploy/sdk</filename> located in the build directory.
+            To run the ADT Installer you need to first get the ADT Installer tarball and then run the ADT
+            Installer Script.
         </para>
 
-        <note>
-            You can install and run the ADT Installer tarball in any directory you want.
-        </note>
+        <section id='getting-the-adt-installer-tarball'>
+            <title>Getting the ADT Installer Tarball</title>
 
-        <para>
-            Before running the ADT Installer you need to configure it by editing 
-            the <filename>adt-installer.conf</filename> file, which is located in the 
-            directory where the ADT Installer tarball was installed.  
-            Your configurations determine which kernel and filesystem image are downloaded.  
-            The following list describes the variables you can define for the ADT Installer.  
-            For configuration values and restrictions see the comments in  
-            the <filename>adt-installer.conf</filename> file:
-
-            <itemizedlist>
-                <listitem><para><filename>YOCTOADT_IPKG_REPO</filename> – This area 
-                includes the IPKG-based packages and the root filesystem upon which 
-                the installation is based.  
-                If you want to set up your own IPKG repository pointed to by 
-                <filename>YOCTOADT_IPKG_REPO</filename>, you need to be sure that the 
-                directory structure follows the same layout as the reference directory 
-                set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.  
-                Also, your repository needs to be accessible through HTTP.
-                </para></listitem>
-                <listitem><para><filename>YOCTOADT-TARGETS</filename> – The machine 
-                target architectures for which you want to set up cross-development 
-                environments.
-                </para></listitem>
-                <listitem><para><filename>YOCTOADT_QEMU</filename> – Indicates whether 
-                or not to install the emulator QEMU.
-                </para></listitem>
-                <listitem><para><filename>YOCTOADT_NFS_UTIL</filename> – Indicates whether 
-                or not to install user-mode NFS.  
-                If you plan to use the Yocto Eclipse IDE plug-in against QEMU, 
-                you should install NFS.
+            <para>
+                The ADT Installer is contained in the ADT Installer tarball.
+                You can download the tarball into any directory from  
+                <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/adt-installer/'></ulink>.
+                Or, you can use Bitbake to generate the tarball inside the existing Yocto Project build tree.
+            </para>
+
+            <para>
+                If you use Bitbake to generate the ADT Installer tarball, you must 
+                source the Yocto Project environment setup script located in the Yocto Project
+                source directory before running the Bitbake command that creates the tarball.
+            </para>
+
+            <para>
+                The following example commands download the Yocto Project release tarball, create the Yocto 
+                Project source tree, set up the environment while also creating the Yocto Project build tree, 
+                and finally run the Bitbake command that results in the tarball 
+                <filename>~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
+                <literallayout class='monospaced'>
+     $ cd ~
+     $ mkdir yocto-project
+     $ cd yocto-project
+     $ wget http://www.yoctoproject.org/downloads/poky/poky-bernard-5.0.1.tar.bz2
+     $ tar xjf poky-bernard-5.0.1.tar.bz2
+     $ source poky-bernard-5.0.1/poky-init-build-env poky-5.0.1-build
+     $ bitbake adt-installer
+                </literallayout>
+            </para>
+
+        </section>
+
+        <section id='configuring-and-running-the-adt-installer-script'>
+            <title>Configuring and Running the ADT Installer Script</title>
+
+            <para>
+                Before running the ADT Installer script you need to unpack the tarball.
+                You can unpack the tarball in any directory you wish.
+                Unpacking it creates the directory <filename>adt-installer</filename>, 
+                which contains the ADT Installer script and its configuration file.
+            </para>
+
+            <para>
+                Before you run the script, however, you should examine the ADT Installer configuration 
+                file (<filename>adt_installer</filename>) and be sure you are going to get what you want.  
+                Your configurations determine which kernel and filesystem image are downloaded.
+            </para>
+
+            <para>  
+                The following list describes the configurations you can define for the ADT Installer.  
+                For configuration values and restrictions see the comments in  
+                the <filename>adt-installer.conf</filename> file:
+
+                <itemizedlist>
+                    <listitem><para><filename>YOCTOADT_IPKG_REPO</filename> – This area 
+                    includes the IPKG-based packages and the root filesystem upon which 
+                    the installation is based.  
+                    If you want to set up your own IPKG repository pointed to by 
+                    <filename>YOCTOADT_IPKG_REPO</filename>, you need to be sure that the 
+                    directory structure follows the same layout as the reference directory 
+                    set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.  
+                    Also, your repository needs to be accessible through HTTP.
+                    </para></listitem>
+                    <listitem><para><filename>YOCTOADT-TARGETS</filename> – The machine 
+                    target architectures for which you want to set up cross-development 
+                    environments.
+                    </para></listitem>
+                    <listitem><para><filename>YOCTOADT_QEMU</filename> – Indicates whether 
+                    or not to install the emulator QEMU.
+                    </para></listitem>
+                    <listitem><para><filename>YOCTOADT_NFS_UTIL</filename> – Indicates whether 
+                    or not to install user-mode NFS.  
+                    If you plan to use the Yocto Eclipse IDE plug-in against QEMU, 
+                    you should install NFS.
                     <note>
                     To boot QEMU images using our userspace NFS server, you need 
                     to be running portmap or rpcbind. 
@@ -83,112 +168,131 @@
                     Your firewall settings may also have to be modified to allow 
                     NFS booting to work.
                     </note>
-                </para></listitem>
-                <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root 
-                filesystem images you want to download.
-                </para></listitem>
-                <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The 
-                root filesystem used to extract and create the target sysroot.
-                </para></listitem>
-                <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The 
-                location of the target sysroot that will be set up on the development machine.
-                </para></listitem>
-            </itemizedlist>
-        </para>
+                    </para></listitem>
+                    <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root 
+                    filesystem images you want to download.
+                    </para></listitem>
+                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The 
+                    root filesystem used to extract and create the target sysroot.
+                    </para></listitem>
+                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The 
+                    location of the target sysroot that will be set up on the development machine.
+                    </para></listitem>
+                </itemizedlist>
+            </para>
 
-        <para>
-            After you have configured the <filename>adt-installer.conf</filename> file, 
-            run the installer using the following command:
-            <literallayout class='monospaced'>
+            <para>
+                After you have configured the <filename>adt_installer.conf</filename> file, 
+                run the installer using the following command:
+                <literallayout class='monospaced'>
      $ adt_installer
-            </literallayout>
-        </para>
+                </literallayout>
+            </para>
 
-        <para>
-            Once the installer begins to run you are asked whether you want to run in 
-            interactive or silent mode.  
-            If you want to closely monitor the installation then choose “I” for interactive 
-            mode rather than “S” for silent mode.  
-            Follow the prompts from the script to complete the installation.
-        </para>
+            <note>
+                The ADT Installer requires the <filename>libtool</filename> package to complete.  
+                If you install the recommended packages as described in the 
+                <ulink url='http://www.yoctoproject.org/docs/yocto-project-qs/yocto-project-qs.html'>
+                Yocto Project Quick Start</ulink> then you will have libtool installed.
+            </note>
 
-        <para>
-            Once the installation completes, the cross-toolchain is installed in 
-            <filename>/opt/poky/$SDKVERSION</filename>.
-        </para>
+            <para>
+                Once the installer begins to run you are asked whether you want to run in 
+                interactive or silent mode.  
+                If you want to closely monitor the installation then choose “I” for interactive 
+                mode rather than “S” for silent mode.  
+                Follow the prompts from the script to complete the installation.
+            </para>
 
-        <para>
-            Before using the ADT you need to run the environment setup script for 
-            your target architecture also located in <filename>/opt/poky/$SDKVERSION</filename>.
-            See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> 
-            section for information.
-        </para>
+            <para>
+                Once the installation completes, the ADT, which includes the cross-toolchain, is installed.
+                You will notice environment setup files for the cross-toolchain in 
+                <filename>/opt/poky/$SDKVERSION</filename>,
+                and image tarballs in the <filename>adt-installer</filename>
+                directory according to your installer configurations, and the target sysroot located
+                according to the <filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> variable
+                also in your configuration file.
+            </para>
+          
+        </section>
     </section>
 
     <section id='using-an-existing-toolchain-tarball'>
-        <title>Using an Existing Toolchain Tarball</title>
+        <title>Using a Cross-Toolchain Tarball</title>
+        <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 sysroot separately.
+        </para>
+
         <para>
-            If you do not want to use the ADT Installer you can install the toolchain 
-            and the sysroot by hand.  
             Follow these steps:
             <orderedlist>
-                <listitem><para>Locate and download the architecture-specific toolchain 
-                tarball from <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0'></ulink>.
-                Look in the ‘toolchain’ folder and then open up the folder that matches your 
-                host development system (i.e. 'i686' for 32-bit machines or 'x86_64' 
-                for 64-bit machines).  
-                Then, select the toolchain tarball whose name includes the appropriate 
-                target architecture.
+                <listitem><para>Go to  
+                <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/toolchain'></ulink> 
+                and find the folder that matches your host development system 
+                (i.e. 'i686' for 32-bit machines or 'x86_64' for 64-bit machines).</para>
+                </listitem>
+                <listitem><para>Go into that folder and download the toolchain tarball whose name 
+                includes the appropriate target architecture.
+                For example, if your host development system is an Intel-based 64-bit system and 
+                you are going to use your cross-toolchain for an arm target go into the 
+                <filename>x86_64</filename> folder and download the following tarball:
+                <literallayout class='monospaced'>
+     yocto-eglibc-x86_64-arm-toolchain-gmae-1.0.tar.bz2
+                </literallayout>
                 <note>
-                    If you need to build the toolchain tarball use the 
-                    <filename>bitbake meta-toolchain</filename> command after you have 
-                    sourced the poky-build-init script.  
-                    The tarball will be located in the build directory at 
-                    <filename>tmp/deploy/sdk</filename> after the build.
-                </note>
-                </para></listitem>
+                Alternatively 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 
+                sourced the <filename>poky-build-init script</filename> located in the Yocto Project 
+                source directory.  
+                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>
                 <listitem><para>Make sure you are in the root directory and then expand 
                 the tarball.  
-                The tarball expands into the <filename>/opt/poky/$SDKVERSION</filename> directory.
-                </para></listitem>
-                <listitem><para>Set up the environment by sourcing the environment set up 
-                script.  
-                See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
-                for information.
+                The tarball expands into <filename>/opt/poky/$SDKVERSION</filename>.
+                Once the tarball in unpacked the cross-toolchain is installed.
+                You will notice environment setup files for the cross-toolchain in the directory.
                 </para></listitem>
             </orderedlist>
         </para>
     </section>
 
     <section id='using-the-toolchain-from-within-the-build-tree'>
-        <title>Using the Toolchain from Within the Build Tree</title>
-        <para>
-            A final way of accessing the toolchain is from the build tree.  
-            The build tree can be set up to contain the architecture-specific cross toolchain.  
-            To populate the build tree with the toolchain you need to run the following command:
-            <literallayout class='monospaced'>  
-     $ bitbake meta-ide-support
-            </literallayout>
-        </para>
- 
-        <para>
-            Before running the command you need to be sure that the 
-            <filename>conf/local.conf</filename> file in the build directory has 
-            the desired architecture specified for the <filename>MACHINE</filename> 
-            variable.
-            See the <filename>local.conf</filename> file for a list of values you 
-            can supply for this variable.  
-            You can populate the build tree with the cross-toolchains for more 
-            than a single architecture.  
-            You just need to edit the <filename>local.conf</filename> file and re-run 
-            the BitBake command.
-        </para>
-
+        <title>Using Bitbake and the Yocto Project Build Tree</title>
         <para>
-            Once the build tree has the toolchain you need to source the environment 
-            setup script so that you can run the cross-tools without having to locate them.  
-            See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
-            for information.
+            A final way of installing just the cross-toolchain is to use Bitbake within an existing 
+            Yocto Project build tree.
+            Follow these steps:
+            <orderedlist>
+                <listitem><para>Source the environment setup script located in the Yocto Project
+                source directory.
+                The script has the string <filename>init-build-env</filename>
+                as part of the name.</para></listitem> 
+                <listitem><para>At this point you should be sure that the 
+                <filename>MACHINE</filename> variable 
+                in the <filename>local.conf</filename> file is set for the target architecture.
+                You can find the <filename>local.conf</filename> file in the Yocto Project source
+                directory.
+                Comments within the <filename>local.conf</filename> file list the values you 
+                can use for the <filename>MACHINE</filename> variable.  
+                <note>You can populate the build tree with the cross-toolchains for more 
+                than a single architecture.  
+                You just need to edit the <filename>MACHINE</filename> variable in the 
+                <filename>local.conf</filename> file and re-run the BitBake command.</note></para></listitem>
+                <listitem><para>Run <filename>bitbake meta-ide-support</filename> to complete the 
+                cross-toolchain installation.
+                <note>If you change your working directory after you source the environment 
+                setup script and before you run the Bitbake command the command will not work. 
+                Be sure to run the Bitbake 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.
+                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>
     </section>
 </section>
@@ -196,7 +300,7 @@
 <section id='setting-up-the-environment'>
     <title>Setting Up the Environment</title>
     <para>
-        Before you can use the cross-toolchain you need to set up the environment by 
+        Before you can use the cross-toolchain you need to set up the toolchain environment by 
         sourcing the environment setup script.  
         If you used 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>