diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 7330247819..5f7b66e411 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -12344,6 +12344,98 @@ Some notes from Cal:
+
+
+
+ Invalidating Shared State to Force a Task to Run
+
+
+ The OpenEmbedded build system uses
+ checksums
+ and
+ shared state
+ cache to avoid unnecessarily rebuilding tasks.
+ Collectively, this scheme is known as "shared state code."
+
+
+
+ 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 rpmdeps
+ changes.
+ The result of the change should be that all the
+ package and
+ package_write_rpm 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.
+
+
+
+ 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.
+
+
+
+ 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
+ do_package
+ 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.
+
+ For an example of a commit that makes a cosmetic
+ change to invalidate shared state, see this
+ commit.
+
+
+
+
Running Specific Tasks
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.
-
- The build system does not maintain
- PR
- 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
- PR information, see the
- "Automatically Incrementing a Binary Package Revision Number"
- section in the Yocto Project Development Tasks Manual.
+ Notes
+
+
+ The build system does not maintain
+ PR
+ 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
+ PR information, see the
+ "Automatically Incrementing a Binary Package Revision Number"
+ section in the Yocto Project Development Tasks Manual.
+
+
+ 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
+ "Viewing Metadata Used to Create the Input Signature of a Shared State Task"
+ and
+ "Invalidating Shared State to Force a Task to Run"
+ sections both in the Yocto Project Development Tasks
+ Manual.
+
+
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.
@@ -2985,100 +3000,6 @@
output from every task.
-
-
- Tips and Tricks
-
-
- 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.
-
-
-
- Debugging
-
-
- 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
- (siginfo) files in
- SSTATE_DIR.
- For information on how to view and interpret information in
- siginfo files, see the
- "Viewing Task Variable Dependencies"
- section in the Yocto Project Development Tasks Manual.
-
-
-
-
- Invalidating Shared State
-
-
- The OpenEmbedded build system uses checksums and shared
- state cache to avoid unnecessarily rebuilding tasks.
- Collectively, this scheme is known as "shared state code."
-
-
-
- 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 rpmdeps
- changes.
- The result of the change should be that all the
- package and
- package_write_rpm 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.
-
-
-
- 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.
-
-
-
- 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
- do_package
- 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.
-
- For an example of a commit that makes a cosmetic
- change to invalidate shared state, see this
- commit.
-
-
-
-