From f1879193b90b27f3c9b1e1dccc9097d5913d95b6 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 1 Sep 2016 10:10:47 -0700 Subject: ref-manual: New section clarifying stamps, input checksums and sstate cache Fixes [YOCTO #10172] I added a new section on how BitBake reruns tasks based on the stamps files. Also put in some cross-referencing links to that new section in the stamps entry for the structure chapter and in the STAMP variable in the glossary. (From yocto-docs rev: da8779d9eb85473cd6b0f74e9e1371e1d277890f) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/closer-look.xml | 61 ++++++++++++++++++++++++++++++ documentation/ref-manual/ref-structure.xml | 12 +++++- documentation/ref-manual/ref-variables.xml | 7 ++++ 3 files changed, 78 insertions(+), 2 deletions(-) (limited to 'documentation') 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 @@ <filename>build/tmp/stamps/</filename> - 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, -- cgit v1.2.3-54-g00ecf