README

   1 *goredo* redo implementation on pure Go
   2
   3 OVERVIEW                                               *goredo-overview*
   4
   5 This is pure Go implementation of DJB's redo (http://cr.yp.to/redo.html)
   6 build system proposal. Originally it was just a rewrite of redo-c
   7 (https://github.com/leahneukirchen/redo-c), but later most features of
   8 apenwarr/redo (https://redo.readthedocs.io/en/latest/) were also
   9 implemented. Why yet another implementation? It is feature full and has
  10 better performance comparing to shell and Python implementation.
  11
  12 goredo is free software: see the file COPYING for copying conditions.
  13 Home page: http://www.goredo.cypherpunks.ru/
  14
  15 INSTALL                                                 *goredo-install*
  16  >
  17     $ go get go.cypherpunks.ru/goredo
  18     $ goredo -symlinks
  19     $ export PATH=`pwd`:$PATH
  20
  21 If you have problems with *.golang.org's unability to verify
  22 authenticity of go.cypherpunks.ru TLS connection, then you can disable
  23 their usage by setting GOPRIVATE=go.cypherpunks.ru. If you still have
  24 problems with the authenticity on your side, then build it manually: >
  25
  26     $ git clone git://git.cypherpunks.ru/goredo.git
  27     $ cd goredo
  28     $ git tag -v v0.2.0
  29     $ git clone git://git.cypherpunks.ru/gorecfile.git
  30     $ ( cd gorecfile ; git tag -v v0.3.0 )
  31     $ echo "replace go.cypherpunks.ru/recfile => `pwd`/gorecfile" >> go.mod
  32     $ go build
  33     $ ./goredo -symlinks
  34     $ export PATH=`pwd`:$PATH
  35
  36 NOTES                                                     *goredo-notes*
  37
  38 * "all" target is default
  39 * stdout is always captured, but no target is created if it was empty
  40 * empty targets are considered always out of date
  41 * .do's $3 is relative path to the file in same directory
  42 * .do search goes up to / by default, but can be limited with either
  43   $REDO_TOP_DIR environment variable, or by having .redo/top file in it
  44 * target's completion messages are written after they finish
  45 * executable .do is run as is, non-executable is run with /bin/sh -e[x]
  46 * tracing (-x) can be done only for non-executable .do
  47
  48 FEATURES                                               *goredo-features*
  49
  50 * explicit useful and convenient checks from apenwarr/redo:
  51     * check that $1 was not touched during .do execution
  52     * check that stdout and $3 are not written simultaneously
  53     * check that generated target was not modified "externally" outside
  54       the redo, preventing its overwriting, but continuing the build
  55 * targets, dependency information and their directories are explicitly
  56   synced (can be disabled, should work faster)
  57 * file's change is detected by comparing its ctime and BLAKE2b hash
  58 * files creation is umask-friendly (unlike mkstemp() used in redo-c)
  59 * parallel build with jobs limit, optionally in infinite mode
  60 * coloured messages (can be disabled)
  61 * verbose debug messages, including out-of-date determination, PIDs,
  62   lock and jobserver acquirings/releases
  63 * displaying of each target's execution time
  64 * each target's stderr can be prefixed with the PID
  65 * optional statusline with currently running/waiting/done jobs
  66 * target's stderr can be stored on the disk with TAI64N timestamp
  67   prefixes for each line. To convert them to localtime you can use either
  68   tai64nlocal utility from daemontools (http://cr.yp.to/daemontools.html)
  69   or make a symlink, to use built-in slower decoder: >
  70     $ ln -s goredo tai64nlocal
  71
  72 COMMANDS                                               *goredo-commands*
  73
  74 * redo-ifchange, redo-ifcreate, redo-always
  75 * redo -- same as redo-ifchange, but forcefully and sequentially run
  76   specified targets
  77 * redo-log -- display TAI64N timestamped last stderr of the target
  78 * redo-stamp -- record stamp dependency. Nothing more, dummy
  79 * redo-cleanup -- removes either temporary, log files, or everything
  80   related to goredo
  81 * redo-whichdo -- .do search paths for specified target (similar to
  82   apenwarr/redo): >
  83     $ redo-whichdo x/y/a.b.o
  84     x/y/a.b.o.do
  85     x/y/default.b.o.do
  86     x/y/default.o.do
  87     x/y/default.do
  88     x/default.b.o.do
  89     x/default.o.do
  90     x/default.do
  91     default.b.o.do
  92     default.o.do
  93     default.do
  94     ../default.b.o.do
  95     ../default.o.do
  96 * redo-dot -- dependency DOT graph generator. For example to visualize
  97   your dependencies with GraphViz: >
  98     $ redo target [...] # to assure that **/.redo/*.dep are filled up
  99     $ redo-dot target [...] > whatever.dot
 100     $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
 101
 102 FAQ                                                         *goredo-faq*
 103
 104     Hashing and stamping~
 105
 106 All targets are checksummed if their ctime differs from the previous
 107 one. apenwarr/redo gives many reasons why every time checksumming is
 108 bad, but in my opinion in practice all of them do not apply.
 109
 110 * Aggregate targets and willing to be out-of-date ones just must not
 111   produce empty output files. apenwarr/*, redo-c and goredo
 112   implementations consider non existing file as an out-of-date target
 113 * If you really wish to produce an empty target file, just touch $3
 114
 115 DJB's proposal with both stdout and $3 gives that ability to control
 116 your desired behaviour. Those who does not capture stdout -- failed.
 117 Those who creates an empty file if no stdout was written -- failed.
 118
 119 redo is a tool to help people. Literally all targets can be safely
 120 "redo-stamp < $3"-ed, reducing false positive out-of-dates. Of course,
 121 with the correct stdout/$3 working and placing necessary results in $3,
 122 instead of just silently feeding them in redo-stamp.
 123
 124 redo implementations are already automatically record -ifchange on .do
 125 files and -ifcreate on non-existing .do files. So why they can not
 126 record redo-stamp the same way implicitly? No, Zen of Python does not
 127 applicable there, because -ifchange/-ifcreate contradict it already.
 128
 129 Modern cryptographic hash algorithms and CPUs are so fast, that even all
 130 read and writes to or from hard drive arrays can be easily checksummed
 131 and transparently compressed, as ZFS with LZ4 and Skein/BLAKE[23]
 132 algorithms demonstrate us.
 133
 134 goredo includes redo-stamp, that really records the stamp in the .dep
 135 file, but it does not play any role later. It is stayed just for
 136 compatibility.
 137
 138     Removed .do can lead to permanent errors of its non existence~
 139
 140 That is true, because dependency on it was recorded previously. Is it
 141 safe to assume that .do-less target now is an ordinary source-file? I
 142 have no confidence in such behaviour. So it is user's decision how to
 143 deal with it, probably it was just his inaccuracy mistake. If you really
 144 want to get rid of that dependency knowledge for foo/bar target, then
 145 just remove foo/.redo/bar.dep.
 146
 147 STATE                                                     *goredo-state*
 148
 149 Dependency and build state is kept inside .redo subdirectory in each
 150 directory related the build. Each corresponding target has its own,
 151 recreated with every rebuild, .dep file. It is recfile
 152 (https://www.gnu.org/software/recutils/), that could have various
 153 dependency information (dep.rec with the schema included): >
 154
 155     Build: 80143f04-bfff-4673-950c-081d712f573d
 156
 157     Type: ifcreate
 158     Target: foo.o.do
 159
 160     Type: ifchange
 161     Target: default.o.do
 162     Ctime: 1605721341.253305000
 163     Hash: f4929732f96f11e6d4ebe94536b5edef426d00ed0146853e37a87f4295e18eda
 164
 165     Type: always
 166
 167     Type: stamp
 168     Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9
 169
 170 USAGE                                                     *goredo-usage*
 171
 172 Run any of the command above with the -help.
 173
 174 LICENCE~
 175
 176 This program is free software: you can redistribute it and/or modify
 177 it under the terms of the GNU General Public License as published by
 178 the Free Software Foundation, version 3 of the License.
 179
 180 This program is distributed in the hope that it will be useful,
 181 but WITHOUT ANY WARRANTY; without even the implied warranty of
 182 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 183 GNU General Public License for more details.
 184
 185  vim: filetype=help