documentation/yocto-project-qs/yocto-project-qs.xml: Robert P. J. Day Review

As Reported By:  Robert P. J. Day.

Community member Robert P. J. Day scrubbed the Quick Start manual for Release
1.1.  He found several areas that were incorrect.  Many items were documented
pre-release and changed during the actual realeas.  Naming conventions for
images and such had to be changed.  Robert also found and suggested several
wording changes that resulted in clearer text.

I was not able to patch all the changes using the 'patch' command.  I need to
work out some process issues still in order to apply patches directly to the
yocto-docs repository.  Meanwhile, I hand-inserted the changes.  Also, some
text changes were modified slightly by me to conform to the books style, etc.

Kudos to Robert for such a detailed look at the YP Quick Start.

(From yocto-docs rev: 6bc2e9c289a802f511441ca5b31ca6163e4fdfac)

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

1 files changed, 35 insertions, 45 deletions

diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index daa1f0efb1..3003f06cd0 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -149,7 +149,7 @@
             The Yocto Project team is continually verifying more and more Linux 
             distributions with each release.
             In general, if you have the current release minus one of the following 
-            distributions you should no problems.
+            distributions you should have no problems.
             <itemizedlist>
                 <listitem><para>Ubuntu</para></listitem>
                 <listitem><para>Fedora</para></listitem>
@@ -278,7 +278,7 @@
             <para>Build an image and run it in the QEMU emulator</para>
         </listitem>
         <listitem>
-            <para>Or, use a pre-built image and run it in the QEMU emulator</para>
+            <para>Use a pre-built image and run it in the QEMU emulator</para>
         </listitem>
     </itemizedlist>
 
@@ -331,9 +331,8 @@
 
          <tip><para>
              To help conserve disk space during builds, you can add the following statement
-             to your <filename>local.conf</filename> file in the Yocto Project build
-             directory, which for this example 
-             is <filename>edison-6.0-build</filename>.
+             to your project's configuration file, which for this example
+             is <filename>edison-6.0-build/conf/local.conf</filename>.
              Adding this statement deletes the work directory used for building a package
              once the package is built.
              <literallayout class='monospaced'>
@@ -342,16 +341,15 @@
          </para></tip>
 
          <itemizedlist>
-             <listitem><para>The first command retrieves the Yocto Project release tarball from the 
-                 source repositories. 
-                 Notice, the example uses the <filename>wget</filename> shell command.
+             <listitem><para>In the previous example, the first command retrieves the Yocto Project
+                 release tarball from the source repositories using the
+                 <filename>wget</filename> command.
                  Alternatively, you can go to the 
-                 <ulink url='http://www.yoctoproject.org'>Yocto Project website</ulink> downloads
-                 area to retrieve the tarball.</para></listitem>
+                 <ulink url='http://www.yoctoproject.org/download'>Yocto Project website</ulink>
+                 Downloads page to retrieve the tarball.</para></listitem>
              <listitem><para>The second command extracts the files from the tarball and places 
                  them into a directory named <filename>poky-edison-6.0</filename> in the current 
-                 directory. 
-               </para></listitem>
+                 directory.</para></listitem>
              <listitem><para>The third command runs the Yocto Project environment setup script.
                  Running this script defines Yocto Project build environment settings needed to 
                  complete the build.
@@ -364,19 +362,18 @@
                  </para></listitem>
          </itemizedlist>
          <para>
-             Take some time to examine your <filename>conf/local.conf</filename> file found in the
-             Yocto Project build directory.
-             The defaults in the <filename>local.conf</filename> should work fine.
+             Take some time to examine your <filename>local.conf</filename> file 
+             in your project's configuration directory.
+             The defaults in that file should work fine.
              However, there are some variables of interest at which you might look.
          </para>
 
          <para>  
              By default, the target architecture for the build is <filename>qemux86</filename>, 
-             which is an image that can be used in the QEMU emulator and is targeted for an
+             which produces an image that can be used in the QEMU emulator and is targeted at an
              <trademark class='registered'>Intel</trademark> 32-bit based architecture.
-             To change this default, edit the value of the <filename>MACHINE</filename> variable in the 
-             <filename>conf/local.conf</filename> file in the build directory before 
-             launching the build.
+             To change this default, edit the value of the <filename>MACHINE</filename> variable 
+             in the configuration file before launching the build.
          </para>
 
          <para>
@@ -384,12 +381,12 @@
              <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink> and the 
              <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> variables.
              By default, these variables are commented out. 
-             However, if you have a multi-core CPU you might want to remove the comment
-             and set the variable
+             However, if you have a multi-core CPU you might want to uncomment
+             the lines and set the variable
              <filename>BB_NUMBER_THREADS</filename> equal to twice the number of your 
              host's processor cores.
-             Also, you could set the variable <filename>PARALLEL_MAKE</filename> equal to the number 
-             of processor cores.
+             Also, you could set the variable <filename>PARALLEL_MAKE</filename> equal to 
+             1.5 times the number of processor cores.
              Setting these variables can significantly shorten your build time.
          </para>
 
@@ -471,10 +468,10 @@
             <title>Installing the Toolchain</title>
             <para>
                 You can download the pre-built toolchain, which includes the <filename>runqemu</filename> 
-                script and support files, from 
-                <ulink url='http://yoctoproject.org/downloads/yocto-1.1/toolchain/'></ulink>.  
+                script and support files, from the appropriate directory under
+                <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-1.1/toolchain/'></ulink>.  
                 Toolchains are available for 32-bit and 64-bit development systems from the 
-                <filename>i686</filename> and <filename>x86_64</filename> folders, respectively. 
+                <filename>i686</filename> and <filename>x86_64</filename> directories, respectively. 
                 Each type of development system supports five target architectures.
                 The tarball files are named such that a string representing the host system appears 
                 first in the filename and then is immediately followed by a string representing
@@ -482,7 +479,7 @@
             </para>
 
             <literallayout class='monospaced'>
-     yocto-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;.tar.bz2
 
      Where:
          &lt;<emphasis>host_system</emphasis>&gt; is a string representing your development system: 
@@ -500,7 +497,7 @@
             </para>
 
             <literallayout class='monospaced'>
-     yocto-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2
+     poky-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2
             </literallayout>
 
             <para>
@@ -513,7 +510,7 @@
             <para>
                 <literallayout class='monospaced'>
      $ cd /
-     $ sudo tar -xvjf ~/toolchains/yocto-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2
+     $ sudo tar -xvjf ~/toolchains/poky-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2
                 </literallayout>
             </para>
 
@@ -522,7 +519,7 @@
                 "<ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and 
                 "<ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Yocto Project Build Tree</ulink>" sections in  
                 <ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html'>The Yocto Project 
-                Application Development Toolkit (ADT) Development Manual</ulink>.
+                Application Development Toolkit (ADT) User's Guide</ulink>.
             </para>
         </section>
 
@@ -531,7 +528,7 @@
       
             <para>
                 You can download the pre-built Linux kernel suitable for running in the QEMU emulator from 
-                <ulink url='http://yoctoproject.org/downloads/yocto-1.1/machines/qemu'></ulink>.
+                <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-1.1/machines/qemu'></ulink>.
                 Be sure to use the kernel that matches the architecture you want to simulate.
                 Download areas exist for the five supported machine architectures:
                 <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
@@ -541,17 +538,12 @@
             <para>  
                 Most kernel files have one of the following forms:
                 <literallayout class='monospaced'>
-     *zImage-&lt;<emphasis>kernel-rev</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;*.bin
-     vmlinux-&lt;<emphasis>kernel-rev</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;*.bin
+     *zImage-qemu&lt;<emphasis>arch</emphasis>&gt;.bin
+     vmlinux-qemu&lt;<emphasis>arch</emphasis>&gt;.bin
 
      Where:
-         &lt;<emphasis>kernel-rev</emphasis>&gt; is the base Linux kernel revision 
-                (e.g. 2.6.37).
-
          &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture: 
                 x86, x86-64, ppc, mips, or arm.
-
-         &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project. 
                 </literallayout>
             </para>
 
@@ -568,7 +560,7 @@
 
             <para>
                 You can also download the filesystem image suitable for your target architecture from
-                <ulink url='http://yoctoproject.org/downloads/yocto-1.1/machines/qemu'></ulink>.
+                <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-1.1/machines/qemu'></ulink>.
                 Again, be sure to use the filesystem that matches the architecture you want 
                 to simulate.
             </para>
@@ -581,19 +573,17 @@
                 The <filename>tar</filename> form can be flattened out in your host development system
                 and used for Yocto Project build purposes.
                 <literallayout class='monospaced'>
-     yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;.rootfs.ext3.bz2
-     yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;.rootfs.tar.bz2
+     core-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.ext3
+     core-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.tar.bz2
 
      Where:
          &lt;<emphasis>profile</emphasis>&gt; is the filesystem image's profile:
-                   lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, sato, sato-dev, or sato-sdk.
+                   lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, sato-dev, or sato-sdk.
                    For information on these types of image profiles, see
                    <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink> in the Yocto Project Reference Manual.
 
          &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture: 
                 x86, x86-64, ppc, mips, or arm.
-
-         &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project. 
                 </literallayout>
             </para>
         </section>
@@ -640,7 +630,7 @@
                 <literallayout class='monospaced'>
      $ source /opt/poky/1.1/environment-setup-i686-poky-linux 
      $ runqemu qemux86 bzImage-3.0-qemux86-1.1.bin \
-     yocto-image-sato-qemux86-1.1.rootfs.ext3
+     core-image-sato-qemux86.ext3
                 </literallayout>
             </para>