From 879eec203bc3a07bfcbcba9600a02f9c29a69db9 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Thu, 31 Mar 2016 16:45:29 -0700
Subject: ref-manual: Updated debugging tips and tricks

Fixes [YOCTO #9336]

I updated the "Debugging" section within the "Tips and Tricks"
section.  The list of items did not provide detail on two
BitBake command-line options you could use to dump out
signature data into .sigdata files.  Also, the .sigdata files
were incorrectly referred to as .siginfo files.

(From yocto-docs rev: 7836c386f4f7c011de710b6ec9f6be13045dc559)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/technical-details.xml | 59 +++++++++++++++++++-------
 1 file changed, 43 insertions(+), 16 deletions(-)

(limited to 'documentation')

diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 87d7387ab8..f06382ab52 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -785,22 +785,49 @@
                 Because of this, the Yocto Project includes strong debugging
                 tools:
                 <itemizedlist>
-                    <listitem><para>Whenever a shared state package is written out, so is a
-                        corresponding <filename>.siginfo</filename> file.
-                        This practice results in a pickled Python database of all
-                        the metadata that went into creating the hash for a given shared state
-                        package.</para></listitem>
-                    <listitem><para>If you run BitBake with the <filename>--dump-signatures</filename>
-                        (or <filename>-S</filename>) option, BitBake dumps out
-                        <filename>.siginfo</filename> files in
-                        the stamp directory for every task it would have executed instead of
-                        building the specified target package.</para></listitem>
-                    <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
-                        can process <filename>.siginfo</filename> files.
-                        If you specify one of these files, BitBake dumps out the dependency
-                        information in the file.
-                        If you specify two files, BitBake compares the two files and dumps out
-                        the differences between the two.
+                    <listitem><para>Whenever a shared state package is written
+                        out into the
+                        <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
+                        a corresponding <filename>.siginfo</filename> file is
+                        also written.
+                        This file contains a pickled Python database of all
+                        the Metadata that went into creating the hash for a
+                        given shared state package.
+                        Whenever a stamp is written into the stamp directory
+                        <link linkend='var-STAMP'><filename>STAMP</filename></link>,
+                        a corresponding <filename>.sigdata</filename> file
+                        is created that contains the same hash data that
+                        represented the executed task.
+                        </para></listitem>
+                    <listitem><para>You can use BitBake to dump out the
+                        signature construction information without executing
+                        tasks by using either of the following BitBake
+                        command-line options:
+                        <literallayout class='monospaced'>
+     &dash;&dash;dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>
+     -S <replaceable>SIGNATURE_HANDLER</replaceable>
+                        </literallayout>
+                        <note>
+                            Two common values for
+                            <replaceable>SIGNATURE_HANDLER</replaceable> are
+                            "none" and "printdiff" to only dump the signature
+                            or to compare the dumped signature with the
+                            cached one, respectively.
+                        </note>
+                        Using BitBake with either of these options causes
+                        BitBake to dump out <filename>.sigdata</filename> files
+                        in the stamp directory for every task it would have
+                        executed instead of building the specified target
+                        package.
+                        </para></listitem>
+                    <listitem><para>There is a
+                        <filename>bitbake-diffsigs</filename> command that
+                        can process <filename>.sigdata</filename> and
+                        <filename>.siginfo</filename> files.
+                        If you specify one of these files, BitBake dumps out
+                        the dependency information in the file.
+                        If you specify two files, BitBake compares the two
+                        files and dumps out the differences between the two.
                         This more easily helps answer the question of "What
                         changed between X and Y?"</para></listitem>
                 </itemizedlist>
-- 
cgit v1.2.3-54-g00ecf