summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/closer-look.xml61
-rw-r--r--documentation/ref-manual/ref-structure.xml12
-rw-r--r--documentation/ref-manual/ref-variables.xml7
3 files changed, 78 insertions, 2 deletions
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 @@
1210 </para> 1210 </para>
1211 </section> 1211 </section>
1212 1212
1213 <section id='stamp-files-and-the-rerunning-of-tasks'>
1214 <title>Stamp Files and the Rerunning of Tasks</title>
1215
1216 <para>
1217 For each task that completes successfully, BitBake writes a
1218 stamp file into the
1219 <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>
1220 directory.
1221 The beginning of the stamp file's filename is determined by the
1222 <link linkend='var-STAMP'><filename>STAMP</filename></link>
1223 variable, and the end of the name consists of the task's name
1224 and current
1225 <ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksum</ulink>.
1226 <note>
1227 This naming scheme assumes that
1228 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink>
1229 is "OEBasicHash", which is almost always the case in
1230 current OpenEmbedded.
1231 </note>
1232 To determine if a task needs to be rerun, BitBake checks if a
1233 stamp file with a matching input checksum exists for the task.
1234 If such a stamp file exists, the task's output is assumed to
1235 exist and still be valid.
1236 If the file does not exist, the task is rerun.
1237 <note>
1238 <para>The stamp mechanism is more general than the shared
1239 state (sstate) cache mechanism described in the
1240 "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>"
1241 section.
1242 BitBake avoids rerunning any task that has a valid
1243 stamp file, not just tasks that can be accelerated through
1244 the sstate cache.</para>
1245 <para>However, you should realize that stamp files only
1246 serve as a marker that some work has been done and these
1247 files do not record task output.
1248 The actual task output would usually be somewhere in
1249 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1250 (e.g. in some recipe's
1251 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.)
1252 What the sstate cache mechanism adds is a way to cache task
1253 output that can then be shared between build machines.
1254 </para>
1255 </note>
1256 Since <filename>STAMPS_DIR</filename> is usually a subdirectory
1257 of <filename>TMPDIR</filename>, removing
1258 <filename>TMPDIR</filename> will also remove
1259 <filename>STAMPS_DIR</filename>, which means tasks will
1260 properly be rerun to repopulate <filename>TMPDIR</filename>.
1261 </para>
1262
1263 <para>
1264 If you want some task to always be considered "out of date",
1265 you can mark it with the
1266 <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink>
1267 varflag.
1268 If some other task depends on such a task, then that task will
1269 also always be considered out of date, which might not be what
1270 you want.
1271 </para>
1272 </section>
1273
1213 <section id='setscene-tasks-and-shared-state'> 1274 <section id='setscene-tasks-and-shared-state'>
1214 <title>Setscene Tasks and Shared State</title> 1275 <title>Setscene Tasks and Shared State</title>
1215 1276
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 @@
801 <title><filename>build/tmp/stamps/</filename></title> 801 <title><filename>build/tmp/stamps/</filename></title>
802 802
803 <para> 803 <para>
804 This directory holds information that BitBake uses for accounting purposes 804 This directory holds information that BitBake uses for
805 to track what tasks have run and when they have run. 805 accounting purposes to track what tasks have run and when they
806 have run.
806 The directory is sub-divided by architecture, package name, and 807 The directory is sub-divided by architecture, package name, and
807 version. 808 version.
808 Following is an example: 809 Following is an example:
@@ -812,6 +813,13 @@
812 Although the files in the directory are empty of data, 813 Although the files in the directory are empty of data,
813 BitBake uses the filenames and timestamps for tracking purposes. 814 BitBake uses the filenames and timestamps for tracking purposes.
814 </para> 815 </para>
816
817 <para>
818 For information on how BitBake uses stamp files to determine if
819 a task should be rerun, see the
820 "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"
821 section.
822 </para>
815 </section> 823 </section>
816 824
817 <section id='structure-build-tmp-log'> 825 <section id='structure-build-tmp-log'>
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
@@ -12620,6 +12620,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
12620 </para> 12620 </para>
12621 12621
12622 <para> 12622 <para>
12623 For information on how BitBake uses stamp files to determine
12624 if a task should be rerun, see the
12625 "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"
12626 section.
12627 </para>
12628
12629 <para>
12623 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>, 12630 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
12624 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, 12631 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
12625 <link linkend='var-PN'><filename>PN</filename></link>, 12632 <link linkend='var-PN'><filename>PN</filename></link>,