documentation: Toolchain corrections from tarball to .sh file

For 1.3 there is not longer a toolchain tarball.  Instead, there
is a wrapper script that lets you install the tarball.  This
fundamental usage model change caused several ripples throughout
the documentation set.  I have changed wordings and examples
to reflect the new paradigm.

(From yocto-docs rev: afb2069daa91e04c0f78ba425a6b184cb820d888)

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

8 files changed, 70 insertions, 46 deletions

diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml
index f5ed906962..074e51c1f1 100644
--- a/documentation/adt-manual/adt-command.xml
+++ b/documentation/adt-manual/adt-command.xml
@@ -32,7 +32,7 @@
         For an Autotools-based project, you can use the cross-toolchain by just 
         passing the appropriate host option to <filename>configure.sh</filename>.
         The host option you use is derived from the name of the environment setup 
-        script in <filename>/opt/poky</filename> resulting from unpacking the 
+        script in <filename>/opt/poky</filename> resulting from installation of the 
         cross-toolchain tarball.
         For example, the host option for an ARM-based target that uses the GNU EABI 
         is <filename>armv5te-poky-linux-gnueabi</filename>.
diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml
index 47e4c3685e..c83880b2d6 100644
--- a/documentation/adt-manual/adt-intro.xml
+++ b/documentation/adt-manual/adt-intro.xml
@@ -54,8 +54,8 @@
         <para>
             The cross-toolchain consists of a cross-compiler, cross-linker, and cross-debugger 
             that are used to develop user-space applications for targeted hardware.
-            This toolchain is created either by running the ADT Installer script or 
-            through a build directory that is based on your metadata 
+            This toolchain is created either by running the ADT Installer script, a toolchain installer
+            script, or through a build directory that is based on your metadata 
             configuration or extension for your targeted device.  
             The cross-toolchain works with a matching target sysroot.
         </para>
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index e512c89a1c..0b74505d7e 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -29,8 +29,7 @@
     <note>
         <para>Avoid mixing installation methods when installing toolchains for different architectures.
         For example, avoid using the ADT Installer to install some toolchains and then hand-installing
-        cross-development toolchains from downloaded tarballs to install toolchains
-        for different architectures. 
+        cross-development toolchains by running the toolchain installer for different architectures. 
         Mixing installation methods can result in situations where the ADT Installer becomes
         unreliable and might not install the toolchain.</para>
         <para>If you must mix installation methods, you might avoid problems by deleting 
@@ -46,9 +45,9 @@
                 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>
+            <listitem><para><emphasis>Use an Existing Toolchain:</emphasis>
                 Using this method, you select and download an architecture-specific
-                toolchain tarball and then hand-install the toolchain.
+                toolchain installer and then run the script to 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 the Build Directory:</emphasis>
@@ -226,8 +225,8 @@
         <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 want to simply install the cross-toolchain by hand, you can do so by running the 
+            toolchain installer.  
             If you use this method to install the cross-toolchain and you still need to install the target 
             sysroot, you will have to extract and install sysroot separately.
             For information on how to do this, see the 
@@ -242,30 +241,41 @@
                     and find the folder that matches your host development system 
                     (i.e. <filename>i686</filename> for 32-bit machines or 
                     <filename>x86-64</filename> for 64-bit machines).</para></listitem>
-                <listitem><para>Go into that folder and download the toolchain tarball whose name 
+                <listitem><para>Go into that folder and download the toolchain installer 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 Intel-based 32-bit target, go into the 
-                    <filename>x86_64</filename> folder and download the following tarball:
+                    <filename>x86_64</filename> folder and download the following installer:
                     <literallayout class='monospaced'>
-     poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.tar.bz2
+     poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.sh
                     </literallayout>
-                    <note><para>As an alternative to steps one and two, you can build the toolchain tarball 
+                    <note><para>As an alternative to steps one and two, you can build the toolchain installer 
                         if you have a <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
                         If you need GMAE, you should use the <filename>bitbake meta-toolchain-gmae</filename>
                         command. 
-                        The resulting tarball will support such development.
+                        The resulting installation script when run will support such development.
                         However, if you are not concerned with GMAE, 
-                        you can generate the tarball using <filename>bitbake meta-toolchain</filename>.</para>
+                        you can generate the toolchain installer 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-env</filename> script located in the source
                         directory.  
-                        When the <filename>bitbake</filename> command completes, the tarball will 
+                        When the <filename>bitbake</filename> command completes, the toolchain installer will 
                         be in <filename>tmp/deploy/sdk</filename> in the build directory.
-                        </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>&YOCTO_ADTPATH_DIR;</filename>.
+                        </para></note>
+                    </para></listitem>
+                <listitem><para>Once you have the installer, run it to install the toolchain. 
+                    The following command shows how to run the installer given a toolchain tarball 
+                    for a 64-bit development host system and a 32-bit target architecture.
+                    The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
+                    <literallayout class='monospaced'>
+     $ ~/Downloads/poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.sh
+                    </literallayout>
+                    <note>
+                        If you do not have write permissions for the directory into which you are installing 
+                        the toolchain, the toolchain installer notifies you and exits.  
+                        Be sure you have write permissions in the directory and run the installer again.
+                    </note>
                     Once the tarball is expanded, the cross-toolchain is installed.
                     You will notice environment setup files for the cross-toolchain in the directory.
                     </para></listitem>
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 5f3b67de24..4bdb91208c 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1066,10 +1066,17 @@
                                 Developer's Guide for information on how to install the toolchain into the build 
 directory.</para></listitem> 
                             <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
-                                This location is where the root filesystem for the 
-                                target hardware is created on the development system by the ADT Installer.
-                                The QEMU user-space tools, the 
-                                NFS boot process, and the cross-toolchain all use the sysroot location.
+                                This location is where the root filesystem for the target hardware resides. 
+                                If you used the ADT Installer, then the location is 
+                                <filename>/opt/poky/&lt;release&gt;</filename>.
+                                Additionally, when you use the ADT Installer, the same location is used for 
+                                the QEMU user-space tools and the NFS boot process.</para>
+                                <para>If you used either of the other two methods to install the toolchain, then the 
+                                location of the sysroot filesystem depends on where you separately
+                                extracted and intalled the filesystem.</para>
+                                <para>For information on how to install the toolchain and on how to extract 
+                                and install the sysroot filesystem, see the
+                                "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" section.
                                 </para></listitem>
                             <listitem><para><emphasis>Select the Target Architecture:</emphasis>
                                 The target architecture is the type of hardware you are 
@@ -1273,7 +1280,7 @@ directory.</para></listitem>
                         <filename>New Connections</filename> Dialog.</para></listitem>
                     <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick 
                         the IP Address you entered.</para></listitem>
-                    <listitem><para>Click <filename>Debug</filename> to bring up a login screen 
+                    <listitem><para>Click <filename>Run</filename> to bring up a login screen 
                         and login.</para></listitem>
                     <listitem><para>Accept the debug perspective.</para></listitem>
                 </orderedlist>
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 9a78d40bb2..3d1983e574 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -170,7 +170,7 @@
             <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
                 This area contains index releases such as 
                 the <trademark class='trade'>Eclipse</trademark>
-                Yocto Plug-in, miscellaneous support, poky, pseudo, cross-development toolchains,
+                Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains,
                 and all released versions of Yocto Project in the form of images or tarballs.
                 Downloading and extracting these files does not produce a local copy of the 
                 Git repository but rather a snapshot of a particular release or image.</para>
@@ -283,11 +283,11 @@
                 tools and utilities that allow you to develop software for targeted architectures.
                 This toolchain contains cross-compilers, linkers, and debuggers that are specific to 
                 an architecture.
-                You can use the OpenEmbedded build system to build cross-development toolchains in tarball 
-                form that, when
-                unpacked, contain the development tools you need to cross-compile and test your software.
-                The Yocto Project ships with images that contain toolchains for supported architectures
-                as well.
+                You can use the OpenEmbedded build system to build a cross-development toolchain
+                installer that when run installs the toolchain that contains the development tools you 
+                need to cross-compile and test your software.
+                The Yocto Project ships with images that contain installers for 
+                toolchains for supported architectures as well.
                 Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem>
             <listitem><para><emphasis>Image:</emphasis> An image is the result produced when 
                 BitBake processes a given collection of recipes and related metadata.
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 3209cb29b7..6e204d85e0 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -313,9 +313,9 @@
         Regardless of the type of image you are using, you need to download the pre-built kernel 
         that you will boot in the QEMU emulator and then download and extract the target root 
         filesystem for your target machine’s architecture.
-        You can get architecture-specific binaries and filesystem from
+        You can get architecture-specific binaries and filesystems from
         <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
-        You can get stand-alone toolchains from
+        You can get installation scripts for stand-alone toolchains from
         <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
         Once you have all your files, you set up the environment to emulate the hardware 
         by sourcing an environment setup script. 
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml
index 8713239442..71717e3d77 100644
--- a/documentation/poky-ref-manual/introduction.xml
+++ b/documentation/poky-ref-manual/introduction.xml
@@ -103,7 +103,7 @@
                 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
             <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at
                 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.  
-                These builds include Yocto Project releases, meta-toolchain tarballs, and 
+                These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and 
                 experimental builds.</para></listitem>
             <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases
                 of the Yocto Project and supported BSPs at the
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index 83c204b0af..b37a45f337 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -526,9 +526,9 @@
         <section id='installing-the-toolchain'>
             <title>Installing the Toolchain</title>
             <para>
-                You can download a tarball with the pre-built toolchain, which includes the 
+                You can download a tarball installer, which includes the pre-built toolchain, the 
                 <filename>runqemu</filename> 
-                script and support files, from the appropriate directory under
+                script, and support files from the appropriate directory under
                 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.  
                 Toolchains are available for 32-bit and 64-bit development systems from the 
                 <filename>i686</filename> and <filename>x86-64</filename> directories, respectively. 
@@ -539,7 +539,7 @@
             </para>
 
             <literallayout class='monospaced'>
-     poky-eglibc-&lt;<emphasis>host_system</emphasis>&gt;-&lt;<emphasis>arch</emphasis>&gt;-toolchain-gmae-&lt;<emphasis>release</emphasis>&gt;.tar.bz2
+     poky-eglibc-&lt;<emphasis>host_system</emphasis>&gt;-&lt;<emphasis>arch</emphasis>&gt;-toolchain-gmae-&lt;<emphasis>release</emphasis>&gt;.sh
 
      Where:
          &lt;<emphasis>host_system</emphasis>&gt; is a string representing your development system: 
@@ -552,26 +552,33 @@
             </literallayout>
 
             <para>       
-                For example, the following toolchain tarball is for a 64-bit development 
+                For example, the following toolchain installer is for a 64-bit development 
                 host system and a 32-bit target architecture:
             </para>
 
             <literallayout class='monospaced'>
-     poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.tar.bz2
+     poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.sh
             </literallayout>
 
             <para>
-                The toolchain tarballs are self-contained and must be installed into <filename>/opt/poky</filename>.
-                The following commands show how you install the toolchain tarball given a 64-bit development 
-                host system and a 32-bit target architecture.
-                The example assumes the toolchain tarball is located in <filename>~/toolchains/</filename>.
-                You must have your working directory set to root before unpacking the tarball:
+                Toolchains are self-contained and by default are installed into <filename>/opt/poky</filename>.
+                However, when you run the toolchain installer, you can choose an installation directory.
+            </para>
+
+            <para>
+                The following command shows how to run the installer given a toolchain tarball 
+                for a 64-bit development host system and a 32-bit target architecture.
+                The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
+                <note>
+                    If you do not have write permissions for the directory into which you are installing 
+                    the toolchain, the toolchain installer notifies you and exits.  
+                    Be sure you have write permissions in the directory and run the installer again.
+                </note>
             </para>
 
             <para>
                 <literallayout class='monospaced'>
-     $ cd /
-     $ sudo tar -xvjf ~/toolchains/poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.tar.bz2
+     $ ~/Downloads/poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.sh
                 </literallayout>
             </para>