diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index e7b423f66f..7aae2e27a9 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -1210,6 +1210,67 @@
+
+ Stamp Files and the Rerunning of Tasks
+
+
+ For each task that completes successfully, BitBake writes a
+ stamp file into the
+ STAMPS_DIR
+ directory.
+ The beginning of the stamp file's filename is determined by the
+ STAMP
+ variable, and the end of the name consists of the task's name
+ and current
+ input checksum.
+
+ This naming scheme assumes that
+ BB_SIGNATURE_HANDLER
+ is "OEBasicHash", which is almost always the case in
+ current OpenEmbedded.
+
+ To determine if a task needs to be rerun, BitBake checks if a
+ stamp file with a matching input checksum exists for the task.
+ If such a stamp file exists, the task's output is assumed to
+ exist and still be valid.
+ If the file does not exist, the task is rerun.
+
+ The stamp mechanism is more general than the shared
+ state (sstate) cache mechanism described in the
+ "Setscene Tasks and Shared State"
+ section.
+ BitBake avoids rerunning any task that has a valid
+ stamp file, not just tasks that can be accelerated through
+ the sstate cache.
+ However, you should realize that stamp files only
+ serve as a marker that some work has been done and these
+ files do not record task output.
+ The actual task output would usually be somewhere in
+ TMPDIR
+ (e.g. in some recipe's
+ WORKDIR.)
+ What the sstate cache mechanism adds is a way to cache task
+ output that can then be shared between build machines.
+
+
+ Since STAMPS_DIR is usually a subdirectory
+ of TMPDIR, removing
+ TMPDIR will also remove
+ STAMPS_DIR, which means tasks will
+ properly be rerun to repopulate TMPDIR.
+
+
+
+ If you want some task to always be considered "out of date",
+ you can mark it with the
+ nostamp
+ varflag.
+ If some other task depends on such a task, then that task will
+ also always be considered out of date, which might not be what
+ you want.
+
+
+
Setscene Tasks and Shared State
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index e51ceb1bf5..6912d3f6b2 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -801,8 +801,9 @@
build/tmp/stamps/
- This directory holds information that BitBake uses for accounting purposes
- to track what tasks have run and when they have run.
+ This directory holds information that BitBake uses for
+ accounting purposes to track what tasks have run and when they
+ have run.
The directory is sub-divided by architecture, package name, and
version.
Following is an example:
@@ -812,6 +813,13 @@
Although the files in the directory are empty of data,
BitBake uses the filenames and timestamps for tracking purposes.
+
+
+ For information on how BitBake uses stamp files to determine if
+ a task should be rerun, see the
+ "Stamp Files and the Rerunning of Tasks"
+ section.
+
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 2a48315be7..1f4b2171a9 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -12619,6 +12619,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
+
+ For information on how BitBake uses stamp files to determine
+ if a task should be rerun, see the
+ "Stamp Files and the Rerunning of Tasks"
+ section.
+
+
See STAMPS_DIR,
MULTIMACH_TARGET_SYS,