diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index 1657431495..dfb5b726c0 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -493,111 +493,86 @@
The code in the Yocto Project that supports incremental builds is not
- simple code.
- Consequently, when things go wrong, debugging needs to be straightforward.
- Because of this, the Yocto Project team included strong debugging
- tools.
+ simple code.
+ This section presents some tips and tricks that help you work around
+ issues related to shared state code.
-
- First, whenever a shared state package is written out, so is a
- corresponding .siginfo file.
- This practice results in a pickled python database of all
- the metadata that went into creating the hash for a given shared state
- package.
-
+
+ Debugging
-
- Second, if BitBake is run with the --dump-signatures
- (or -S) option, BitBake dumps out
- .siginfo files in
- the stamp directory for every task it would have executed instead of
- building the target package specified.
-
+
+ When things go wrong, debugging needs to be straightforward.
+ Because of this, the Yocto Project team included strong debugging
+ tools:
+
+ Whenever a shared state package is written out, so is a
+ corresponding .siginfo file.
+ This practice results in a pickled python database of all
+ the metadata that went into creating the hash for a given shared state
+ package.
+ If BitBake is run with the --dump-signatures
+ (or -S) option, BitBake dumps out
+ .siginfo files in
+ the stamp directory for every task it would have executed instead of
+ building the target package specified.
+ There is a bitbake-diffsigs command that
+ can process these .siginfo files.
+ If one file is specified, it will dump out the dependency
+ information in the file.
+ If two files are specified, it will compare the
+ two files and dump out the differences between the two.
+ This allows the question of "What changed between X and Y?" to be
+ answered easily.
+
+
+
-
- Finally, there is a bitbake-diffsigs command that
- can process these .siginfo files.
- If one file is specified, it will dump out the dependency
- information in the file.
- If two files are specified, it will compare the
- two files and dump out the differences between the two.
- This allows the question of "What changed between X and Y?" to be
- answered easily.
-
+
+ Invalidating Shared State
+
+
+ The Yocto Project shared state code uses checksums and shared state memory
+ cache to avoide building tasks that don't need built.
+ As with all schemes, this one has some drawbacks.
+ It is possible that you could make implicit changes that are not factored into the checksum
+ calculation, but do affect a task's output.
+ A good example is perhaps when a tool changes its output.
+ Let's say that the output of rpmdeps needed to change.
+ The result of the change should be that all the "package", "package_write_rpm",
+ and "package_deploy-rpm" shared state cache items would become invalid.
+ But, because this is a change that is external to the code and therefore implicit,
+ the associated shared state cache items do not become invalidated.
+ In this case, the build process would use the cache 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
+ change you make.
+ Note that any changes you make directly to a function automatically are factored into
+ the checksum calculation and thus, will invalidate the associated area of sstate cache.
+ 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.
+ Once you are aware of such a change, you can take steps to invalidate the cache
+ and force the task to run.
+ The step to take is as simple as changing a function's comments in the source code.
+ For example, to invalidate package shared state files, change the comment statments
+ of do_package or the comments of one of the functions it calls.
+ The change is purely cosmetic, but it causes the checksum to be recalculated and
+ forces the task to be run again.
+
+
+
+ For an example of a commit that makes a cosmetic change to invalidate an sstate,
+ see this
+ commit.
+
+
-
-