Bug 10172

Hello,

One thing I think trips many people up and that also confused me at first is
input signatures and stamp files. It's easy to get the impression that input
signatures are only used for the sstate cache and nothing else, and stamp files
become very hazy then too.

I suggest adding the following section before the existing '3.5.7. Setscene
Tasks and Shared State' section. It tries to straighten the concepts out.

  3.5.7. Stamp Files and 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 consists of the task's name and
  current [input checksum](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#checksums).
  (This assumes that
  [BB_SIGNATURE_HANDLER](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#var-BB_SIGNATURE_HANDLER)
  is "OEBasicHash", but this is almost always the case in modern 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, and otherwise the task is
  rerun.
  
  Note {
  The stamp mechanism is more general than the shared state (sstate) cache
  mechanism described below. BitBake avoids rerunning any task that has a valid
  stamp file, not just tasks that can be accelerated through the sstate cache.
  
  Note however that stamp files only serve as a marker that some work has been
  done and 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, meaning 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]](https://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#variable-flags)
  flag. Note that 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.


To make the new section easier to discover, some links could be added:

 * At the end of 6.2.19:

     See [3.5.7. Stamp Files and Rerunning of Tasks] for more information.

 * In the glossary entry for STAMP, in a separate paragraph before "See
   STAMPS_DIR, MULTIMACH_TARGET_SYS, ...":

     See [3.5.7. Stamp Files and Rerunning of Tasks] for more information.


Cheers,
Ulf