doc/cmds.texi

   1 @node Commands
   2 @unnumbered Commands
   3
   4 There are three basic main commands, originally suggested by DJB in his
   5 articles:
   6
   7 @table @command
   8 @pindex redo
   9 @item redo
  10     Forcefully and sequentially build specified targets. This is the
  11     main command you will explicitly use from the command line. If no
  12     targets are given, then @file{all} target will be used by default.
  13
  14 @pindex redo-ifchange
  15 @item redo-ifchange
  16     Rebuild specified targets if they are out-of-date and record them as
  17     a dependency for the currently run target. This is the main command
  18     you will use in @file{.do} files.
  19
  20 @pindex redo-ifcreate
  21 @item redo-ifcreate
  22     Record the non-existent file dependency for the currently run
  23     target. Target will be rebuilt if any of the given files appear. Can
  24     be used only inside @file{.do} file.
  25 @end table
  26
  27 Pay attention that @command{redo-ifchange} enables parallel builds of
  28 the given targets, but ordinary @command{redo} is not: it builds
  29 specified targets sequentially and stops when error happens.
  30
  31 @cindex tracing
  32 @option{-x} option can be used to enable tracing (@code{set -x}) of the
  33 currently run shell script @file{.do} file. @option{-xx} option enables
  34 tracing for all invoked @file{.do} files further.
  35
  36 @cindex parallel build
  37 With @option{-j} option you can enable parallel builds, probably with an
  38 infinite number of workers (@code{=0}). Also you can set
  39 @env{$REDO_JOBS} to automatically apply that setting globally.
  40
  41 Read about @ref{Logs, log storage capabilities}.
  42
  43 @cindex debug
  44 @vindex REDO_LOG_PID
  45 @vindex REDO_DEBUG
  46 @option{-log-pid} (@env{$REDO_LOG_PID=1}) can be used to prefix job's
  47 @code{stderr} with the PID, that could be useful during parallel builds.
  48 @option{-d} (@env{$REDO_DEBUG=1}) enables debug messages.
  49
  50 @cindex progress
  51 @vindex REDO_NO_PROGRESS
  52 @vindex REDO_NO_STATUS
  53 @vindex NO_COLOR
  54 @option{-no-progress} (@env{$REDO_NO_PROGRESS=1}) and
  55 @option{-no-status} (@env{$REDO_NO_STATUS=1}) disable statusline and
  56 progress display. @env{$NO_COLOR=1} disables progress/debug messages
  57 colouring.
  58
  59 @cindex fsync
  60 @vindex REDO_NO_SYNC
  61 By default all build commands use @code{fsync} to assure data is reached
  62 the disk. You can disable its usage with @env{$REDO_NO_SYNC=1}
  63 environment variable, for speeding up the build process.
  64
  65 @vindex REDO_STOP_IF_MODIFIED
  66 If redo sees some target modified externally, then by default it warns
  67 user about that, does not build that target, but continues the build
  68 process further. That is convenient in most cases: you can build your
  69 project with manual targets alterings, without touching possibly more
  70 complicated @file{.do} files. With @env{$REDO_STOP_IF_MODIFIED=1} redo
  71 won't continue and will exit with failure message.
  72
  73 There are other commands that could be found in other implementations too:
  74
  75 @table @command
  76 @pindex redo-always
  77 @item redo-always
  78     Record current target as an always-do dependency. By definition it
  79     should be always build. @command{goredo} tries to build it once per
  80     @strong{run}.
  81
  82 @pindex redo-stamp
  83 @item redo-stamp
  84     Record "stamp" dependency. It reads @code{stdin} and stores its hash
  85     in the dependency database. It is not used anyhow, it is dummy. Read
  86     about @ref{Stamping, stamping} in the FAQ. It is left only for
  87     compatibility with some other implementations.
  88
  89 @pindex redo-targets
  90 @pindex redo-ood
  91 @item redo-targets, redo-ood
  92     Show all known targets, possibly limited by specified directories.
  93     @command{redo-ood} shows only the out-of-date ones.
  94
  95 @pindex redo-sources
  96 @item redo-sources
  97     Recursively show all source files the given targets depend on.
  98
  99 @pindex redo-affects
 100 @item redo-affects
 101     It is not in other distributions, but it is some kind of opposite of
 102     @command{redo-sources} -- shows the targets that will be affected by
 103     specified files change.
 104 @end table
 105
 106 And there are some maintenance and debug commands:
 107
 108 @table @command
 109 @pindex redo-cleanup
 110 @item redo-cleanup
 111     Removes either temporary (@option{tmp}), log files (@option{log}),
 112     lock files (@option{lock}), or everything related to @command{goredo}
 113     (@option{full}).
 114
 115 @pindex redo-whichdo
 116 @item redo-whichdo
 117     Display @file{.do} search paths for specified target (similar to
 118     @command{apenwarr/redo}):
 119 @example
 120 $ redo-whichdo x/y/a.b.o
 121 x/y/a.b.o.do
 122 x/y/default.b.o.do
 123 x/y/default.o.do
 124 x/y/default.do
 125 x/default.b.o.do
 126 x/default.o.do
 127 x/default.do
 128 default.b.o.do
 129 default.o.do
 130 default.do
 131 ../default.b.o.do
 132 ../default.o.do
 133 ../default.do
 134 @end example
 135
 136 @pindex redo-dot
 137 @item redo-dot
 138     Dependency
 139     @url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT}
 140     graph generator. For example to visualize your dependencies with GraphViz:
 141 @example
 142 $ redo target [...] # to assure that **/.redo/*.rec are filled up
 143 $ redo-dot target [...] > whatever.dot
 144 $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
 145 @end example
 146
 147 @pindex redo-depfix
 148 @item redo-depfix
 149     When you copy your worktree to different place, then copied files
 150     ctime will change. And because recorded dependency information
 151     differs from updated ctimes, out-of-date algorithm will fallback to
 152     rereading the whole files for hash calculation, that is much slower.
 153     If you do not want to rebuild your targets from the ground, then
 154     @command{redo-depfix} can traverse through all dependency files and
 155     check if they have non-altered ctime values and update them in place.
 156
 157 @end table