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