overview-manual, dev-manual: Moved sstate debug tips sections

Two sections at the end of the shared state concepts section
in the overview-manual are really task sections.  I took those
and created a couple new sections in the dev-manual to house
those topics.

(From yocto-docs rev: 86382e7873d796f44554c8e04d3bd8091d350f51)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/dev-manual/dev-manual-common-tasks.xml

@@ -12344,6 +12344,98 @@ Some notes from Cal:
             </para>
         </section>
 
+        <section id='dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>
+            <title>Viewing Metadata Used to Create the Input Signature of a Shared State Task</title>
+
+            <para>
+                Seeing what metadata went into creating the input signature
+                of a shared state (sstate) task can be a useful debugging
+                aid.
+                This information is available in signature information
+                (<filename>siginfo</filename>) files in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
+                For information on how to view and interpret information in
+                <filename>siginfo</filename> files, see the
+                "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
+                section.
+            </para>
+
+            <para>
+                For conceptual information on shared state, see the
+                "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>Shared State</ulink>"
+                section in the Yocto Project Overview and Concepts Manual.
+            </para>
+        </section>
+
+        <section id='dev-invalidating-shared-state-to-force-a-task-to-run'>
+            <title>Invalidating Shared State to Force a Task to Run</title>
+
+            <para>
+                The OpenEmbedded build system uses
+                <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>checksums</ulink>
+                and
+                <ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>shared state</ulink>
+                cache to avoid unnecessarily rebuilding tasks.
+                Collectively, this scheme is known as "shared state code."
+            </para>
+
+            <para>
+                As with all schemes, this one has some drawbacks.
+                It is possible that you could make implicit changes to your
+                code that the checksum calculations do not take into
+                account.
+                These implicit changes affect a task's output but do not
+                trigger the shared state code into rebuilding a recipe.
+                Consider an example during which a tool changes its output.
+                Assume that the output of <filename>rpmdeps</filename>
+                changes.
+                The result of the change should be that all the
+                <filename>package</filename> and
+                <filename>package_write_rpm</filename> shared state cache
+                items become invalid.
+                However, because the change to the output is
+                external to the code and therefore implicit,
+                the associated shared state cache items do not become
+                invalidated.
+                In this case, the build process uses the cached items
+                rather than running the task again.
+                Obviously, these types of implicit changes can cause
+                problems.
+            </para>
+
+            <para>
+                To avoid these problems during the build, you need to
+                understand the effects of any changes you make.
+                Realize that changes you make directly to a function
+                are automatically factored into the checksum calculation.
+                Thus, these explicit changes invalidate the associated
+                area of shared state cache.
+                However, you need to be aware of any implicit changes that
+                are not obvious changes to the code and could affect
+                the output of a given task.
+            </para>
+
+            <para>
+                When you identify an implicit change, you can easily
+                take steps to invalidate the cache and force the tasks
+                to run.
+                The steps you can take are as simple as changing a
+                function's comments in the source code.
+                For example, to invalidate package shared state files,
+                change the comment statements of
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+                or the comments of one of the functions it calls.
+                Even though the change is purely cosmetic, it causes the
+                checksum to be recalculated and forces the build system to
+                run the task again.
+                <note>
+                    For an example of a commit that makes a cosmetic
+                    change to invalidate shared state, see this
+                    <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
+                </note>
+            </para>
+        </section>
+
         <section id='dev-debugging-taskrunning'>
             <title>Running Specific Tasks</title>
 

documentation/overview-manual/overview-manual-concepts.xml

@@ -2495,24 +2495,39 @@
             second question assuming the build system can fetch the sstate
             objects from remote locations and install them if they are deemed
             to be valid.
-            <note>
-                The build system does not maintain
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
-                information as part of the shared state packages.
-                Consequently, considerations exist that affect maintaining
-                shared state feeds.
-                For information on how the build system works with packages
-                and can track incrementing
-                <filename>PR</filename> information, see the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
-                section in the Yocto Project Development Tasks Manual.
+            <note><title>Notes</title>
+                <itemizedlist>
+                    <listitem><para>
+                        The build system does not maintain
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+                        information as part of the shared state packages.
+                        Consequently, considerations exist that affect
+                        maintaining shared state feeds.
+                        For information on how the build system works with
+                        packages and can track incrementing
+                        <filename>PR</filename> information, see the
+                       "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
+                        section in the Yocto Project Development Tasks Manual.
+                        </para></listitem>
+                    <listitem><para>
+                        The code in the build system that supports incremental
+                        builds is not simple code.
+                        For techniques that help you work around issues related
+                        to shared state code, see the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>Viewing Metadata Used to Create the Input Signature of a Shared State Task</ulink>"
+                        and
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-invalidating-shared-state-to-force-a-task-to-run'>Invalidating Shared State to Force a Task to Run</ulink>"
+                        sections both in the Yocto Project Development Tasks
+                        Manual.
+                        </para></listitem>
+                </itemizedlist>
             </note>
         </para>
 
         <para>
             The rest of this section goes into detail about the overall
-            incremental build architecture, the checksums (signatures), shared
-            state, and some tips and tricks.
+            incremental build architecture, the checksums (signatures), and
+            shared state.
         </para>
 
         <section id='concepts-overall-architecture'>
@@ -2985,100 +3000,6 @@
                 output from every task.
             </para>
         </section>
-
-        <section id='concepts-tips-and-tricks'>
-            <title>Tips and Tricks</title>
-
-            <para>
-                The code in the build system that supports incremental builds
-                is not simple code.
-                This section presents some tips and tricks that help you work
-                around issues related to shared state code.
-            </para>
-
-            <section id='concepts-overview-debugging'>
-                <title>Debugging</title>
-
-                <para>
-                    Seeing what metadata went into creating the input signature
-                    of a shared state (sstate) task can be a useful debugging
-                    aid.
-                    This information is available in signature information
-                    (<filename>siginfo</filename>) files in
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
-                    For information on how to view and interpret information in
-                    <filename>siginfo</filename> files, see the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
-                    section in the Yocto Project Development Tasks Manual.
-                </para>
-            </section>
-
-            <section id='concepts-invalidating-shared-state'>
-                <title>Invalidating Shared State</title>
-
-                <para>
-                    The OpenEmbedded build system uses checksums and shared
-                    state cache to avoid unnecessarily rebuilding tasks.
-                    Collectively, this scheme is known as "shared state code."
-                </para>
-
-                <para>
-                    As with all schemes, this one has some drawbacks.
-                    It is possible that you could make implicit changes to your
-                    code that the checksum calculations do not take into
-                    account.
-                    These implicit changes affect a task's output but do not
-                    trigger the shared state code into rebuilding a recipe.
-                    Consider an example during which a tool changes its output.
-                    Assume that the output of <filename>rpmdeps</filename>
-                    changes.
-                    The result of the change should be that all the
-                    <filename>package</filename> and
-                    <filename>package_write_rpm</filename> shared state cache
-                    items become invalid.
-                    However, because the change to the output is
-                    external to the code and therefore implicit,
-                    the associated shared state cache items do not become
-                    invalidated.
-                    In this case, the build process uses the cached items
-                    rather than running the task again.
-                    Obviously, these types of implicit changes can cause
-                    problems.
-                </para>
-
-                <para>
-                    To avoid these problems during the build, you need to
-                    understand the effects of any changes you make.
-                    Realize that changes you make directly to a function
-                    are automatically factored into the checksum calculation.
-                    Thus, these explicit changes invalidate the associated
-                    area of shared state cache.
-                    However, you need to be aware of any implicit changes that
-                    are not obvious changes to the code and could affect
-                    the output of a given task.
-                </para>
-
-                <para>
-                    When you identify an implicit change, you can easily
-                    take steps to invalidate the cache and force the tasks
-                    to run.
-                    The steps you can take are as simple as changing a
-                    function's comments in the source code.
-                    For example, to invalidate package shared state files,
-                    change the comment statements of
-                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
-                    or the comments of one of the functions it calls.
-                    Even though the change is purely cosmetic, it causes the
-                    checksum to be recalculated and forces the build system to
-                    run the task again.
-                    <note>
-                        For an example of a commit that makes a cosmetic
-                        change to invalidate shared state, see this
-                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
-                    </note>
-                </para>
-            </section>
-        </section>
     </section>
 
     <section id='automatically-added-runtime-dependencies'>