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>

1 files changed, 28 insertions, 107 deletions

diff --git a/documentation/overview-manual/overview-manual-concepts.xml b/documentation/overview-manual/overview-manual-concepts.xml
index f5337813df..af34b970aa 100644
--- a/documentation/overview-manual/overview-manual-concepts.xml
+++ b/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'>