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 inability 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.5.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     $ git clone git://git.cypherpunks.ru/gotai64n.git
  33     $ ( cd gotai64n ; git tag -v v0.2.0 )
  34     $ echo "replace go.cypherpunks.ru/tai64n => `pwd`/gotai64n" >> go.mod
  35     $ go build
  36     $ ./goredo -symlinks
  37     $ export PATH=`pwd`:$PATH
  38
  39 NOTES                                                     *goredo-notes*
  40
  41 * "all" target is default
  42 * stdout is always captured, but no target is created if it was empty
  43 * empty targets are considered always out of date
  44 * .do's $3 is relative path to the file in target directory
  45 * .do search goes up to / by default, but can be limited with either
  46   $REDO_TOP_DIR environment variable, or by having .redo/top file in it
  47 * target's completion messages are written after they finish
  48 * executable .do is run as is, non-executable is run with /bin/sh -e[x]
  49 * tracing (-x) can be done only for non-executable .do
  50
  51 FEATURES                                               *goredo-features*
  52
  53 * explicit useful and convenient checks from apenwarr/redo:
  54     * check that $1 was not touched during .do execution
  55     * check that stdout and $3 are not written simultaneously
  56     * check that generated target was not modified "externally" outside
  57       the redo, preventing its overwriting, but continuing the build
  58 * targets, dependency information and their directories are explicitly
  59   synced (can be disabled, should work faster)
  60 * file's change is detected by comparing its ctime and BLAKE2b hash
  61 * files creation is umask-friendly (unlike mkstemp() used in redo-c)
  62 * parallel build with jobs limit, optionally in infinite mode
  63 * coloured messages (can be disabled)
  64 * verbose debug messages, including out-of-date determination, PIDs,
  65   lock and jobserver acquirings/releases
  66 * displaying of each target's execution time
  67 * each target's stderr can be prefixed with the PID
  68 * optional statusline with currently running/waiting/done jobs
  69 * target's stderr can be stored on the disk with TAI64N timestamp
  70   prefixes for each line. To convert them to localtime you can use either
  71   tai64nlocal utility from daemontools (http://cr.yp.to/daemontools.html),
  72   or similar one: >
  73     $ go get go.cypherpunks.ru/tai64n/cmd/tai64nlocal
  74
  75 COMMANDS                                               *goredo-commands*
  76
  77 * redo-ifchange, redo-ifcreate, redo-always
  78 * redo -- same as redo-ifchange, but forcefully and sequentially run
  79   specified targets
  80 * redo-log -- display TAI64N timestamped last stderr of the target
  81 * redo-stamp -- record stamp dependency. Nothing more, dummy
  82 * redo-cleanup -- removes either temporary, log files, or everything
  83   related to goredo
  84 * redo-whichdo -- .do search paths for specified target (similar to
  85   apenwarr/redo): >
  86     $ redo-whichdo x/y/a.b.o
  87     x/y/a.b.o.do
  88     x/y/default.b.o.do
  89     x/y/default.o.do
  90     x/y/default.do
  91     x/default.b.o.do
  92     x/default.o.do
  93     x/default.do
  94     default.b.o.do
  95     default.o.do
  96     default.do
  97     ../default.b.o.do
  98     ../default.o.do
  99     ../default.do
 100 * redo-dot -- dependency DOT graph generator. For example to visualize
 101   your dependencies with GraphViz: >
 102     $ redo target [...] # to assure that **/.redo/*.dep are filled up
 103     $ redo-dot target [...] > whatever.dot
 104     $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
 105
 106 FAQ                                                         *goredo-faq*
 107
 108     Hashing and stamping~
 109
 110 All targets are checksummed if their ctime differs from the previous
 111 one. apenwarr/redo gives many reasons why every time checksumming is
 112 bad, but in my opinion in practice all of them do not apply.
 113
 114 * Aggregate targets and willing to be out-of-date ones just must not
 115   produce empty output files. apenwarr/*, redo-c and goredo
 116   implementations consider non existing file as an out-of-date target
 117 * If you really wish to produce an empty target file, just touch $3
 118
 119 DJB's proposal with both stdout and $3 gives that ability to control
 120 your desired behaviour. Those who does not capture stdout -- failed.
 121 Those who creates an empty file if no stdout was written -- failed.
 122
 123 redo is a tool to help people. Literally all targets can be safely
 124 "redo-stamp < $3"-ed, reducing false positive out-of-dates. Of course,
 125 with the correct stdout/$3 working and placing necessary results in $3,
 126 instead of just silently feeding them in redo-stamp.
 127
 128 redo implementations are already automatically record -ifchange on .do
 129 files and -ifcreate on non-existing .do files. So why they can not
 130 record redo-stamp the same way implicitly? No, Zen of Python does not
 131 applicable there, because -ifchange/-ifcreate contradict it already.
 132
 133 Modern cryptographic hash algorithms and CPUs are so fast, that even all
 134 read and writes to or from hard drive arrays can be easily checksummed
 135 and transparently compressed, as ZFS with LZ4 and Skein/BLAKE[23]
 136 algorithms demonstrate us.
 137
 138 goredo includes redo-stamp, that really records the stamp in the .dep
 139 file, but it does not play any role later. It is stayed just for
 140 compatibility.
 141
 142     Can removed .do lead to permanent errors of its non existence?~
 143
 144 Yes, because dependency on it was recorded previously. Is it safe to
 145 assume that .do-less target now is an ordinary source-file? I have no
 146 confidence in such behaviour. So it is user's decision how to deal with
 147 it, probably it was just his inaccuracy mistake. If you really want to
 148 get rid of that dependency knowledge for foo/bar target, then just
 149 remove foo/.redo/bar.dep.
 150
 151     Does redo-always always rebuilds target?~
 152
 153 goredo, together with apenwarr/redo, rebuilds target once per run.
 154 Always rebuilds during every redo invocation, but only once during it
 155 building. http://news.dieweltistgarnichtso.net/bin/redo-sh.html#why-built-twice
 156 has other opinion, that is why its redo-sh.tests/always_rebuild_1 will
 157 fail. Rebuilding of always-ed targets even during the same build process
 158 ruins any redo's usability in practice.
 159
 160 For example if my .h file contains source code's version number, that is
 161 git-describe's output and all my other files depends on that header,
 162 then any redo-ifchange of .o will lead to git-describe execution, that
 163 is rather heavy. Of course, because of either hashing or possible
 164 redo-stamp-ing its dependants won't be rebuilt further, but build time
 165 will be already ruined. If you need to rebuild TeX documents (case
 166 mentioned in redo-sh's FAQ) until all references and numbers are ready,
 167 then you must naturally expectedly explicitly use while cycle in your
 168 .do, as apenwarr/redo already suggests.
 169
 170 STATE                                                     *goredo-state*
 171
 172 Dependency and build state is kept inside .redo subdirectory in each
 173 directory related the build. Each corresponding target has its own,
 174 recreated with every rebuild, .dep file. It is recfile
 175 (https://www.gnu.org/software/recutils/), that could have various
 176 dependency information (dep.rec with the schema included): >
 177
 178     Build: 80143f04-bfff-4673-950c-081d712f573d
 179
 180     Type: ifcreate
 181     Target: foo.o.do
 182
 183     Type: ifchange
 184     Target: default.o.do
 185     Ctime: 1605721341.253305000
 186     Hash: f4929732f96f11e6d4ebe94536b5edef426d00ed0146853e37a87f4295e18eda
 187
 188     Type: always
 189
 190     Type: stamp
 191     Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9
 192
 193 USAGE                                                     *goredo-usage*
 194
 195 Run any of the command above with the -help.
 196
 197 LICENCE~
 198
 199 This program is free software: you can redistribute it and/or modify
 200 it under the terms of the GNU General Public License as published by
 201 the Free Software Foundation, version 3 of the License.
 202
 203 This program is distributed in the hope that it will be useful,
 204 but WITHOUT ANY WARRANTY; without even the implied warranty of
 205 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 206 GNU General Public License for more details.
 207
 208  vim: filetype=help