ref-manual, yocto-project-qs: Notes and infor for buildtools issues

Fixes [YOCTO #4866]

Updated the main area where it talks about needing the right
versions of Git, tar, and Python.  You can get this set up using a
couple methods.  I documented both.

The changes in the FAQ and in the QS are basically notes that point
to that section for more information.

(From yocto-docs rev: 1b64c7c271303ecf10ec85c8a2cd5a0d909f1151)

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

3 files changed, 143 insertions, 61 deletions

diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
index ff695ba721..035011f342 100644
--- a/documentation/ref-manual/faq.xml
+++ b/documentation/ref-manual/faq.xml
@@ -30,9 +30,12 @@
 
     <qandaentry>
         <question>
-            <para>
-                My development system does not have Python 2.7.3 or greater,
-                which the Yocto Project requires.
+            <para id='faq-not-meeting-requirements'>
+                My development system does not meet the
+                required Git, tar, and Python versions.
+                In particular, I do not have Python 2.7.3 or greater, or
+                I do have Python 3.x, which is specifically not supported by
+                the Yocto Project.
                 Can I still use the Yocto Project?
             </para>
         </question>
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index 47f736285c..7eb8203bc2 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -338,63 +338,142 @@
 
         <para>
             If your host development system does not meet all these requirements,
-            you can resolve this by either downloading a pre-built tarball
-            containing these tools, or building such a tarball on another
-            system.
-            Regardless of the method, once you have the tarball, you simply
-            install it somewhere on your system, such as a directory in your
-            home directory, and then source the environment script provided,
-            which adds the tools into <filename>PATH</filename> and sets
-            any other environment variables required to run the tools.
-            Doing so gives you working versions of Git, tar, Python and
-            <filename>chrpath</filename>.
+            you can resolve this by installing a <filename>buildtools</filename>
+            tarball that contains these tools.
+            You can get the tarball one of two ways: download a pre-built
+            tarball or use BitBake to build the tarball.
         </para>
 
-        <para>
-            If downloading a pre-built tarball, locate the
-            <filename>*.sh</filename> at
-            <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
-        </para>
+        <section id='downloading-a-pre-built-buildtools-tarball'>
+            <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
 
-        <para>
-            If building your own tarball, do so using this command:
-            <literallayout class='monospaced'>
-     $ bitbake buildtools-tarball
-            </literallayout>
-            <note>
-                The <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
-                variable determines whether you build tools for a 32-bit
-                or 64-bit system.
-            </note>
-            Once the build completes, you can find the file that installs
-            the tools in the <filename>tmp/deploy/sdk</filename> subdirectory
-            of the
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
-            The file used to install the tarball has the string "buildtools"
-            in the name.
-        </para>
+            <para>
+                Downloading and running a pre-built buildtools installer is
+                the easiest of the two methods by which you can get these tools:
+                <orderedlist>
+                    <listitem><para>
+                        Locate and download the <filename>*.sh</filename> at
+                        <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
+                        </para></listitem>
+                    <listitem><para>
+                        Execute the installation script.
+                        Here is an example:
+                        <literallayout class='monospaced'>
+     $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
+                        </literallayout>
+                        During execution, a prompt appears that allows you to
+                        choose the installation directory.
+                        For example, you could choose the following:
+                        <literallayout class='monospaced'>
+     /home/your-username/buildtools
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        Source the tools environment setup script by using a
+                        command like the following:
+                        <literallayout class='monospaced'>
+     $ source /home/your-username/buildtools/environment-setup-i586-poky-linux
+                        </literallayout>
+                        Of course, you need to supply your installation directory and be
+                        sure to use the right file (i.e. i585 or x86-64).
+                        </para>
+                        <para>
+                        After you have sourced the setup script,
+                        the tools are added to <filename>PATH</filename>
+                        and any other environment variables required to run the
+                        tools are initialized.
+                        The results are working versions versions of Git, tar,
+                        Python and <filename>chrpath</filename>.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
 
-        <para>
-            After you have either built the tarball or downloaded it, you need
-            to install it.
-            Install the tools by executing the <filename>*.sh</filename> file.
-            During execution, a prompt appears that allows you to choose the
-            installation directory.
-            For example, you could choose the following:
-            <literallayout class='monospaced'>
-     /home/your-username/sdk
-            </literallayout>
-        </para>
+        <section id='building-your-own-buildtools-tarball'>
+            <title>Building Your Own <filename>buildtools</filename> Tarball</title>
 
-        <para>
-            The final step before you can actually use the tools is to source
-            the tools environment with a command like the following:
-            <literallayout class='monospaced'>
-     $ source /home/your-username/sdk/environment-setup-i586-poky-linux
-            </literallayout>
-            Of course, you need to supply your installation directory and be
-            sure to use the right file (i.e. i585 or x86-64).
-        </para>
+            <para>
+                Building and running your own buildtools installer applies
+                only when you have a build host that can already run BitBake.
+                In this case, you use that machine to build the
+                <filename>.sh</filename> file and then
+                take steps to transfer and run it on a
+                machine that does not meet the minimal Git, tar, and Python
+                requirements.
+            </para>
+
+            <para>
+                Here are the steps to take to build and run your own
+                buildtools installer:
+                <orderedlist>
+                    <listitem><para>
+                        On the machine that is able to run BitBake,
+                        be sure you have set up your build environment with
+                        the setup script
+                        (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+                        or
+                        <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+                        </para></listitem>
+                    <listitem><para>
+                        Run the BitBake command to build the tarball:
+                        <literallayout class='monospaced'>
+     $ bitbake buildtools-tarball
+                        </literallayout>
+                        <note>
+                        The
+                        <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
+                        variable in your <filename>local.conf</filename> file
+                        determines whether you build tools for a 32-bit
+                        or 64-bit system.
+                       </note>
+                       Once the build completes, you can find the
+                       <filename>.sh</filename> file that installs
+                       the tools in the <filename>tmp/deploy/sdk</filename>
+                       subdirectory of the
+                       <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                       The installer file has the string "buildtools"
+                       in the name.
+                       </para></listitem>
+                   <listitem><para>
+                       Transfer the <filename>.sh</filename> file from the
+                       build host to the machine that does not meet the
+                       Git, tar, or Python requirements.
+                       </para></listitem>
+                   <listitem><para>
+                       On the machine that does not meet the requirements,
+                       run the <filename>.sh</filename> file
+                       to install the tools.
+                       Here is an example:
+                       <literallayout class='monospaced'>
+     $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
+                       </literallayout>
+                       During execution, a prompt appears that allows you to
+                       choose the installation directory.
+                       For example, you could choose the following:
+                       <literallayout class='monospaced'>
+     /home/your-username/buildtools
+                       </literallayout>
+                       </para></listitem>
+                    <listitem><para>
+                        Source the tools environment setup script by using a
+                        command like the following:
+                        <literallayout class='monospaced'>
+     $ source /home/your-username/buildtools/environment-setup-i586-poky-linux
+                        </literallayout>
+                        Of course, you need to supply your installation directory and be
+                        sure to use the right file (i.e. i585 or x86-64).
+                        </para>
+                        <para>
+                        After you have sourced the setup script,
+                        the tools are added to <filename>PATH</filename>
+                        and any other environment variables required to run the
+                        tools are initialized.
+                        The results are working versions versions of Git, tar,
+                        Python and <filename>chrpath</filename>.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
     </section>
 </section>
 
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index d86518ea09..393da9529f 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -533,12 +533,12 @@
              <literallayout class='monospaced'>
      $ bitbake -k core-image-sato
              </literallayout>
-             <note><para>
-                 BitBake requires Python 2.6 or 2.7.  For more information on this requirement,
-                 see the
-                 <ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink> in the Yocto Project Reference
-                 Manual.
-             </para></note>
+             <note>
+                 BitBake requires Python 2.6 or 2.7.  For more information on
+                 this requirement, see the
+                 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python</ulink>"
+                 section in the Yocto Project Reference Manual.
+             </note>
              The final command runs the image:
              <literallayout class='monospaced'>
      $ runqemu qemux86