@node Commands
@unnumbered Commands
+There are three basic main commands, originally suggested by DJB in his
+articles:
+
@table @command
+@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
+ 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-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
-@item redo-ifchange, redo-ifcreate, redo-always
+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.
-@item redo
- Same as @command{redo-ifchange}, but forcefully and sequentially run
- specified targets.
+@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.
-@item redo-log
- Display @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamped
- last @command{stderr} of the target, captured before.
+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.
-@item redo-targets, redo-sources, redo-ood
- List known targets, sources and out-of-date targets. You can limit
- results by specifying explicit targets you are interested in.
- @command{redo-sources} shows all recursive source files given
- targets depend on.
+With @option{-logs} (@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{-silent} (@env{$REDO_SILENT=1}) omits @code{stderr} printing at
+all, but you can still capture it with @option{-logs}.
-@item redo-affects
- List all targets that will be affected by changing the specified ones.
+@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.
+
+@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.
+
+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.
+There are other commands that could be found in other implementations too:
+
+@table @command
+@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}.
@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.
+@item redo-targets, redo-ood
+ Show all known targets, possibly limited by specified directories.
+ @command{redo-ood} shows only the out-of-date ones.
+@item redo-sources
+ Recursively show all source files the given targets depend on.
+@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
-@item redo-cleanup
- Removes either temporary, log files, or everything related to
- @command{goredo}.
+And there are some maintenance and debug commands:
+@table @command
+@item redo-cleanup
+ Removes either temporary (@option{tmp}), log files (@option{log}),
+ or everything related to @command{goredo} (@option{full}).
@item redo-whichdo
Display @file{.do} search paths for specified target (similar to
@command{apenwarr/redo}):
../default.o.do
../default.do
@end example
-
@item redo-dot
Dependency
@url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT}
@node Features
@unnumbered Features
+Notable features that differentiate @command{goredo} from many other
+implementations.
+
@itemize
@item explicit useful and convenient checks from @command{apenwarr/redo}:
synced (can be disabled, should work faster)
@item file's change is detected by comparing its size, @code{ctime} (if
@env{REDO_INODE_NO_TRUST} environment variable is not set) and
- BLAKE3 hash
+ @url{https://github.com/BLAKE3-team/BLAKE3, BLAKE3} hash
@item files creation is @code{umask}-friendly (unlike @code{mkstemp()}
used in @command{redo-c})
@item parallel build with jobs limit, optionally in infinite mode
-@item coloured messages (can be disabled)
+@item optional coloured messages
@item verbose debug messages, including out-of-date determination, PIDs,
lock and jobserver acquirings/releases
@item displaying of each target's execution time