bitbake: user-manual: Review edits applied from Paul Eggleton.

Review of the entire manual by Paul.  I have implemented his
suggestions throughout.

(Bitbake rev: 5cd310d1df194cd171691a4bcfb98024e2bc66b8)

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

4 files changed, 115 insertions, 126 deletions

diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml
index d451ebb533..6110a93e2a 100644
--- a/bitbake/doc/user-manual/user-manual-execution.xml
+++ b/bitbake/doc/user-manual/user-manual-execution.xml
@@ -87,21 +87,6 @@
             just constructed.
             The <filename>bitbake.conf</filename> file usually indicates
             all the other key include files to parse.
-            The usual convention is to have machine, distro, site, and local
-            configurations.
-            This means a user provides their own customizations
-            through a <filename>local.conf</filename> file.
-        </para>
-
-        <para>
-            As mentioned in the previous paragraph, two of the other notable
-            configuration files are the distro and machine configuration
-            files.
-            These configuration files are normally identified by
-            variables unique to the build systems using BitBake.
-            For example, the Yocto Project uses the
-            <filename>DISTRO</filename> and <filename>MACHINE</filename>
-            variables, respectively.
         </para>
 
         <para>
@@ -122,7 +107,7 @@
 
         <para>
             The base configuration metadata is global
-            and therefore affects all packages and tasks that are executed.
+            and therefore affects all recipes and tasks that are executed.
         </para>
 
         <para>
@@ -161,10 +146,11 @@
             These variables might have been set from the environment
             depending on the environment variables previously
             mentioned or set in the configuration files.
-            See the
+            The
             "<link linkend='ref-variables-glos'>Variables Glossary</link>"
-            for a full list of variables.
-            The following list shows common variables set:
+            chapter presents a full list of variables.
+<!--
+            Here are some common ones used:
             <itemizedlist>
                 <listitem><para>
                     <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
@@ -215,6 +201,7 @@
                     <link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link>
                     </para></listitem>
             </itemizedlist>
+-->
         </para>
 
         <para>
@@ -305,7 +292,7 @@
         </para>
 
         <para>
-            BitBake does not need all this information.
+            BitBake does not need all of this information.
             It only needs a small subset of the information to make
             decisions about the recipe.
             Consequently, BitBake caches the values in which it is
@@ -375,7 +362,7 @@
             <literallayout class='monospaced'>
      PROVIDES += "virtual/package"
             </literallayout>
-            The recipe now provides both "package1" and "virtual/package.
+            The recipe now provides both "package1" and "virtual/package".
             The "virtual/" namespace is often used to denote cases where
             multiple providers are expected with the user choosing between
             them.
@@ -395,20 +382,8 @@
             The default
             <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
             is the provider with the same name as the target.
-        </para>
-
-        <para>
-            Bitbake iterates through each target it needs to build and resolve
-            them using this process.
-            As an example, suppose the target is
-            <filename>core-image-sato</filename>.
-            In this case, it would lead to
-            <filename>packagegroup-core-x11-sato</filename>,
-            which in turn leads to recipes like
-            <filename>matchbox-terminal</filename>, <filename>pcmanfm</filename>
-            and <filename>gthumb</filename>.
-            These recipes in turn depend on <filename>eglibc</filename>
-            and the toolchain.
+            Bitbake iterates through each target it needs to build and
+            resolves them and their dependencies using this process.
         </para>
 
         <para>
@@ -418,21 +393,21 @@
             Version comparisons are made using the same method as Debian.
             You can use the
             <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
-            variable to specify a particular version (usually in the distro configuration).
+            variable to specify a particular version.
             You can influence the order by using the
             <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
             variable.
             By default, files have a preference of "0".
             Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
-            package unlikely to be used unless it is explicitly referenced.
-            Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
+            recipe unlikely to be used unless it is explicitly referenced.
+            Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the recipe is used.
             <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
-            <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
+            <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental recipe
             versions until they have undergone sufficient testing to be considered stable.
         </para>
 
         <para>
-            When there are multiple “versions” of a given package,
+            When there are multiple “versions” of a given recipe,
             BitBake defaults to selecting the most recent
             version, unless otherwise specified.
             If the recipe in question has a
@@ -573,12 +548,12 @@
         <para>
             Tasks can either be a shell task or a Python task.
             For shell tasks, BitBake writes a shell script to
-            <filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
+            <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/run.do_taskname.pid</filename>
             and then executes the script.
             The generated shell script contains all the exported variables,
             and the shell functions with all variables expanded.
             Output from the shell script goes to the file
-            <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
+            <filename>${T}/log.do_taskname.pid</filename>.
             Looking at the expanded shell functions in the run file and
             the output in the log files is a useful debugging technique.
         </para>
@@ -831,9 +806,6 @@
             a setscene task named <filename>xxx_setscene</filename>.
             The setscene version of the task executes and provides the necessary
             artifacts returning either success or failure.
-            <note>
-                Artifacts might need to be fetched from the network.
-            </note>
         </para>
 
         <para>
diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index cbf08d949c..c66596ed6e 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -42,7 +42,7 @@
      fetcher = bb.fetch2.Fetch(src_uri, d)
      fetcher.download()
             </literallayout>
-            This code sets up an instance of the fetch module.
+            This code sets up an instance of the fetch class.
             The instance uses a space-separated list of URLs from the
             <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
             variable and then calls the <filename>download</filename>
@@ -155,14 +155,13 @@
             <filename>SRC_URI</filename> variable with the appropriate
             varflags as follows:
             <literallayout class='monospaced'>
-     SRC_URI[md5sum]
-     SRC_URI[sha256sum]
+     SRC_URI[md5sum] = "value"
+     SRC_URI[sha256sum] = "value"
             </literallayout>
             You can also specify the checksums as parameters on the
             <filename>SRC_URI</filename> as shown below:
             <literallayout class='monospaced'>
-     SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07f
-db994d"
+     SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
             </literallayout>
             If multiple URIs exist, you can specify the checksums either
             directly as in the previous example, or you can name the URLs.
@@ -578,7 +577,7 @@ db994d"
                 Fetch submodules also exist for the following:
                 <itemizedlist>
                     <listitem><para>
-                        Bazzar (<filename>bzr://</filename>)
+                        Bazaar (<filename>bzr://</filename>)
                         </para></listitem>
                     <listitem><para>
                         Perforce (<filename>p4://</filename>)
diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml
index 6f9ad2049a..d46e823c72 100644
--- a/bitbake/doc/user-manual/user-manual-intro.xml
+++ b/bitbake/doc/user-manual/user-manual-intro.xml
@@ -6,10 +6,10 @@
 
     <para>
         Welcome to the BitBake User Manual.
-        This manual provides information on BitBake.
+        This manual provides information on the BitBake tool.
         The information attempts to be as independent as possible regarding
         systems that use BitBake, such as the Yocto Project and
-        OpenEmbeddeded.
+        OpenEmbedded.
         In some cases, scenarios or examples that within the context of
         a build system are used in the manual to help with understanding.
         For these cases, the manual clearly states the context.
@@ -88,7 +88,7 @@
             an aspiring embedded Linux distribution.
             All of the build systems used by traditional desktop Linux
             distributions lacked important functionality, and none of the
-            ad-hoc buildroot systems, prevalent in the
+            ad-hoc Buildroot-based systems, prevalent in the
             embedded space, were scalable or maintainable.
         </para>
 
@@ -216,7 +216,7 @@
 
             <para>
                 Within the context of BitBake, or any project utilizing BitBake
-                as it's build system, files with the <filename>.bb</filename>
+                as its build system, files with the <filename>.bb</filename>
                 extension are referred to as recipes.
                 <note>
                     The term "package" is also commonly used to describe recipes.
@@ -282,7 +282,7 @@
 
             <para>
                 To illustrate how you can use layers to keep things modular,
-                consider machine customizations.
+                consider customizations you might make to support a specific target machine.
                 These types of customizations typically reside in a special layer,
                 rather than a general layer, called a Board Specific Package (BSP) Layer.
                 Furthermore, the machine customizations should be isolated from
@@ -343,7 +343,7 @@
                 <filename>busybox_1.3.0.bb</filename>, the append name would not
                 match.
                 However, if you named the append file
-                <filename>busybox_1.%.bb</filename>, then you would have a match.
+                <filename>busybox_1.%.bbappend</filename>, then you would have a match.
             </para>
         </section>
     </section>
@@ -421,20 +421,10 @@
         <title>The BitBake Command</title>
 
         <para>
-            BitBake is the underlying piece of the build system.
-            Two excellent examples are the Yocto Project and the OpenEmbedded
-            build systems.
-            Each provide an environment in which to develop embedded Linux
-            images, and each use BitBake as their underlying build engine.
-        </para>
-
-        <para>
-            BitBake facilitates executing tasks in a single <filename>.bb</filename>
-            file, or executing a given task on a set of multiple
-            <filename>.bb</filename> files, accounting for interdependencies
-            amongst them.
-            This section presents the BitBake syntax and provides some execution
-            examples.
+            The BitBake command is the primary interface to the BitBake
+            tool.
+            This section presents the BitBake command syntax and provides
+            several execution examples.
         </para>
 
         <section id='usage-and-syntax'>
@@ -539,17 +529,21 @@ Options:
                 </para>
 
                 <para>
-                    The following command runs the clean task on the
-                    <filename>foo_1.0.bb</filename> recipe file:
-                    <literallayout class='monospaced'>
-     $ bitbake -b foo.bb -c clean
-                    </literallayout>
                     The following command runs the build task, which is
                     the default task, on the <filename>foo_1.0.bb</filename>
                     recipe file:
                     <literallayout class='monospaced'>
      $ bitbake -b foo_1.0.bb
                     </literallayout>
+                    The following command runs the clean task on the
+                    <filename>foo_1.0.bb</filename> recipe file:
+                    <literallayout class='monospaced'>
+     $ bitbake -b foo.bb -c clean
+                    </literallayout>
+                    <note>
+                        The "-b" option explicitly does not handle recipe
+                        dependencies.
+                    </note>
                 </para>
             </section>
 
@@ -573,7 +567,7 @@ Options:
 
                 <para>
                     The <filename>bitbake</filename> command, when not using
-                    "--buildfile" or "-b" only accepts a "PROVIDER".
+                    "--buildfile" or "-b" only accepts a "PROVIDES".
                     You cannot provide anything else.
                     By default, a recipe file generally "PROVIDES" its
                     "packagename", "packagename-version", and
@@ -581,10 +575,6 @@ Options:
                     example:
                     <literallayout class='monospaced'>
      $ bitbake foo
-
-     $ bitbake foo-1.0
-
-     $ bitbake foo-1.0-r0
                     </literallayout>
                     This next example "PROVIDES" the package name and also uses
                     the "-c" option to tell BitBake to just execute the
@@ -600,22 +590,35 @@ Options:
 
                 <para>
                     BitBake is able to generate dependency graphs using
-                    the dot syntax.
-                    You can convert these graphs into images using the dot
-                    application from
+                    the <filename>dot</filename> syntax.
+                    You can convert these graphs into images using the
+                    <filename>dot</filename> tool from
                     <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
                 </para>
 
                 <para>
-                    When you generate a dependency graph, BitBake writes two files
+                    When you generate a dependency graph, BitBake writes four files
                     to the current working directory:
-                    <filename>depends.dot</filename>, which contains dependency information
-                    at the package level, and <filename>task-depends.dot</filename>,
-                    which contains a breakdown of the dependencies at the task level.
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>package-depends.dot</filename>:</emphasis>
+                            Shows BitBake's knowledge of dependencies between
+                            runtime targets.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>pn-depends.dot</filename>:</emphasis>
+                            Shows dependencies between build-time targets
+                            (i.e. recipes).
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>task-depends.dot</filename>:</emphasis>
+                            Shows dependencies between tasks.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>pn-buildlist</filename>:</emphasis>
+                            Shows a simple list of targets that are to be built.
+                            </para></listitem>
+                    </itemizedlist>
                 </para>
 
                 <para>
-                    To stop depending on common depends, use use the "-I" depend
+                    To stop depending on common depends, use the "-I" depend
                     option and BitBake omits them from the graph.
                     Leaving this information out can produce more readable graphs.
                     This way, you can remove from the graph
@@ -629,7 +632,7 @@ Options:
                     <literallayout class='monospaced'>
      $ bitbake -g foo
 
-     $ bitbake -g -I virtual/whatever -I bloom foo
+     $ bitbake -g -I virtual/kernel -I eglibc foo
                     </literallayout>
                 </para>
             </section>
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 748b959d98..3a19b96303 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -40,12 +40,15 @@
                 BitBake supports variables referencing one another's
                 contents using a syntax that is similar to shell scripting.
                 Following is an example that results in <filename>A</filename>
-                containing "aval" and <filename>B</filename> containing
+                containing "aval" and <filename>B</filename> evaluating to
                 "preavalpost".
                 <literallayout class='monospaced'>
      A = "aval"
      B = "pre${A}post"
                 </literallayout>
+                Because the expansion happens later, the value of
+                <filename>B</filename> expands differently if the value
+                of <filename>A</filename> changes.
             </para>
         </section>
 
@@ -79,7 +82,7 @@
             <title>Setting a weak default value (??=)</title>
 
             <para>
-                It is possible to use a "weaker" assignment that in the
+                It is possible to use a "weaker" assignment than in the
                 previous section by using the "??=" operator.
                 This assignment behaves identical to "?=" except that the
                 assignment is made at the end of the parsing process rather
@@ -197,6 +200,13 @@
                     override syntax.
                 </note>
             </para>
+
+            <para>
+                The operators "_append" and "_prepend" differ from
+                the operators ".=" and "=." in that they are deferred
+                until after parsing completes rather than being immediately
+                applied.
+            </para>
         </section>
 
         <section id='removing-override-style-syntax'>
@@ -519,7 +529,7 @@
                 recipes require.
                 For example, you can easily abstract out the tasks involved in
                 building a package that uses Autoconf and Automake and put
-                those tasks into a class file that can be used by your package.
+                those tasks into a class file that can be used by your recipe.
             </para>
 
             <para>
@@ -549,9 +559,10 @@
                 directive.
                 This directive causes BitBake to parse whatever file you specify,
                 and to insert that file at that location.
-                The directive is much like Make except that if the path specified
-                on the include line is a relative path, BitBake locates
-                the first file it can find within <filename>BBPATH</filename>.
+                The directive is much like its equivalent in Make except
+                that if the path specified on the include line is a relative
+                path, BitBake locates the first file it can find
+                within <filename>BBPATH</filename>.
             </para>
 
             <para>
@@ -588,7 +599,7 @@
             </para>
 
             <para>
-                Similar to how BitBake uses
+                Similar to how BitBake handles
                 <link linkend='include-directive'><filename>include</filename></link>,
                 if the path specified
                 on the require line is a relative path, BitBake locates
@@ -776,16 +787,17 @@
             Tasks are only supported in recipe (<filename>.bb</filename>
             or <filename>.inc</filename>) and class
             (<filename>.bbclass</filename>) files.
-            By convention, tasks begin with the string "do_".
+            By convention, task names begin with the string "do_".
         </para>
 
         <para>
             Here is an example of a task that prints out the date:
             <literallayout class='monospaced'>
      python do_printdate () {
-         import time print
-         time.strftime('%Y%m%d', time.gmtime())
+         import time
+         print time.strftime('%Y%m%d', time.gmtime())
      }
+     addtask printdate after do_fetch before do_build
             </literallayout>
         </para>
 
@@ -802,8 +814,8 @@
                 and defining some dependencies:
                 <literallayout class='monospaced'>
      python do_printdate () {
-         import time print
-         time.strftime('%Y%m%d', time.gmtime())
+         import time
+         print time.strftime('%Y%m%d', time.gmtime())
      }
      addtask printdate after do_fetch before do_build
                 </literallayout>
@@ -942,11 +954,6 @@
         <para>
             BitBake has a defined set of varflags available for recipes and
             classes.
-            You can discover the complete set by using <filename>grep</filename>
-            within a shell and search on the string "VarFlags".
-        </para>
-
-        <para>
             Tasks support a number of these flags which control various
             functionality of the task:
             <itemizedlist>
@@ -958,12 +965,13 @@
                     </para></listitem>
                 <listitem><para><emphasis>noexec:</emphasis>
                     Marks the tasks as being empty and no execution required.
-                    These flags are used as dependency placeholders or used when
-                    added tasks need to be subsequently disabled.
+                    The <filename>noexec</filename> flag can be used to set up
+                    tasks as dependency placeholders, or to disable tasks defined
+                    elsewhere that are not needed in a particular recipe.
                     </para></listitem>
                 <listitem><para><emphasis>nostamp:</emphasis>
                     Tells BitBake to not generate a stamp file for a task,
-                    which implies the task is always executed.
+                    which implies the task should always be executed.
                     </para></listitem>
                 <listitem><para><emphasis>fakeroot:</emphasis>
                     Causes a task to be run in a fakeroot environment,
@@ -1027,7 +1035,7 @@
                     List of functions to call before the task executes.
                     </para></listitem>
                 <listitem><para><emphasis>stamp-extra-info:</emphasis>
-                    Extra stamp information to append to the task's stamp
+                    Extra stamp information to append to the task's stamp.
                     As an example, OpenEmbedded uses this flag to allow
                     machine-specific tasks.
                     </para></listitem>
@@ -1380,15 +1388,18 @@
                         </row>
                         <row>
                             <entry align="left"><filename>d.setVar("X", value)</filename></entry>
-                            <entry align="left">Sets the variable "X" to "value".</entry>
+                            <entry align="left">Sets the variable "X" to the value of the Python
+                            variable called "value".</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.appendVar("X", value)</filename></entry>
-                            <entry align="left">Adds "value" to the end of the variable "X".</entry>
+                            <entry align="left">Adds the value of the Python variable called
+                            "value" to the end of the variable "X".</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.prependVar("X", value)</filename></entry>
-                            <entry align="left">Adds "value" to the start of the variable "X".</entry>
+                            <entry align="left">Adds the value of the Python variable called
+                            "value" to the start of the variable "X".</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.delVar("X")</filename></entry>
@@ -1400,40 +1411,44 @@
                         </row>
                         <row>
                             <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
-                            <entry align="left">Gets "flag" from the variable "X".
-                                Using "expand=True" expands the flag.</entry>
+                            <entry align="left">Gets then named flag from the variable "X".
+                                Using "expand=True" expands the named flag.</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry>
-                            <entry align="left">Sets "flag" for variable "X" to "value".
-                                <filename>setVarFlags</filename> does not clear previous flags.
-                                Think of this operation as <filename>addVarFlags</filename>.</entry>
+                            <entry align="left">Sets the named flag for variable "X" to the value
+                                of the Python variable called "value".</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry>
-                            <entry align="left">Need description.</entry>
+                            <entry align="left">Appends a value to the named flag on the
+                            variable "X".</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry>
-                            <entry align="left">Need description.</entry>
+                            <entry align="left">Prepends a value to the named flag on
+                               the variable "X".</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
-                            <entry align="left">Need description.</entry>
+                            <entry align="left">Deletes the named flag on the variable
+                                "X" from the datastore.</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
                             <entry align="left">Sets the flags specified in
-                                the <filename>dict()</filename> parameter.</entry>
+                                the <filename>flagsdict()</filename> parameter.
+                                <filename>setVarFlags</filename> does not clear previous flags.
+                                Think of this operation as <filename>addVarFlags</filename>.</entry>
                         </row>
                         <row>
                             <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
-                            <entry align="left">Returns a <filename>dict</filename> of the flags for
+                            <entry align="left">Returns a <filename>flagsdict</filename> of the flags for
                                 the variable "X".</entry>
                         </row>
                         <row>
-                            <entry align="left"><filename>d.delVarFlags</filename></entry>
-                            <entry align="left">Deletes all the flags for a variable.</entry>
+                            <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
+                            <entry align="left">Deletes all the flags for the variable "X".</entry>
                         </row>
                     </tbody>
                 </tgroup>