From: Sergey Matveev Date: Tue, 22 Jun 2021 11:29:04 +0000 (+0300) Subject: Full documentation X-Git-Tag: v1.7.0~2 X-Git-Url: http://www.git.cypherpunks.ru/?p=goredo.git;a=commitdiff_plain;h=b3dd8c5cdab414de32a69956b54f0d5e4fdcfeb8 Full documentation --- diff --git a/dep.go b/dep.go index bbd7310..0309eff 100644 --- a/dep.go +++ b/dep.go @@ -130,7 +130,7 @@ func writeDeps(fdDep *os.File, tgts []string) (err error) { if _, errStat := os.Stat(tgt); errStat == nil { err = writeDep(fdDep, tgtDir, tgtRel) } else { - trace(CDebug, "ifchange: %s <- %s (unexisting)", fdDep.Name(), tgtRel) + trace(CDebug, "ifchange: %s <- %s (non-existing)", fdDep.Name(), tgtRel) fields := []recfile.Field{ {Name: "Type", Value: DepTypeIfchange}, {Name: "Target", Value: tgtRel}, diff --git a/doc/cmds.texi b/doc/cmds.texi index 6e5fc2f..d76bf65 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -1,35 +1,93 @@ @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}): @@ -49,7 +107,6 @@ default.do ../default.o.do ../default.do @end example - @item redo-dot Dependency @url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT} diff --git a/doc/faq.texi b/doc/faq.texi index 2098b77..3bf832e 100644 --- a/doc/faq.texi +++ b/doc/faq.texi @@ -4,8 +4,8 @@ @anchor{Stamping} @section Hashing and stamping -All targets are checksummed if no @env{REDO_INODE_NO_TRUST} environment -variable is set and target's @file{ctime} differs from the previous one. +All targets are checksummed if target's @file{ctime} differs from the +previous one, or @env{REDO_INODE_NO_TRUST} environment variable is set. @command{apenwarr/redo} gives @url{https://redo.readthedocs.io/en/latest/FAQImpl/#why-not-always-use-checksum-based-dependencies-instead-of-timestamps, many reasons} why every time checksumming is bad, but in my opinion in practice all of diff --git a/doc/features.texi b/doc/features.texi index 843222d..df1778b 100644 --- a/doc/features.texi +++ b/doc/features.texi @@ -1,6 +1,9 @@ @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}: @@ -14,11 +17,11 @@ 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 diff --git a/doc/index.texi b/doc/index.texi index f84fc4d..c7aa0eb 100644 --- a/doc/index.texi +++ b/doc/index.texi @@ -47,6 +47,7 @@ maillist. Announcements also go to this mailing list. @include features.texi @include notes.texi +@include rules.texi @include cmds.texi @include news.texi @include install.texi diff --git a/doc/notes.texi b/doc/notes.texi index 4922f71..84de611 100644 --- a/doc/notes.texi +++ b/doc/notes.texi @@ -1,6 +1,9 @@ @node Notes @unnumbered Implementation notes +Since there are no strict rules about redo behaviour, here are some +remarks about @command{goredo}'s one: + @itemize @item @file{all} target is default