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 goredo is free software: see the file COPYING for copying conditions.
  12
  13 INSTALL                                                 *goredo-install*
  14
  15 Either: >
  16     $ go get go.cypherpunks.ru/goredo
  17     $ goredo -symlinks
  18     $ export PATH=`pwd`:$PATH
  19 or: >
  20     $ git clone git://git.cypherpunks.ru/goredo.git
  21     $ cd goredo
  22     $ go build
  23     $ ./goredo -symlinks
  24     $ export PATH=`pwd`:$PATH
  25 <
  26 NOTES                                                     *goredo-notes*
  27
  28 * "all" target is used by default
  29 * stdout is always captured, but no target is created if it was empty
  30 * empty targets are considered always out of date
  31 * .do's arguments are relative paths
  32 * .do search goes up to / by default, but can be limited with either
  33   REDO_TOP_DIR environment variable, or by having .redo/top file in it
  34 * executable .do is run as is
  35 * shebangless .do is run with /bin/sh -e[x]
  36 * target's completion messages are written after they finish
  37
  38 FEATURES                                               *goredo-features*
  39
  40 * explicit useful and convenient checks from apenwarr/redo:
  41     * check that $1 was not touched during .do execution
  42     * check that stdout and $3 are not written simultaneously
  43     * check that generated target was not modified "externally" outside
  44       the redo, preventing its overwriting, but continuing the build
  45 * targets, dependency information and their directories are explicitly
  46   synced (can be disabled, should work faster)
  47 * file's change is detected by comparing its ctime and BLAKE2b hash
  48 * files creation is umask-friendly (unlike mkstemp() used in redo-c)
  49 * parallel build with jobs limit, optionally in infinite mode
  50 * coloured messages (can be disabled)
  51 * verbose debug messages, including out-of-date determination, PIDs,
  52   lock and jobserver acquirings/releases
  53 * displaying of each target's execution time
  54 * each target's stderr can be displayed with the PID
  55 * optional statusline with currently running/waiting/done jobs
  56 * target's stderr can be stored on the disk with TAI64N timestamp
  57   prefixes for each line. To convert them to localtime you can use either
  58   tai64nlocal utility from daemontools (http://cr.yp.to/daemontools.html)
  59   or make a symlink, to use built-in slower decoder: >
  60     $ ln -s goredo tai64nlocal
  61 <
  62 COMMANDS                                               *goredo-commands*
  63
  64 * redo-ifchange, redo-ifcreate, redo-always (useful with redo-stamp)
  65 * redo -- same as redo-ifchange, but forcefully and *sequentially* run
  66   specified targets
  67 * redo-log -- display TAI64N timestamped last stderr of the target
  68 * redo-stamp -- record stamp dependency. Nothing more, just dummy
  69 * redo-cleanup -- removes either temporary, or log files, or
  70   everything related to goredo
  71 * redo-whichdo -- .do search paths for specified target (similar to
  72   apenwarr/redo): >
  73     $ redo-whichdo x/y/a.b.o
  74     x/y/a.b.o.do
  75     x/y/default.b.o.do
  76     x/y/default.o.do
  77     x/y/default.do
  78     x/default.b.o.do
  79     x/default.o.do
  80     x/default.do
  81     default.b.o.do
  82     default.o.do
  83     default.do
  84     ../default.b.o.do
  85     ../default.o.do
  86 * redo-dot -- dependency DOT graph generator. For example to visualize
  87   your dependencies with GraphViz: >
  88     $ redo target [...] # to assure that .redo is filled up
  89     $ redo-dot target [...] > whatever.dot
  90     $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
  91 <
  92 STATE                                                     *goredo-state*
  93
  94 Dependency and build state is kept inside .redo subdirectory in each
  95 directory touched related the build. Each corresponding target has its
  96 own, recreated with every rebuild, .dep file. It is recfile
  97 (https://www.gnu.org/software/recutils/), that could have various
  98 dependency information (dep.rec with the schema included): >
  99
 100     Build: 80143f04-bfff-4673-950c-081d712f573d
 101
 102     Type: ifcreate
 103     Target: foo.o.do
 104
 105     Type: ifchange
 106     Target: default.o.do
 107     Ctime: 1605721341.253305000
 108     Hash: f4929732f96f11e6d4ebe94536b5edef426d00ed0146853e37a87f4295e18eda
 109
 110     Type: always
 111
 112     Type: stamp
 113     Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9
 114 <
 115 LICENCE~
 116
 117 This program is free software: you can redistribute it and/or modify
 118 it under the terms of the GNU General Public License as published by
 119 the Free Software Foundation, version 3 of the License.
 120
 121 This program is distributed in the hope that it will be useful,
 122 but WITHOUT ANY WARRANTY; without even the implied warranty of
 123 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 124 GNU General Public License for more details.
 125
 126  vim: filetype=help