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