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