documentation/poky-ref-manual/usingpoky.xml: re-write for Yocto

General re-write to make the chapter Yocto Project friendly.
Weeded out the references to "Poky."

(From yocto-docs rev: ac4fc6082f458e5ee60962693ee332bbf1e3c1a9)

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

1 files changed, 143 insertions, 104 deletions

diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index b07ec70fac..ed30d8df51 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -4,16 +4,17 @@
 <title>Using Poky</title>
 
     <para>
-        This section gives an overview of the components that make up Poky 
-        followed by information about running poky builds and dealing with any
-        problems that may arise.
+        This section gives an overview of the components that make up the Yocto Project 
+        followed by information about Yocto Project builds and dealing with any
+        problems that might arise.
     </para>
 
 <section id='usingpoky-components'>
     <title>Poky Overview</title>
 
     <para>
-        The BitBake task executor together with various types of configuration files form the core of Poky.
+        The BitBake task executor together with various types of configuration files form the 
+        Yocto Project core.
         This section overviews the BitBake task executor and the
         configuration files by describing what they are used for and they they interact.
     </para>
@@ -28,6 +29,11 @@
         <listitem><para>Configuration Data:  Defines machine-specific settings, policy decisions, etc.
           Configuration data acts a the glue to bind everything together.</para></listitem>
     </itemizedlist>
+        For more information on data, see the
+        <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#yocto-project-terms'>
+        Yocto Project Terms</ulink> section in 
+        <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>
+        The Yocto Project Development Manual</ulink>.
     </para>
 
     <para> 
@@ -46,16 +52,19 @@
         <title>BitBake</title>
 
         <para>
-            BitBake is the tool at the heart of Poky and is responsible
-            for parsing the metadata, generating a list of tasks from it
-            and then executing them. To see a list of the options BitBake
-            supports look at 'bitbake --help'.
+            BitBake is the tool at the heart of the Yocto Project and is responsible
+            for parsing the metadata, generating a list of tasks from it,
+            and then executing those tasks. 
+            To see a list of the options BitBake supports, use the following help command:
+            <literallayout class='monospaced'>
+     $ bitbake --help
+            </literallayout>
         </para>
 
         <para>
             The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where
-            packagename is the name of the package you want to build (referred to as the 'target'
-            in this manual). 
+            <filename>packagename</filename> is the name of the package you want to build 
+            (referred to as the "target" in this manual). 
             The target often equates to the first part of a <filename>.bb</filename> filename.
             So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
             might type the following:
@@ -64,43 +73,46 @@
             </literallayout>
             Several different versions of <filename>matchbox-desktop</filename> might exist.
             BitBake chooses the one selected by the distribution configuration.
-            You can get more details about how BitBake chooses between different versions
-            and providers in the <link linkend='ref-bitbake-providers'>
-            'Preferences and Providers'</link> section.
+            You can get more details about how BitBake chooses between different 
+            target versions and providers in the 
+            <link linkend='ref-bitbake-providers'>Preferences and Providers</link> section.
         </para>
+
         <para>
             BitBake also tries to execute any dependent tasks first.
-            So for example, before building <filename>matchbox-desktop</filename> BitBake
-            would build a cross compiler and glibc if they had not already been built.
+            So for example, before building <filename>matchbox-desktop</filename>, BitBake
+            would build a cross compiler and <filename>glibc</filename> if they had not already 
+            been built.
         </para>
+
         <para>
             A useful BitBake option to consider is the <filename>-k</filename> or 
             <filename>--continue</filename> option.  
             This option instructs BitBake to try and continue processing the job as much 
-            as possible even after encountering an error.  When an error occurs the target that
-            failed and those that depend on it cannot be remade.  However, when you use this
-            option other dependencies can still be processed.
+            as possible even after encountering an error.  
+            When an error occurs, the target that
+            failed and those that depend on it cannot be remade.  
+            However, when you use this option other dependencies can still be processed.
         </para>
-
     </section>
 
     <section id='usingpoky-components-metadata'>
         <title>Metadata (Recipes)</title>
 
         <para>
-            The <filename>.bb</filename> files are usually referred to as 'recipes'. 
-            In general, a recipe contains information about a single piece of software such
-            as from where to download the source patches (if any are needed), which special 
-            configuration options to apply, how to compile the source files, and how to 
-            package the compiled output. 
+            The <filename>.bb</filename> files are usually referred to as "recipes." 
+            In general, a recipe contains information about a single piece of software.
+            The information includes the location from which to download the source patches 
+            (if any are needed), which special configuration options to apply, 
+            how to compile the source files, and how to package the compiled output. 
         </para>
 
         <para>
-            The term 'package' can also be used to describe recipes.
-            However, since the same word is used for the packaged output from Poky (i.e. .ipk or .deb
-            files), this document avoids it.
+            The term "package" can also be used to describe recipes.
+            However, since the same word is used for the packaged output from the Yocto 
+            Project (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files), 
+            this document avoids using the term "package" to refer to recipes.
         </para>
-
     </section>
 
     <section id='usingpoky-components-classes'>
@@ -109,8 +121,8 @@
         <para>
             Class files (<filename>.bbclass</filename>) contain information that is useful to share
             between metadata files. 
-            An example is the autotools class, which contains
-            common settings for any application that autotools uses.
+            An example is the Autotools class, which contains
+            common settings for any application that Autotools uses.
             The <link linkend='ref-classes'>Reference: Classes</link> appendix provides details
             about common classes and how to use them.
         </para>
@@ -121,13 +133,13 @@
 
         <para>
             The configuration files (<filename>.conf</filename>) define various configuration variables
-            that govern what Poky does. 
-            These files are split into several areas that define machine configuration options, 
+            that govern the Yocto Project build process. 
+            These files fall into several areas that define machine configuration options, 
             distribution configuration options, compiler tuning options, general common configuration
-            options and user configuration options (<filename>local.conf</filename>).
+            options and user configuration options (<filename>local.conf</filename>, which is found
+            in the Yocto Project files build directory).
         </para>
     </section>
-
 </section>
 
 
@@ -135,47 +147,64 @@
     <title>Running a Build</title>
 
     <para>
-        First the Poky build environment needs to be set up using the following command:
+        You can find information on how to build an image using the Yocto Project 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 the 
+        <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
+        Yocto Project Quick Start</ulink>.
+        This section provides a quick overview.
     </para>
+
     <para>
+        The first thing you need to do is set up the Yocto Project build environment by sourcing
+        the environment setup script as follows:
         <literallayout class='monospaced'>
-     $ source oe-init-build-env [build_dir]
+     $ source oe-init-build-env [build_dir];
         </literallayout>
     </para>
+
     <para>
-        The build_dir is the dir containing all the build's object files. The default 
-        build dir is poky-dir/build. A different build_dir can be used for each of the targets. 
-        For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target.
-        Please refer to <link linkend="structure-core-script">oe-init-build-env</link>
-        for more detailed information.
-    </para>
-    <para>
-        Once the Poky build environment is set up, a target can be built using:
+        The <filename>build_dir</filename> is optional and specifies the directory Yocto Project
+        uses for the build.
+        If you do not specify a build directory it defaults to <filename>build</filename>
+        in the Yocto Project files directory structure.
+        A common practice is to use a different build directory for different targets. 
+        For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
+        target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
+        See <link linkend="structure-core-script">oe-init-build-env</link>
+        for more information on this script.
     </para>
+
     <para>
+        Once the Yocto Project build environment is set up, you can build a target using:
         <literallayout class='monospaced'>
      $ bitbake &lt;target&gt;
         </literallayout>
     </para>
+
     <para>
-        The target is the name of the recipe you want to build. 
+        The <filename>target</filename> is the name of the recipe you want to build. 
         Common targets are the images in <filename>meta/recipes-core/images</filename>,
-        <filename>/meta/recipes-sato/images</filename>, etc.
+        <filename>/meta/recipes-sato/images</filename>, etc. all found in the Yocto Project
+        files.
         Or, the target can be the name of a recipe for a specific piece of software such as 
         <application>busybox</application>. 
-        For more details about the standard images available, see the 
+        For more details about the images Yocto Project supports, see the 
         <link linkend="ref-images">'Reference: Images'</link> appendix.
     </para>
+
     <note>
         Building an image without GNU Public License Version 3 (GPLv3) components is 
         only supported for minimal and base images.
         See <link linkend='ref-images'>'Reference: Images'</link> for more information.
     </note>
+
     <note>
-        When building an image using GPL components you need to maintain your original 
+        When building an image using GPL components, you need to maintain your original 
         settings and not switch back and forth applying different versions of the GNU
-        Public License.  If you rebuild using different versions of GPL you can get 
-        dependency errors due to some components not being rebuilt.
+        Public License.  
+        If you rebuild using different versions of GPL, dependency errors might occur
+        due to some components not being rebuilt.
     </note>
 </section>
 
@@ -183,17 +212,18 @@
     <title>Installing and Using the Result</title>
 
     <para>
-        Once an image has been built it often needs to be installed. 
-        The images/kernels built by Poky are placed in the 
-        <filename class="directory">tmp/deploy/images</filename> directory. 
-        Running qemux86 and qemuarm images is described in the
-        'Using Pre-Built Binaries and QEMU' section of the Yocto Project Quick Start.
-        See <ulink url="http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html"/>
-        for the guide. 
+        Once an image has been built, it often needs to be installed. 
+        The images and kernels built by the Yocto Project are placed in the build directory in 
+        <filename class="directory">tmp/deploy/images</filename>. 
+        For information on how to run pre-built images such as <filename>qemux86</filename> 
+        and <filename>qemuarm</filename>, see the
+        <ulink url='http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html#using-pre-built'>
+        Using Pre-Built Binaries and QEMU</ulink> section in the 
+        <ulink url='http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html'>
+        Yocto Project Quick Start</ulink>.
         For information about how to install these images, see the documentation for your
         particular board/machine.
     </para>
-
 </section>
 
 <section id='usingpoky-debugging'>
@@ -213,15 +243,17 @@
     <section id='usingpoky-debugging-taskfailures'>
         <title>Task Failures</title>
 
-        <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 
-            For example, the "compile" task of busybox 1.01 on the ARM spitz machine might be 
+        <para>The log file for shell tasks is available in 
+            <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 
+            For example, the <filename>compile</filename> task of busybox 1.01 on the ARM spitz 
+            machine might be 
             <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>.
             To see what BitBake runs to generate that log, look at the corresponding 
             <filename>run.do_taskname.pid </filename> file located in the same directory.
         </para>
 
         <para>
-            Presently, the output from python tasks is sent directly to the console.
+            Presently, the output from Python tasks is sent directly to the console.
         </para>
     </section>
 
@@ -230,28 +262,33 @@
 
         <para>
             Any given package consists of a set of tasks.  
-            In most cases the series is: fetch, unpack, patch, configure,
-            compile, install, package, package_write and build. 
-            The default task is "build" and any tasks on which it depends build first - hence, 
-            the standard BitBake behaviour. 
-            Some tasks exist, such as devshell, that are not part of the default build chain.  
-            If you wish to run a task that is not part of the default build chain you can use the 
-            "-c" option in BitBake as follows:
+            The standard BitBake behavior in most cases is: <filename>fetch</filename>, 
+            <filename>unpack</filename>, 
+            <filename>patch</filename>, <filename>configure</filename>,
+            <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
+            <filename>package_write</filename>, and <filename>build</filename>. 
+            The default task is <filename>build</filename> and any tasks on which it depends 
+            build first.
+            Some tasks exist, such as <filename>devshell</filename>, that are not part of the
+            default build chain.  
+            If you wish to run a task that is not part of the default build chain, you can use the 
+            <filename>-c</filename> option in BitBake as follows:
             <literallayout class='monospaced'>
      $ bitbake matchbox-desktop -c devshell
             </literallayout>
         </para>
 
         <para>
-            If you wish to rerun a task use the force option "-f". 
+            If you wish to rerun a task, use the <filename>-f</filename> force option. 
             For example, the following sequence forces recompilation after changing files in the 
             working directory.
-        </para>
-
-        <para>
             <literallayout class='monospaced'>
      $ bitbake matchbox-desktop
-     [make some changes to the source code in the WORKDIR]
+               .
+               .
+        [make some changes to the source code in the working directory]
+               .
+               .
      $ bitbake matchbox-desktop -c compile -f
      $ bitbake matchbox-desktop
             </literallayout>
@@ -259,14 +296,14 @@
 
         <para>
             This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it.
-            The last command reruns all tasks, basically the packaging tasks, after the compile.
-            BitBake recognizes that the "compile" task was rerun and therefore understands that the other
-            tasks also need to be run again.
+            The last command reruns all tasks (basically the packaging tasks) after the compile.
+            BitBake recognizes that the <filename>compile</filename> task was rerun and therefore 
+            understands that the other tasks also need to be run again.
         </para>
 
         <para>
-            You can view a list of tasks in a given package by running the "listtasks" task.
-            For example:
+            You can view a list of tasks in a given package by running the
+            <filename>listtasks</filename> task as follows:
             <literallayout class='monospaced'>
      $ bitbake matchbox-desktop -c
             </literallayout>
@@ -279,12 +316,13 @@
 
         <para>
             Sometimes it can be hard to see why BitBake wants to build some other packages before a given 
-            package you've specified.
-            The <filename>bitbake -g targetname</filename> command creates the <filename>depends.dot</filename> and
-            <filename>task-depends.dot</filename> files in the current directory. 
+            package you have specified.
+            The <filename>bitbake -g targetname</filename> command creates the 
+            <filename>depends.dot</filename> and <filename>task-depends.dot</filename> files 
+            in the current directory. 
             These files show the package and task dependencies and are useful for debugging problems.
-            You can use the <filename>bitbake -g -u depexp targetname</filename> command to display the results 
-            in a more human-readable form.
+            You can use the <filename>bitbake -g -u depexp targetname</filename> command to 
+            display the results in a more human-readable form.
         </para>
     </section>
 
@@ -292,10 +330,10 @@
         <title>General BitBake Problems</title>
 
         <para>
-            You can see debug output from BitBake by using the "-D" option.
+            You can see debug output from BitBake by using the <filename>-D</filename> option.
             The debug output gives more information about what BitBake
             is doing and the reason behind it. 
-            Each "-D" option you use increases the logging level.
+            Each <filename>-D</filename> option you use increases the logging level.
             The most common usage is <filename>-DDD</filename>.
         </para>
 
@@ -312,19 +350,20 @@
         <title>Building with No Dependencies</title>
         <para>
             If you really want to build a specific <filename>.bb</filename> file, you can use
-            the command form <filename>bitbake -b somepath/somefile.bb</filename>. 
+            the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>. 
             This command form does not check for dependencies so you should use it
             only when you know its dependencies already exist. 
-            You can also specify fragments of the filename and BitBake checks for a unique match.
+            You can also specify fragments of the filename.
+            In this case, BitBake checks for a unique match.
         </para>
     </section>
 
     <section id='usingpoky-debugging-variables'>
         <title>Variables</title>
         <para>
-            The "-e" option dumps the resulting environment for
+            The <filename>-e</filename> option dumps the resulting environment for
             either the configuration (no package specified) or for a
-            specific package when specified with the "-b" option.
+            specific package when specified with the <filename>-b</filename> option.
         </para>
     </section>
     
@@ -422,23 +461,23 @@
     
     <section id='usingpoky-debugging-others'>
         <title>Other Tips</title>
-        <tip>
-        <para>
-            When adding new packages it is worth watching for undesireable items making their way
-            into compiler command lines.
-            For example, you do not want references to local system files like 
-            <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
-        </para>
-        </tip>
-        <tip>
+
         <para>
-            If you want to remove the psplash boot splashscreen, add "psplash=false"
-            to  the kernel command line.
-            Doing so prevents psplash from loading thus allowing you to see the console.
-            It is also possible to switch out of the splashscreen by 
-            switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
+            Here are some other tips that you might find useful:
+            <itemizedlist>
+                <listitem><para>When adding new packages, it is worth watching for 
+                    undesireable items making their way into compiler command lines.
+                    For example, you do not want references to local system files like 
+                    <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
+                    </para></listitem>
+                <listitem><para>If you want to remove the psplash boot splashscreen, 
+                    add <filename>psplash=false</filename> to  the kernel command line.
+                    Doing so prevents psplash from loading and thus allows you to see the console.
+                    It is also possible to switch out of the splashscreen by 
+                    switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
+                    </para></listitem>
+            </itemizedlist>
         </para>
-        </tip>
     </section>
 </section>