X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcmds.texi;h=b3e19d7802d57d64366d91cb681551845c4b4cf6;hb=240e970cd64ca6465469af669e6b6333550ff520;hp=4c396093c4651ab969f1965fa90ccb8cfce0f10a;hpb=2e85fe511f4f0410e4b8a1dcdb127396b7f3f7c0;p=goredo.git diff --git a/doc/cmds.texi b/doc/cmds.texi index 4c39609..b3e19d7 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -5,14 +5,19 @@ 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. + +@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. + +@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 @@ -23,59 +28,75 @@ 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. -With @option{-k} (@env{$REDO_LOGS=1}) option you can capture job's -@code{stderr} on the disk and read it later with @command{redo-log} -command. Log's lines have @url{http://cr.yp.to/libtai/tai64.html, -TAI64N} timestamp. You can decode it with @command{tai64nlocal} utility -from @url{http://cr.yp.to/daemontools.html, daemontools}, or similar -one: @code{go get go.cypherpunks.ru/tai64n/cmd/tai64nlocal}. -@option{-s} (@env{$REDO_SILENT=1}) omits @code{stderr} printing at -all, but you can still capture it with @option{-k}. +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. -@command{goredo} determines target is out-of-date by comparing its size, -@code{ctime} and content's hash, if @code{ctime} differs. Depending on -the filesystem you use, probably you can not trust its @code{ctime} -value at all. In that case you can set @env{$REDO_INODE_NO_TRUST=1} to -forcefully verify the hash. +@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. 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 @@ -85,9 +106,12 @@ There are other commands that could be found in other implementations too: And there are some maintenance and debug commands: @table @command +@pindex redo-cleanup @item redo-cleanup Removes either temporary (@option{tmp}), log files (@option{log}), 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}): @@ -107,6 +131,8 @@ default.do ../default.o.do ../default.do @end example + +@pindex redo-dot @item redo-dot Dependency @url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT} @@ -117,4 +143,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