]> Cypherpunks.ru repositories - goredo.git/blobdiff - faq.texi
Texinfo-ed documentation and tarballs preparation
[goredo.git] / faq.texi
diff --git a/faq.texi b/faq.texi
new file mode 100644 (file)
index 0000000..02ea26b
--- /dev/null
+++ b/faq.texi
@@ -0,0 +1,75 @@
+@node FAQ
+@unnumbered FAQ
+
+@anchor{Stamping}
+@section Hashing and stamping
+
+All targets are checksummed if their @file{ctime} differs from the
+previous one. @command{apenwarr/redo} gives many reasons why every time
+checksumming is bad, but in my opinion in practice all of them do not
+apply.
+
+@itemize
+@item Aggregate targets and willing to be out-of-date ones just must not
+  produce empty output files. @command{apenwarr/*}, @command{redo-c} and
+  @command{goredo} implementations consider non existing file as an
+  out-of-date target
+@item If you really wish to produce an empty target file, just touch @file{$3}
+@end itemize
+
+DJB's proposal with both @file{stdout} and @file{$3} gives that ability
+to control your desired behaviour. Those who does not capture
+@file{stdout} -- failed. Those who creates an empty file if no
+@file{stdout} was written -- failed.
+
+redo is a tool to help people. Literally all targets can be safely
+@code{redo-stamp < $3}-ed, reducing false positive out-of-dates. Of
+course, with the correct @file{stdout}/@file{$3} working and placing
+necessary results in @file{$3}, instead of just silently feeding them in
+redo-stamp.
+
+redo implementations are already automatically record -ifchange on
+@file{.do} files and -ifcreate on non-existing @file{.do} files. So why
+they can not record redo-stamp the same way implicitly? No, Zen of
+Python does not applicable there, because -ifchange/-ifcreate contradict
+it already.
+
+Modern cryptographic hash algorithms and CPUs are so fast, that even all
+read and writes to or from hard drive arrays can be easily checksummed
+and transparently compressed, as ZFS with LZ4 and Skein/BLAKE[23]
+algorithms demonstrate us.
+
+@command{goredo} includes @command{redo-stamp}, that really records the
+stamp in the @file{.dep} file, but it does not play any role later. It
+is stayed just for compatibility.
+
+@section Can removed .do lead to permanent errors of its non existence?
+
+Yes, because dependency on it was recorded previously. Is it safe to
+assume that @file{.do}-less target now is an ordinary source-file? I
+have no confidence in such behaviour. So it is user's decision how to
+deal with it, probably it was just his inaccuracy mistake. If you really
+want to get rid of that dependency knowledge for @file{foo/bar} target,
+then just remove @file{foo/.redo/bar.dep}.
+
+@section Does redo-always always rebuilds target?
+
+@command{goredo}, together with @command{apenwarr/redo}, rebuilds target
+once per @strong{run}.
+Always rebuilds during every redo invocation, but only once during it
+building.
+@url{http://news.dieweltistgarnichtso.net/bin/redo-sh.html#why-built-twice, redo-sh}
+has other opinion, that is why its @file{redo-sh.tests/always_rebuild_1}
+will fail. Rebuilding of always-ed targets even during the same build
+process ruins any redo's usability in practice.
+
+For example if my @file{.h} file contains source code's version number,
+that is @command{git describe}'s output and all my other files depends
+on that header, then any @command{redo-ifchange} of @file{.o} will lead
+to @command{git describe} execution, that is rather heavy. Of course,
+because of either hashing or possible @command{redo-stamp}-ing its
+dependants won't be rebuilt further, but build time will be already
+ruined. If you need to rebuild TeX documents (case mentioned in
+redo-sh's FAQ) until all references and numbers are ready, then you must
+naturally expectedly explicitly use while cycle in your @file{.do}, as
+@command{apenwarr/redo} already suggests.