From 103bbc6642261cd5da038ba2071621919ee01253 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Thu, 12 Apr 2018 12:55:29 -0700
Subject: bitbake-user-manual: Updated "Task Checksums and Setscene" section

Fixes [#YOCTO 12030]

Updated the "Task Checksums and Setscene" section to provide a bit
of user information around the bitbake-dumpsigs use that lets a
user examine signatures and inputs that determine if a do_compile
task is indeed supposed to be run.

Added more explanation of how a user can examine signatures used
to determine if a do_compile task is indeed supposed to be run.

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../bitbake-user-manual-metadata.xml               | 74 ++++++++++++++--------
 1 file changed, 46 insertions(+), 28 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 32be1789d..b4fc64e75 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -2651,53 +2651,71 @@
             OpenEmbedded metadata-based example.
         </para>
 
-<!--
         <para>
-            Bug 12030: This list is a place holder of content existed from previous work
-            on the manual.
-            Some or all of it probably needs integrated into the subsections
-            that make up this section.
-            For now, I have just provided a short glossary-like description
-            for each variable.
+            These checksums are stored in
+            <link linkend='var-STAMP'><filename>STAMP</filename></link>.
+            You can examine the checksums using the following BitBake command:
+            <literallayout class='monospaced'>
+     $ bitbake-dumpsigs
+            </literallayout>
+            This command returns the signature data in a readable format
+            that allows you to examine the inputs used when the
+            OpenEmbedded build system generates signatures.
+            For example, using <filename>bitbake-dumpsigs</filename>
+            allows you to examine the <filename>do_compile</filename>
+            task's “sigdata” for a C application (e.g.
+            <filename>bash</filename>).
+            Running the command also reveals that the “CC” variable is part of
+            the inputs that are hashed.
+            Any changes to this variable would invalidate the stamp and
+            cause the <filename>do_compile</filename> task to run.
         </para>
--->
 
         <para>
             The following list describes related variables:
             <itemizedlist>
-                <listitem><para><filename>STAMP</filename>:
-                    The base path to create stamp files.</para></listitem>
-                <listitem><para><filename>STAMPCLEAN</filename>
-                    Again, the base path to create stamp files but can use wildcards
-                    for matching a range of files for clean operations.
-                    </para></listitem>
-                <listitem><para><filename>BB_STAMP_WHITELIST</filename>
-                    Lists stamp files that are looked at when the stamp policy
-                    is "whitelist".
-                    </para></listitem>
-                <listitem><para><filename>BB_STAMP_POLICY</filename>
-                    Defines the mode for comparing timestamps of stamp files.
-                    </para></listitem>
-                <listitem><para><filename>BB_HASHCHECK_FUNCTION</filename>
+                <listitem><para>
+                    <link linkend='var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>:
                     Specifies the name of the function to call during
                     the "setscene" part of the task's execution in order
                     to validate the list of task hashes.
                     </para></listitem>
-                <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
+                <listitem><para>
+                    <link linkend='var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>:
+                    Specifies a function BitBake calls that determines
+                    whether BitBake requires a setscene dependency to
+                    be met.
+                    </para></listitem>
+                <listitem><para>
+                    <link linkend='var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link>:
                     Specifies a function to call that verifies the list of
                     planned task execution before the main task execution
                     happens.
                     </para></listitem>
-                <listitem><para><filename>BB_SETSCENE_DEPVALID</filename>
-                    Specifies a function BitBake calls that determines
-                    whether BitBake requires a setscene dependency to
-                    be met.
+                <listitem><para>
+                    <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>:
+                    Defines the mode for comparing timestamps of stamp files.
+                    </para></listitem>
+                <listitem><para>
+                    <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>:
+                    Lists stamp files that are looked at when the stamp policy
+                    is "whitelist".
                     </para></listitem>
-                <listitem><para><filename>BB_TASKHASH</filename>
+                <listitem><para>
+                    <link linkend='var-BB_TASKHASH'><filename>BB_TASKHASH</filename></link>:
                     Within an executing task, this variable holds the hash
                     of the task as returned by the currently enabled
                     signature generator.
                     </para></listitem>
+                <listitem><para>
+                    <link linkend='var-STAMP'><filename>STAMP</filename></link>:
+                    The base path to create stamp files.
+                    </para></listitem>
+                <listitem><para>
+                    <link linkend='var-STAMPCLEAN'><filename>STAMPCLEAN</filename></link>:
+                    Again, the base path to create stamp files but can use wildcards
+                    for matching a range of files for clean operations.
+                    </para></listitem>
             </itemizedlist>
         </para>
     </section>
-- 
cgit 1.2.3-korg