tcslog-tools 0.1.8

Command-line tools for inspecting tcslog segment files: tcslog-dump and tcslog-dumphdr
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

# tcslog-tools 0.1.8

The library requirement, and the documentation that names it. Neither tool
changed -- not an option, not a line of output, and not which stored
segment file formats a build understands -- so a dependent upgrading from
0.1.7 sees no difference in what the binaries do.

The `tcslog` requirement moves from 0.3 to 0.4. That release added a field
to `Record`, the value `LogRead::iter` yields, saying whether the record is
a whole one or only its front. It breaks a caller that builds a `Record`
with a struct literal or destructures one exhaustively, and the requirement
moves only because a caret requirement on 0.3 does not match 0.4. A copy
built against `tcslog` 0.3, or 0.2, is equally correct and goes on working.

**The change does not reach these tools, and the reason is worth stating,
because the library release it comes from is a fix to exactly the behaviour
`tcslog-dump` reports on.** Both tools read through `LogRead::read` into a
buffer of their own; neither names `Record`, and neither calls the iterator.
What 0.4.0 fixed was the iterator handing partial records back unmarked, so
that a caller could not tell the front of a record from the whole of one.
`read` never had that problem: a record cut short arrives as
`ReadTruncated` carrying the bytes recovered, and `tcslog-dump` has always
printed those marked, with the lost-file count beside them. So the library
grew a way to say through the iterator what these tools were already saying
through `read`.

This is the release that puts the requirement and the documentation on
crates.io, `tcslog` 0.4.0 now being published; the requirement was already
correct in the repository and could not resolve from the registry until
that happened.

Requires `tcslog` 0.4.

### Changed

- The `tcslog` requirement becomes 0.4. That release adds a field to
  `Record`, the value `LogRead::iter` yields, which breaks a caller that
  constructs or exhaustively destructures one. Neither tool does either:
  both read through `LogRead::read` into a buffer of their own, and neither
  names `Record` at all. Nothing in either binary changes, and the records
  they read are the same records, the stored format being unchanged at
  0.1.0.

  The new field says whether the record handed back is a whole one or only
  its front. `tcslog-dump` already reports that distinction, because `read`
  always made it: a record cut short arrives as `ReadTruncated` carrying the
  bytes recovered, and the tool prints them marked. What 0.4.0 fixes is the
  iterator, which handed partial records over unmarked -- an interface these
  tools never used.

  The requirement still has to move, because a caret requirement on 0.3 does
  not match 0.4. A build of these tools against `tcslog` 0.3 is equally
  correct and will go on working for anyone who has one; this says which
  release they are built against from here.

- The manual's prerequisites and the README name 0.4 as the library version
  these tools are built against, as 0.1.7 had them name 0.3. The
  prerequisites now account for both of the library's breaking changes
  rather than only the first, since a reader who meets either in the
  library's own documentation has reason to ask whether it reaches these
  tools. Neither does: `WriteCallbacks` is on the writing side, which is not
  compiled here, and `Record` is what the iterator yields, which neither tool
  uses.

### Notes

- Which stored segment file formats a build of these tools understands
  follows from the `tcslog` version it was built against rather than from
  this crate's: a build reads a file whose major format version matches the
  library's and whose minor version is no greater. That stayed at 0.1.0
  across the library's 0.4.0, so a build of these tools reads every log any
  `tcslog` release has written.
- Installing: `cargo install tcslog-tools`, or `make install` from a
  checkout. The tools' own documentation is `docs/tcslog-tools.rst`; the log
  format they read and the recovery rules they report on are the library's,
  in `docs/tcslog.rst` of the `tcslog` repository.
- The error-recovery suite in the `tcslog` repository drives both binaries
  from a sibling checkout and compares their output against stored files,
  which is what establishes that this release changed none of it.
- Requires Rust 1.75 or later. Dual licensed under MIT OR Apache-2.0.