ceph/src/zstd/doc/educational_decoder/README.md

   1 Educational Decoder
   2 ===================
   3
   4 `zstd_decompress.c` is a self-contained implementation in C99 of a decoder,
   5 according to the [Zstandard format specification].
   6 While it does not implement as many features as the reference decoder,
   7 such as the streaming API or content checksums, it is written to be easy to
   8 follow and understand, to help understand how the Zstandard format works.
   9 It's laid out to match the [format specification],
  10 so it can be used to understand how complex segments could be implemented.
  11 It also contains implementations of Huffman and FSE table decoding.
  12
  13 [Zstandard format specification]: https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md
  14 [format specification]: https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md
  15
  16 While the library's primary objective is code clarity,
  17 it also happens to compile into a small object file.
  18 The object file can be made even smaller by removing error messages,
  19 using the macro directive `ZDEC_NO_MESSAGE` at compilation time.
  20 This can be reduced even further by foregoing dictionary support,
  21 by defining `ZDEC_NO_DICTIONARY`.
  22
  23 `harness.c` provides a simple test harness around the decoder:
  24
  25     harness <input-file> <output-file> [dictionary]
  26
  27 As an additional resource to be used with this decoder,
  28 see the `decodecorpus` tool in the [tests] directory.
  29 It generates valid Zstandard frames that can be used to verify
  30 a Zstandard decoder implementation.
  31 Note that to use the tool to verify this decoder implementation,
  32 the --content-size flag should be set,
  33 as this decoder does not handle streaming decoding,
  34 and so it must know the decompressed size in advance.
  35
  36 [tests]: https://github.com/facebook/zstd/blob/dev/tests/