From 20471d1200d79e9a8e4926255e9eabd8dbe3a0b5 Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Sat, 7 Oct 2023 22:57:38 +0300
Subject: [PATCH] Prepare for release

---
 doc/cmds.texi  | 12 +++++++--
 doc/faq.texi   |  4 +--
 doc/news.texi  | 40 ++++++++++++++++++++++++++++
 doc/state.texi | 71 +++++++++++++++++++++++++++++++++++++++++++++++---
 usage.go       |  4 +++
 5 files changed, 123 insertions(+), 8 deletions(-)

diff --git a/doc/cmds.texi b/doc/cmds.texi
index 8beb84c..72d1238 100644
--- a/doc/cmds.texi
+++ b/doc/cmds.texi
@@ -139,7 +139,7 @@ default.do
     @url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT}
     graph generator. For example to visualize your dependencies with GraphViz:
 @example
-$ redo target [...] # to assure that **/.redo/*.rec are filled up
+$ redo target [...] # to assure that **/.redo/*.dep are filled up
 $ redo-dot target [...] > whatever.dot
 $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
 @end example
@@ -152,6 +152,14 @@ $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho
     rereading the whole files for hash calculation, that is much slower.
     If you do not want to rebuild your targets from the ground, then
     @command{redo-depfix} can traverse through all dependency files and
-    check if they have non-altered ctime values and update them in place.
+    recalculate dependency information.
+
+    Also if it finds legacy @command{.rec} dependency files, it converts
+    them to binary format.
+
+@pindex redo-dep2rec
+@item redo-dep2rec
+    Convert specified @file{.dep} file to recfile on stdout.
+    Aimed to be used mainly for debugging purposes.
 
 @end table
diff --git a/doc/faq.texi b/doc/faq.texi
index 7fc12a0..7f65521 100644
--- a/doc/faq.texi
+++ b/doc/faq.texi
@@ -43,7 +43,7 @@ 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{.rec} file, but it does not play any role later. It
+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?
@@ -53,7 +53,7 @@ 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.rec}.
+then remove @file{foo/.redo/bar.dep}.
 
 @section Does redo-always always rebuilds target?
 
diff --git a/doc/news.texi b/doc/news.texi
index cdaac28..ec0d5e8 100644
--- a/doc/news.texi
+++ b/doc/news.texi
@@ -2,6 +2,46 @@
 @cindex news
 @unnumbered News
 
+@anchor{Release 2_0_0}
+@section Release 2.0.0
+@itemize
+@item
+Huge quantity of performance optimisations.
+
+@item
+Fixed possible unexpected lock file closing.
+
+@item
+When resulting target has the same contents, it does not replace already
+existing one. That was done previously. But now it also copies the file's
+mode flags to the target (for example making it executable).
+
+@item
+If @command{redo-*} command runs under control of another (top-level)
+redo, then it does not parse the flags as options and treat each
+argument as a target, allowing passing the targets with dashes in the
+beginning.
+
+@item
+Prevented possible concurrent stderr writing by multiple running
+targets.
+
+@item
+@command{redo-depfix} command now always rewrites dependency files and
+calculates checksums of the files.
+
+@item
+Own binary format is used for dependency files (@file{.dep}), instead of
+recfile (@file{.rec}) one. It is several times smaller and much faster
+to parse. You must run @command{redo-depfix} to convert all existing
+@file{.redo/*.rec} files to that binary format.
+
+@item
+@command{redo-dep2rec} command appeared, that can convert @file{.dep} to
+recfile on stdout.
+
+@end itemize
+
 @anchor{Release 1_32_0}
 @section Release 1.32.0
 @itemize
diff --git a/doc/state.texi b/doc/state.texi
index 5b0e05c..0a3b3d8 100644
--- a/doc/state.texi
+++ b/doc/state.texi
@@ -5,9 +5,72 @@
 
 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{.rec} file. It is
-@url{https://www.gnu.org/software/recutils/, recfile}, that could have
-various dependency information. For example:
+recreated with every rebuild, binary @file{.dep} file.
+
+It starts with the header:
+
+@verbatim
+"GOREDO" || 0x01 || BuildUUID
+@end verbatim
+
+@code{0x01} is format's version number. @code{BuildUUID} is 128-bit UUID.
+
+After the header comes concatenation of length-prefixed chunks. Length
+is the length of the whole chunk, including the size of the encoded
+length itself. It is 16-bit big-endian integer. After the length comes
+single byte type of the chunk:
+
+@table @asis
+
+@item ifcreate
+
+@verbatim
+LEN || 0x01 || target
+@end verbatim
+
+@code{target} is UTF-8 encoded target's name.
+
+@item ifchange
+
+@verbatim
+LEN || 0x02 ||
+    size || inodeNum ||
+    ctimeSec || ctimeNsec ||
+    mtimeSec || mtimeNsec ||
+    hash || target
+@end verbatim
+
+@code{target} is UTF-8 encoded target's name.
+@code{hash} is 256-bit BLAKE3 hash.
+All other inode-related fields are 64-bit big-endian integers.
+
+@item always
+
+@verbatim
+LEN || 0x03
+@end verbatim
+
+@item stamp
+
+@verbatim
+LEN || 0x04 || hash
+@end verbatim
+
+@code{hash} is 256-bit BLAKE3 hash.
+
+@item ifchange-nonexistent
+
+@verbatim
+LEN || 0x05 || target
+@end verbatim
+
+@code{target} is UTF-8 encoded target's name.
+
+@end table
+
+That @file{.dep} file can be converted to human-readable
+@url{https://www.gnu.org/software/recutils/, recfile} format.
+For example:
 
 @example
 Build: 80143f04-bfff-4673-950c-081d712f573d
@@ -31,5 +94,5 @@ Type: stamp
 Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9
 @end example
 
-And the schema definition:
+And its schema definition:
 @verbatiminclude ../dep.rec
diff --git a/usage.go b/usage.go
index f14ad7e..f29b2b9 100644
--- a/usage.go
+++ b/usage.go
@@ -105,6 +105,10 @@ List all currently known out-of-date targets.`
 		d = `Usage: redo-affects target [...]
 
 List all targets that will be affected by changing the specified ones.`
+	case CmdNameRedoDep2Rec:
+		d = `Usage: redo-dep2rec .../.redo/file.dep
+
+Convert binary .dep file to recfile and write it to stdout.`
 	case CmdNameRedoDepFix:
 		d = `Usage: redo-depfix
 
-- 
2.44.0