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 With @option{-logs} (@env{$REDO_LOGS=1}) option you can capture job's
  35 @code{stderr} on the disk and read it later with @command{redo-log}
  36 command. Log's lines have @url{http://cr.yp.to/libtai/tai64.html,
  37 TAI64N} timestamp. You can decode it with @command{tai64nlocal} utility
  38 from @url{http://cr.yp.to/daemontools.html, daemontools}, or similar
  39 one: @code{go get go.cypherpunks.ru/tai64n/cmd/tai64nlocal}.
  40 @option{-silent} (@env{$REDO_SILENT=1}) omits @code{stderr} printing at
  41 all, but you can still capture it with @option{-logs}.
  42
  43 @option{-log-pid} (@env{$REDO_LOG_PID=1}) can be used to prefix job's
  44 @code{stderr} with the PID, that could be useful during parallel builds.
  45 @option{-d} (@env{$REDO_DEBUG=1}) enables debug messages.
  46
  47 @option{-no-progress} (@env{$REDO_NO_PROGRESS=1}) and
  48 @option{-no-status} (@env{$REDO_NO_STATUS=1}) disable statusline and
  49 progress display. @env{$NO_COLOR=1} disables progress/debug messages
  50 colouring.
  51
  52 By default all build commands use @code{fsync} to assure data is reached
  53 the disk. You can disable its usage with @env{$REDO_NO_SYNC=1}
  54 environment variable, for speeding up the build process.
  55
  56 @command{goredo} determines target is out-of-date by comparing its size,
  57 @code{ctime} and content's hash, if @code{ctime} differs. Depending on
  58 the filesystem you use, probably you can not trust its @code{ctime}
  59 value at all. In that case you can set @env{$REDO_INODE_NO_TRUST=1} to
  60 forcefully verify the hash.
  61
  62 There are other commands that could be found in other implementations too:
  63
  64 @table @command
  65 @item redo-always
  66     Record current target as an always-do dependency. By definition it
  67     should be always build. @command{goredo} tries to build it once per
  68     @strong{run}.
  69 @item redo-stamp
  70     Record "stamp" dependency. It reads @code{stdin} and stores its hash
  71     in the dependency database. It is not used anyhow, it is dummy. Read
  72     about @ref{Stamping, stamping} in the FAQ. It is left only for
  73     compatibility with some other implementations.
  74 @item redo-targets, redo-ood
  75     Show all known targets, possibly limited by specified directories.
  76     @command{redo-ood} shows only the out-of-date ones.
  77 @item redo-sources
  78     Recursively show all source files the given targets depend on.
  79 @item redo-affects
  80     It is not in other distributions, but it is some kind of opposite of
  81     @command{redo-sources} -- shows the targets that will be affected by
  82     specified files change.
  83 @end table
  84
  85 And there are some maintenance and debug commands:
  86
  87 @table @command
  88 @item redo-cleanup
  89     Removes either temporary (@option{tmp}), log files (@option{log}),
  90     or everything related to @command{goredo} (@option{full}).
  91 @item redo-whichdo
  92     Display @file{.do} search paths for specified target (similar to
  93     @command{apenwarr/redo}):
  94 @example
  95 $ redo-whichdo x/y/a.b.o
  96 x/y/a.b.o.do
  97 x/y/default.b.o.do
  98 x/y/default.o.do
  99 x/y/default.do
 100 x/default.b.o.do
 101 x/default.o.do
 102 x/default.do
 103 default.b.o.do
 104 default.o.do
 105 default.do
 106 ../default.b.o.do
 107 ../default.o.do
 108 ../default.do
 109 @end example
 110 @item redo-dot
 111     Dependency
 112     @url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT}
 113     graph generator. For example to visualize your dependencies with GraphViz:
 114 @example
 115 $ redo target [...] # to assure that **/.redo/*.rec are filled up
 116 $ redo-dot target [...] > whatever.dot
 117 $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
 118 @end example
 119
 120 @end table