doc/ood.texi

   1 @node OOD
   2 @cindex OOD
   3 @cindex checksum
   4 @unnumbered Out-of-date determination
   5
   6 The main task for build system is deciding if the target is out-of-date
   7 and needs rebuilding. The single most reliable way to do that is to
   8 compare file's content with previously recorded one. But that is too
   9 expensive.
  10
  11 So direct content storage/comparison can be replaced with
  12 collision-resistant hash function of enough length. @command{goredo}
  13 uses @url{https://github.com/BLAKE3-team/BLAKE3, BLAKE3} with 256-bit
  14 output for that purpose.
  15
  16 Also it stores file's size and its inode number. Obviously if size
  17 differs, then file's content too and there is no need to read and hash it.
  18
  19 @vindex REDO_INODE_TRUST
  20 But still it could be relatively expensive. So there are additional
  21 possible checks that can skip need of hash checking, based on some trust
  22 to the underlying filesystem and operating system behaviour, controlled
  23 by @env{$REDO_INODE_TRUST} environment variable value:
  24
  25 @table @env
  26
  27 @item $REDO_INODE_TRUST=none
  28 Do not trust filesystem at all, except for file's size knowledge.
  29 Most reliable mode.
  30
  31 @cindex time
  32 @item $REDO_INODE_TRUST=ctime
  33 Trust @code{ctime} value of file's inode. It should change every time
  34 inode is updated. If nothing is touched and @code{ctime} is the same,
  35 then assume that file was not modified and we do not try to read its
  36 content. Unfortunately @code{ctime} also changes if link count is
  37 updated and ownership, that could give false positive decision and force
  38 file's rereading.
  39
  40 @item $REDO_INODE_TRUST=mtime
  41 Trust @code{mtime} value of file's inode. It should change every time
  42 file's content is updated. But unfortunately there are
  43 @url{https://apenwarr.ca/log/20181113, many reasons} it won't.
  44
  45 @end table
  46
  47 @cindex mtime
  48 Pay attention that although @code{mtime} is considered harmful (link
  49 above), and is hardly acceptable in build system like Make, because it
  50 compares timestamps of two files, redo is satisfied only with the fact
  51 of its changing, so badly jumping clocks are not so devastating. Modern
  52 filesystem and operating systems with micro- and nano-seconds resolution
  53 timestamps should be pretty good choice for @env{$REDO_INODE_TRUST=mtime}.
  54 However GNU/Linux with @code{ext4} filesystem can easily have pretty big
  55 granularity of 10ms.
  56
  57 @command{goredo} uses @env{$REDO_INODE_TRUST=ctime} by default.
  58
  59 If you move your worktree to different place, then all @code{ctime}s
  60 (probably @code{mtime}s if you are inaccurate) will be also changed. OOD
  61 check will be much slower after that, because it has to fallback to
  62 content/hash checking all the time. You can use @command{redo-depfix}
  63 utility to rebuild dependency files.