[gnome-continuous-yocto/gnomeostree-3.28-rocko: 1968/8267] ref-manual: Clarify and flesh out debugging using bitbake -e

[Emmanuele Bassi <ebassi src gnome org>]

commit 1a1fc42e9f0c609d9c57e6a0a68a67f03db6acbf
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Mon Aug 8 14:13:06 2016 -0700

    ref-manual: Clarify and flesh out debugging using bitbake -e
    
    Fixes [YOCTO #10099]
    
    Renamed the log file section to better describe what the user
    is accomplishing.
    
    Renamed and repositioned the variables section to better describe
    and emphasize the task.  Also fleshed out the variables section with
    more information.
    
    (From yocto-docs rev: 0606fe481416a07bf98fc8ae79a30c1d62e75e6d)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/ref-manual/usingpoky.xml |   75 +++++++++++++++++++++++---------
 1 files changed, 54 insertions(+), 21 deletions(-)
---
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 99912ff..f70c196 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -163,9 +163,8 @@
         <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
     </note>
 
-
-    <section id='usingpoky-debugging-taskfailures'>
-        <title>Task Failures</title>
+    <section id='usingpoky-debugging-viewing-logs-from-failed-tasks'>
+        <title>Viewing Logs from Failed Tasks</title>
 
         <para>The log file for shell tasks is available in
             <filename>${WORKDIR}/temp/log.do_<replaceable>taskname</replaceable>.pid</filename>.
@@ -183,6 +182,58 @@
         </para>
     </section>
 
+    <section id='usingpoky-debugging-viewing-variable-values'>
+        <title>Viewing Variable Values</title>
+        <para>
+            BitBake's <filename>-e</filename> option is used to display
+            variable values after parsing.
+            The following command displays the variable values after the
+            configuration files (i.e. <filename>local.conf</filename>,
+            <filename>bblayers.conf</filename>, and so forth) have been
+            parsed:
+            <literallayout class='monospaced'>
+     $ bitbake -e
+            </literallayout>
+            The following command displays variable values after a specific
+            recipe has been parsed.
+            The variables include those from the configuration as well:
+            <literallayout class='monospaced'>
+     $ bitbake -e recipename
+            </literallayout>
+            <note><para>
+                Each recipe has its own private set of variables (datastore).
+                Internally, after parsing the configuration, a copy of the
+                resulting datastore is made prior to parsing each recipe.
+                This copying implies that variables set in one recipe will
+                not be visible to other recipes.</para>
+
+                <para>Likewise, each task within a recipe gets a private
+                datastore based on the recipe datastore, which means that
+                variables set within one task will not be visible to
+                other tasks.</para>
+            </note>
+        </para>
+
+        <para>
+            In the output of <filename>bitbake -e</filename>, each variable is
+            preceded by a description of how the variable got its value,
+            including temporary values that were later overriden.
+            This description also includes variable flags (varflags) set on
+            the variable.
+            The output can be very helpful during debugging.
+        </para>
+
+        <para>
+            Variables that are exported to the environment are preceded by
+            <filename>export</filename> in the output of
+            <filename>bitbake -e</filename>.
+            See the following example:
+            <literallayout class='monospaced'>
+     export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
+            </literallayout>
+        </para>
+    </section>
+
     <section id='usingpoky-debugging-taskrunning'>
         <title>Running Specific Tasks</title>
 
@@ -319,7 +370,6 @@
 
     </section>
 
-
     <section id='usingpoky-debugging-dependencies'>
         <title>Dependency Graphs</title>
 
@@ -410,23 +460,6 @@
         </para>
     </section>
 
-    <section id='usingpoky-debugging-variables'>
-        <title>Variables</title>
-        <para>
-            You can use the <filename>-e</filename> BitBake option to
-            display the parsing environment for a configuration.
-            The following displays the general parsing environment:
-            <literallayout class='monospaced'>
-     $ bitbake -e
-            </literallayout>
-            This next example shows the parsing environment for a specific
-            recipe:
-            <literallayout class='monospaced'>
-     $ bitbake -e <replaceable>recipename</replaceable>
-            </literallayout>
-        </para>
-    </section>
-
     <section id='recipe-logging-mechanisms'>
         <title>Recipe Logging Mechanisms</title>
         <para>