X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcmds.texi;h=8beb84cbebd7d14ac755614f8a7ab58b5fc6d2d9;hb=b4eefdd675c9aef9ff8bd1089d031ee05733195b;hp=abd09905baf2d0820745ed6224113046c7171e0b;hpb=5ca39bfc0b769607db3f84213fc7f16f0c4019fa;p=goredo.git

diff --git a/doc/cmds.texi b/doc/cmds.texi
index abd0990..8beb84c 100644
--- a/doc/cmds.texi
+++ b/doc/cmds.texi
@@ -1,26 +1,118 @@
 @node Commands
 @unnumbered Commands
 
+There are three basic main commands, originally suggested by DJB in his
+articles:
+
 @table @command
+@pindex redo
+@item redo
+    Forcefully and sequentially build specified targets. This is the
+    main command you will explicitly use from the command line. If no
+    targets are given, then @file{all} target will be used by default.
 
-@item redo-ifchange, redo-ifcreate, redo-always
+@pindex redo-ifchange
+@item redo-ifchange
+    Rebuild specified targets if they are out-of-date and record them as
+    a dependency for the currently run target. This is the main command
+    you will use in @file{.do} files.
 
-@item redo
-    Same as @command{redo-ifchange}, but forcefully and sequentially run
-    specified targets.
+@pindex redo-ifcreate
+@item redo-ifcreate
+    Record the non-existent file dependency for the currently run
+    target. Target will be rebuilt if any of the given files appear. Can
+    be used only inside @file{.do} file.
+@end table
+
+Pay attention that @command{redo-ifchange} enables parallel builds of
+the given targets, but ordinary @command{redo} is not: it builds
+specified targets sequentially and stops when error happens.
+
+@cindex tracing
+@option{-x} option can be used to enable tracing (@code{set -x}) of the
+currently run shell script @file{.do} file. @option{-xx} option enables
+tracing for all invoked @file{.do} files further.
+
+@cindex parallel build
+With @option{-j} option you can enable parallel builds, probably with an
+infinite number of workers (@code{=0}). Also you can set
+@env{$REDO_JOBS} to automatically apply that setting globally.
+
+Read about @ref{Logs, log storage capabilities}.
+
+@cindex debug
+@vindex REDO_LOG_PID
+@vindex REDO_DEBUG
+@option{-log-pid} (@env{$REDO_LOG_PID=1}) can be used to prefix job's
+@code{stderr} with the PID, that could be useful during parallel builds.
+@option{-d} (@env{$REDO_DEBUG=1}) enables debug messages.
+
+@cindex progress
+@vindex REDO_NO_PROGRESS
+@vindex REDO_NO_STATUS
+@vindex NO_COLOR
+@option{-no-progress} (@env{$REDO_NO_PROGRESS=1}) and
+@option{-no-status} (@env{$REDO_NO_STATUS=1}) disable statusline and
+progress display. @env{$NO_COLOR=1} disables progress/debug messages
+colouring.
+
+@cindex fsync
+@vindex REDO_NO_SYNC
+By default all build commands use @code{fsync} to assure data is reached
+the disk. You can disable its usage with @env{$REDO_NO_SYNC=1}
+environment variable, for speeding up the build process.
 
-@item redo-log
-    Display @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamped
-    last @command{stderr} of the target.
+@vindex REDO_STOP_IF_MODIFIED
+If redo sees some target modified externally, then by default it warns
+user about that, does not build that target, but continues the build
+process further. That is convenient in most cases: you can build your
+project with manual targets alterings, without touching possibly more
+complicated @file{.do} files. With @env{$REDO_STOP_IF_MODIFIED=1} redo
+won't continue and will exit with failure message.
 
+There are other commands that could be found in other implementations too:
+
+@table @command
+@pindex redo-always
+@item redo-always
+    Record current target as an always-do dependency. By definition it
+    should be always build. @command{goredo} tries to build it once per
+    @strong{run}.
+
+@pindex redo-stamp
 @item redo-stamp
-    Record stamp dependency. Nothing more, dummy. Read about
-    @ref{Stamping, stamping} in the FAQ.
+    Record "stamp" dependency. It reads @code{stdin} and stores its hash
+    in the dependency database. It is not used anyhow, it is dummy. Read
+    about @ref{Stamping, stamping} in the FAQ. It is left only for
+    compatibility with some other implementations.
+
+@pindex redo-targets
+@pindex redo-ood
+@item redo-targets, redo-ood
+    Show all known targets, possibly limited by specified directories.
+    @command{redo-ood} shows only the out-of-date ones.
+
+@pindex redo-sources
+@item redo-sources
+    Recursively show all source files the given targets depend on.
 
+@pindex redo-affects
+@item redo-affects
+    It is not in other distributions, but it is some kind of opposite of
+    @command{redo-sources} -- shows the targets that will be affected by
+    specified files change.
+@end table
+
+And there are some maintenance and debug commands:
+
+@table @command
+@pindex redo-cleanup
 @item redo-cleanup
-    Removes either temporary, log files, or everything related to
-    @command{goredo}.
+    Removes either temporary (@option{tmp}), log files (@option{log}),
+    lock files (@option{lock}), or everything related to @command{goredo}
+    (@option{full}).
 
+@pindex redo-whichdo
 @item redo-whichdo
     Display @file{.do} search paths for specified target (similar to
     @command{apenwarr/redo}):
@@ -41,6 +133,7 @@ default.do
 ../default.do
 @end example
 
+@pindex redo-dot
 @item redo-dot
     Dependency
     @url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT}
@@ -51,4 +144,14 @@ $ redo-dot target [...] > whatever.dot
 $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
 @end example
 
+@pindex redo-depfix
+@item redo-depfix
+    When you copy your worktree to different place, then copied files
+    ctime will change. And because recorded dependency information
+    differs from updated ctimes, out-of-date algorithm will fallback to
+    rereading the whole files for hash calculation, that is much slower.
+    If you do not want to rebuild your targets from the ground, then
+    @command{redo-depfix} can traverse through all dependency files and
+    check if they have non-altered ctime values and update them in place.
+
 @end table