doc/cmds.texi | 7 ++++--- doc/faq.texi | 25 ++++++++++++------------- doc/features.texi | 4 ++-- doc/notes.texi | 3 ++- doc/state.texi | 6 ++++-- diff --git a/doc/cmds.texi b/doc/cmds.texi index 2af943508343cef7e25501ae9fc847ba8dd9fcb87c254df54cc424039d1b0c04..4aef55654486f0eab193ac713da79766d0d43c1c46394a7823f6fe1a9f5d4630 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 ea7bd5b2995222c760bd0400aeebdd90297959590e459557b5108fdd18d3183e..72555885f5a3c11e4dc55bdc06bcc6a561c7ca72916dc7561f2825ad9b0bc616 100644 --- a/doc/faq.texi +++ b/doc/faq.texi @@ -5,9 +5,10 @@ @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. +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 @@ @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 +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 @@ @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 diff --git a/doc/features.texi b/doc/features.texi index 9a35356d4475efe6cfb1858931df6a75c41823c5df4ec231aa97bb1144f58976..47296e440a4c0c8b74719dbcaac6aeb03a3136277a1f82038aa948b0f1e610e7 100644 --- a/doc/features.texi +++ b/doc/features.texi @@ -25,8 +25,8 @@ @item optional statusline with currently running/waiting/done jobs @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 5a8746a22a3d1b01eb68438e4931d5a47684ea4d4241d8119700e947887b150a..98afac1bfcbdf3e0de77a39efa7d7618534452a33e108dc333a5e260109bb159 100644 --- a/doc/notes.texi +++ b/doc/notes.texi @@ -14,7 +14,8 @@ having @file{.redo/top} file in it @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 3bbe4f66c0f903dc58d3a62a6ed9ed59286e7a4488279e9e0cc66ba088096d7c..f978d8b14529d9596365a6c086c3e8566a48b121e6a21cabd73d62e8e6ca7470 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: stamp Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9 @end example + +And the schema definition: +@verbatiminclude ../dep.rec