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>
+            <note><title>Notes</title>
-                The build system does not maintain
+                <itemizedlist>
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+                    <listitem><para>
-                information as part of the shared state packages.
+                        The build system does not maintain
-                Consequently, considerations exist that affect maintaining
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
-                shared state feeds.
+                        information as part of the shared state packages.
-                For information on how the build system works with packages
+                        Consequently, considerations exist that affect
-                and can track incrementing
+                        maintaining shared state feeds.
-                <filename>PR</filename> information, see the
+                        For information on how the build system works with
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
+                        packages and can track incrementing
-                section in the Yocto Project Development Tasks Manual.
+                        <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
+            incremental build architecture, the checksums (signatures), and
-            state, and some tips and tricks.
+            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'>

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 @@
2495	second question assuming the build system can fetch the sstate	2495	second question assuming the build system can fetch the sstate
2496	objects from remote locations and install them if they are deemed	2496	objects from remote locations and install them if they are deemed
2497	to be valid.	2497	to be valid.
2498	<note>	2498	<note><title>Notes</title>
2499	The build system does not maintain	2499	<itemizedlist>
2500	<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>	2500	<listitem><para>
2501	information as part of the shared state packages.	2501	The build system does not maintain
2502	Consequently, considerations exist that affect maintaining	2502	<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
2503	shared state feeds.	2503	information as part of the shared state packages.
2504	For information on how the build system works with packages	2504	Consequently, considerations exist that affect
2505	and can track incrementing	2505	maintaining shared state feeds.
2506	<filename>PR</filename> information, see the	2506	For information on how the build system works with
2507	"<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"	2507	packages and can track incrementing
2508	section in the Yocto Project Development Tasks Manual.	2508	<filename>PR</filename> information, see the
		2509	"<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
		2510	section in the Yocto Project Development Tasks Manual.
		2511	</para></listitem>
		2512	<listitem><para>
		2513	The code in the build system that supports incremental
		2514	builds is not simple code.
		2515	For techniques that help you work around issues related
		2516	to shared state code, see the
		2517	"<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>"
		2518	and
		2519	"<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>"
		2520	sections both in the Yocto Project Development Tasks
		2521	Manual.
		2522	</para></listitem>
		2523	</itemizedlist>
2509	</note>	2524	</note>
2510	</para>	2525	</para>
2511		2526
2512	<para>	2527	<para>
2513	The rest of this section goes into detail about the overall	2528	The rest of this section goes into detail about the overall
2514	incremental build architecture, the checksums (signatures), shared	2529	incremental build architecture, the checksums (signatures), and
2515	state, and some tips and tricks.	2530	shared state.
2516	</para>	2531	</para>
2517		2532
2518	<section id='concepts-overall-architecture'>	2533	<section id='concepts-overall-architecture'>
@@ -2985,100 +3000,6 @@
2985	output from every task.	3000	output from every task.
2986	</para>	3001	</para>
2987	</section>	3002	</section>
2988
2989	<section id='concepts-tips-and-tricks'>
2990	<title>Tips and Tricks</title>
2991
2992	<para>
2993	The code in the build system that supports incremental builds
2994	is not simple code.
2995	This section presents some tips and tricks that help you work
2996	around issues related to shared state code.
2997	</para>
2998
2999	<section id='concepts-overview-debugging'>
3000	<title>Debugging</title>
3001
3002	<para>
3003	Seeing what metadata went into creating the input signature
3004	of a shared state (sstate) task can be a useful debugging
3005	aid.
3006	This information is available in signature information
3007	(<filename>siginfo</filename>) files in
3008	<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
3009	For information on how to view and interpret information in
3010	<filename>siginfo</filename> files, see the
3011	"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
3012	section in the Yocto Project Development Tasks Manual.
3013	</para>
3014	</section>
3015
3016	<section id='concepts-invalidating-shared-state'>
3017	<title>Invalidating Shared State</title>
3018
3019	<para>
3020	The OpenEmbedded build system uses checksums and shared
3021	state cache to avoid unnecessarily rebuilding tasks.
3022	Collectively, this scheme is known as "shared state code."
3023	</para>
3024
3025	<para>
3026	As with all schemes, this one has some drawbacks.
3027	It is possible that you could make implicit changes to your
3028	code that the checksum calculations do not take into
3029	account.
3030	These implicit changes affect a task's output but do not
3031	trigger the shared state code into rebuilding a recipe.
3032	Consider an example during which a tool changes its output.
3033	Assume that the output of <filename>rpmdeps</filename>
3034	changes.
3035	The result of the change should be that all the
3036	<filename>package</filename> and
3037	<filename>package_write_rpm</filename> shared state cache
3038	items become invalid.
3039	However, because the change to the output is
3040	external to the code and therefore implicit,
3041	the associated shared state cache items do not become
3042	invalidated.
3043	In this case, the build process uses the cached items
3044	rather than running the task again.
3045	Obviously, these types of implicit changes can cause
3046	problems.
3047	</para>
3048
3049	<para>
3050	To avoid these problems during the build, you need to
3051	understand the effects of any changes you make.
3052	Realize that changes you make directly to a function
3053	are automatically factored into the checksum calculation.
3054	Thus, these explicit changes invalidate the associated
3055	area of shared state cache.
3056	However, you need to be aware of any implicit changes that
3057	are not obvious changes to the code and could affect
3058	the output of a given task.
3059	</para>
3060
3061	<para>
3062	When you identify an implicit change, you can easily
3063	take steps to invalidate the cache and force the tasks
3064	to run.
3065	The steps you can take are as simple as changing a
3066	function's comments in the source code.
3067	For example, to invalidate package shared state files,
3068	change the comment statements of
3069	<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
3070	or the comments of one of the functions it calls.
3071	Even though the change is purely cosmetic, it causes the
3072	checksum to be recalculated and forces the build system to
3073	run the task again.
3074	<note>
3075	For an example of a commit that makes a cosmetic
3076	change to invalidate shared state, see this
3077	<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
3078	</note>
3079	</para>
3080	</section>
3081	</section>
3082	</section>	3003	</section>
3083		3004
3084	<section id='automatically-added-runtime-dependencies'>	3005	<section id='automatically-added-runtime-dependencies'>