From e2bafe8e0da716b4909da1b192d06c92c4f6260d Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Mon, 11 Jan 2021 17:15:51 +0300 Subject: [PATCH] Various documentation changes --- doc/cmds.texi | 7 ++++--- doc/faq.texi | 25 ++++++++++++------------- doc/features.texi | 4 ++-- doc/notes.texi | 3 ++- doc/state.texi | 6 ++++-- 5 files changed, 24 insertions(+), 21 deletions(-) diff --git a/doc/cmds.texi b/doc/cmds.texi index 19cd5f0..1483b7f 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -6,11 +6,12 @@ @item redo-ifchange, redo-ifcreate, redo-always @item redo - Same as redo-ifchange, but forcefully and sequentially run specified - targets. + Same as @command{redo-ifchange}, but forcefully and sequentially run + specified targets. @item redo-log - Display TAI64N timestamped last @command{stderr} of the target. + Display @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamped + last @command{stderr} of the target. @item redo-stamp Record stamp dependency. Nothing more, dummy. Read about diff --git a/doc/faq.texi b/doc/faq.texi index 02ea26b..1c6def3 100644 --- a/doc/faq.texi +++ b/doc/faq.texi @@ -5,9 +5,10 @@ @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. +previous one. @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 +them do not apply. @itemize @item Aggregate targets and willing to be out-of-date ones just must not @@ -18,26 +19,26 @@ apply. @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 +to control your desired behaviour. Those who do not capture +@file{stdout} -- failed. Those who create 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. +@command{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. +they can not record @command{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. +and transparently compressed, as ZFS with LZ4/Zstandard 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 @@ -56,8 +57,6 @@ then just remove @file{foo/.redo/bar.dep}. @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 diff --git a/doc/features.texi b/doc/features.texi index 5d2b634..9145312 100644 --- a/doc/features.texi +++ b/doc/features.texi @@ -25,8 +25,8 @@ @item target's @file{stderr} can be stored on the disk with @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamp prefixes for each line. To convert them to localtime you can use either - tai64nlocal utility from @url{http://cr.yp.to/daemontools.html, - daemontools}, or similar one: + @command{tai64nlocal} utility from + @url{http://cr.yp.to/daemontools.html, daemontools}, or similar one: @code{go get go.cypherpunks.ru/tai64n/cmd/tai64nlocal} @end itemize diff --git a/doc/notes.texi b/doc/notes.texi index a74a001..4922f71 100644 --- a/doc/notes.texi +++ b/doc/notes.texi @@ -14,7 +14,8 @@ @item target's completion messages are written after they finish @item executable @file{.do} is run as is, non-executable is run with @code{/bin/sh -e[x]} -@item tracing (-x) can be obviously done only for non-executable @file{.do} +@item tracing (@option{-x}) can be obviously done only for + non-executable @file{.do} @item parallizable build is done only during @command{redo-ifchange} for human convenience: you can globally enable @env{REDO_JOBS}, but still do for example: @code{redo htmls infos index upload} diff --git a/doc/state.texi b/doc/state.texi index d4fa9db..5313ae1 100644 --- a/doc/state.texi +++ b/doc/state.texi @@ -5,8 +5,7 @@ Dependency and build state is kept inside @file{.redo} subdirectory in each directory related the build. Each corresponding target has its own, recreated with every rebuild, @file{.dep} file. It is @url{https://www.gnu.org/software/recutils/, recfile}, that could have -various dependency information (@file{dep.rec} with the schema -included): +various dependency information. For example: @example Build: 80143f04-bfff-4673-950c-081d712f573d @@ -24,3 +23,6 @@ Type: always Type: stamp Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9 @end example + +And the schema definition: +@verbatiminclude ../dep.rec -- 2.44.0