sys/contrib/zstd/README.md

   1 <p align="center"><img src="https://raw.githubusercontent.com/facebook/zstd/dev/doc/images/zstd_logo86.png" alt="Zstandard"></p>
   2
   3 __Zstandard__, or `zstd` as short version, is a fast lossless compression algorithm,
   4 targeting real-time compression scenarios at zlib-level and better compression ratios.
   5 It's backed by a very fast entropy stage, provided by [Huff0 and FSE library](https://github.com/Cyan4973/FiniteStateEntropy).
   6
   7 Zstandard's format is stable and documented in [RFC8878](https://datatracker.ietf.org/doc/html/rfc8878). Multiple independent implementations are already available.
   8 This repository represents the reference implementation, provided as an open-source dual [BSD](LICENSE) and [GPLv2](COPYING) licensed **C** library,
   9 and a command line utility producing and decoding `.zst`, `.gz`, `.xz` and `.lz4` files.
  10 Should your project require another programming language,
  11 a list of known ports and bindings is provided on [Zstandard homepage](http://www.zstd.net/#other-languages).
  12
  13 **Development branch status:**
  14
  15 [![Build Status][travisDevBadge]][travisLink]
  16 [![Build status][AppveyorDevBadge]][AppveyorLink]
  17 [![Build status][CircleDevBadge]][CircleLink]
  18 [![Build status][CirrusDevBadge]][CirrusLink]
  19 [![Fuzzing Status][OSSFuzzBadge]][OSSFuzzLink]
  20
  21 [travisDevBadge]: https://api.travis-ci.com/facebook/zstd.svg?branch=dev "Continuous Integration test suite"
  22 [travisLink]: https://travis-ci.com/facebook/zstd
  23 [AppveyorDevBadge]: https://ci.appveyor.com/api/projects/status/xt38wbdxjk5mrbem/branch/dev?svg=true "Windows test suite"
  24 [AppveyorLink]: https://ci.appveyor.com/project/YannCollet/zstd-p0yf0
  25 [CircleDevBadge]: https://circleci.com/gh/facebook/zstd/tree/dev.svg?style=shield "Short test suite"
  26 [CircleLink]: https://circleci.com/gh/facebook/zstd
  27 [CirrusDevBadge]: https://api.cirrus-ci.com/github/facebook/zstd.svg?branch=dev
  28 [CirrusLink]: https://cirrus-ci.com/github/facebook/zstd
  29 [OSSFuzzBadge]: https://oss-fuzz-build-logs.storage.googleapis.com/badges/zstd.svg
  30 [OSSFuzzLink]: https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:zstd
  31
  32 ## Benchmarks
  33
  34 For reference, several fast compression algorithms were tested and compared
  35 on a desktop running Ubuntu 20.04 (`Linux 5.11.0-41-generic`),
  36 with a Core i7-9700K CPU @ 4.9GHz,
  37 using [lzbench], an open-source in-memory benchmark by @inikep
  38 compiled with [gcc] 9.3.0,
  39 on the [Silesia compression corpus].
  40
  41 [lzbench]: https://github.com/inikep/lzbench
  42 [Silesia compression corpus]: http://sun.aei.polsl.pl/~sdeor/index.php?page=silesia
  43 [gcc]: https://gcc.gnu.org/
  44
  45 | Compressor name         | Ratio | Compression| Decompress.|
  46 | ---------------         | ------| -----------| ---------- |
  47 | **zstd 1.5.1 -1**       | 2.887 |   530 MB/s |  1700 MB/s |
  48 | [zlib] 1.2.11 -1        | 2.743 |    95 MB/s |   400 MB/s |
  49 | brotli 1.0.9 -0         | 2.702 |   395 MB/s |   450 MB/s |
  50 | **zstd 1.5.1 --fast=1** | 2.437 |   600 MB/s |  2150 MB/s |
  51 | **zstd 1.5.1 --fast=3** | 2.239 |   670 MB/s |  2250 MB/s |
  52 | quicklz 1.5.0 -1        | 2.238 |   540 MB/s |   760 MB/s |
  53 | **zstd 1.5.1 --fast=4** | 2.148 |   710 MB/s |  2300 MB/s |
  54 | lzo1x 2.10 -1           | 2.106 |   660 MB/s |   845 MB/s |
  55 | [lz4] 1.9.3             | 2.101 |   740 MB/s |  4500 MB/s |
  56 | lzf 3.6 -1              | 2.077 |   410 MB/s |   830 MB/s |
  57 | snappy 1.1.9            | 2.073 |   550 MB/s |  1750 MB/s |
  58
  59 [zlib]: http://www.zlib.net/
  60 [lz4]: http://www.lz4.org/
  61
  62 The negative compression levels, specified with `--fast=#`,
  63 offer faster compression and decompression speed
  64 at the cost of compression ratio (compared to level 1).
  65
  66 Zstd can also offer stronger compression ratios at the cost of compression speed.
  67 Speed vs Compression trade-off is configurable by small increments.
  68 Decompression speed is preserved and remains roughly the same at all settings,
  69 a property shared by most LZ compression algorithms, such as [zlib] or lzma.
  70
  71 The following tests were run
  72 on a server running Linux Debian (`Linux version 4.14.0-3-amd64`)
  73 with a Core i7-6700K CPU @ 4.0GHz,
  74 using [lzbench], an open-source in-memory benchmark by @inikep
  75 compiled with [gcc] 7.3.0,
  76 on the [Silesia compression corpus].
  77
  78 Compression Speed vs Ratio | Decompression Speed
  79 ---------------------------|--------------------
  80 ![Compression Speed vs Ratio](doc/images/CSpeed2.png "Compression Speed vs Ratio") | ![Decompression Speed](doc/images/DSpeed3.png "Decompression Speed")
  81
  82 A few other algorithms can produce higher compression ratios at slower speeds, falling outside of the graph.
  83 For a larger picture including slow modes, [click on this link](doc/images/DCspeed5.png).
  84
  85
  86 ## The case for Small Data compression
  87
  88 Previous charts provide results applicable to typical file and stream scenarios (several MB). Small data comes with different perspectives.
  89
  90 The smaller the amount of data to compress, the more difficult it is to compress. This problem is common to all compression algorithms, and reason is, compression algorithms learn from past data how to compress future data. But at the beginning of a new data set, there is no "past" to build upon.
  91
  92 To solve this situation, Zstd offers a __training mode__, which can be used to tune the algorithm for a selected type of data.
  93 Training Zstandard is achieved by providing it with a few samples (one file per sample). The result of this training is stored in a file called "dictionary", which must be loaded before compression and decompression.
  94 Using this dictionary, the compression ratio achievable on small data improves dramatically.
  95
  96 The following example uses the `github-users` [sample set](https://github.com/facebook/zstd/releases/tag/v1.1.3), created from [github public API](https://developer.github.com/v3/users/#get-all-users).
  97 It consists of roughly 10K records weighing about 1KB each.
  98
  99 Compression Ratio | Compression Speed | Decompression Speed
 100 ------------------|-------------------|--------------------
 101 ![Compression Ratio](doc/images/dict-cr.png "Compression Ratio") | ![Compression Speed](doc/images/dict-cs.png "Compression Speed") | ![Decompression Speed](doc/images/dict-ds.png "Decompression Speed")
 102
 103
 104 These compression gains are achieved while simultaneously providing _faster_ compression and decompression speeds.
 105
 106 Training works if there is some correlation in a family of small data samples. The more data-specific a dictionary is, the more efficient it is (there is no _universal dictionary_).
 107 Hence, deploying one dictionary per type of data will provide the greatest benefits.
 108 Dictionary gains are mostly effective in the first few KB. Then, the compression algorithm will gradually use previously decoded content to better compress the rest of the file.
 109
 110 ### Dictionary compression How To:
 111
 112 1. Create the dictionary
 113
 114    `zstd --train FullPathToTrainingSet/* -o dictionaryName`
 115
 116 2. Compress with dictionary
 117
 118    `zstd -D dictionaryName FILE`
 119
 120 3. Decompress with dictionary
 121
 122    `zstd -D dictionaryName --decompress FILE.zst`
 123
 124
 125 ## Build instructions
 126
 127 ### Makefile
 128
 129 If your system is compatible with standard `make` (or `gmake`),
 130 invoking `make` in root directory will generate `zstd` cli in root directory.
 131
 132 Other available options include:
 133 - `make install` : create and install zstd cli, library and man pages
 134 - `make check` : create and run `zstd`, tests its behavior on local platform
 135
 136 ### cmake
 137
 138 A `cmake` project generator is provided within `build/cmake`.
 139 It can generate Makefiles or other build scripts
 140 to create `zstd` binary, and `libzstd` dynamic and static libraries.
 141
 142 By default, `CMAKE_BUILD_TYPE` is set to `Release`.
 143
 144 ### Meson
 145
 146 A Meson project is provided within [`build/meson`](build/meson). Follow
 147 build instructions in that directory.
 148
 149 You can also take a look at [`.travis.yml`](.travis.yml) file for an
 150 example about how Meson is used to build this project.
 151
 152 Note that default build type is **release**.
 153
 154 ### VCPKG
 155 You can build and install zstd [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
 156
 157     git clone https://github.com/Microsoft/vcpkg.git
 158     cd vcpkg
 159     ./bootstrap-vcpkg.sh
 160     ./vcpkg integrate install
 161     ./vcpkg install zstd
 162
 163 The zstd port in vcpkg is kept up to date by Microsoft team members and community contributors.
 164 If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
 165
 166 ### Visual Studio (Windows)
 167
 168 Going into `build` directory, you will find additional possibilities:
 169 - Projects for Visual Studio 2005, 2008 and 2010.
 170   + VS2010 project is compatible with VS2012, VS2013, VS2015 and VS2017.
 171 - Automated build scripts for Visual compiler by [@KrzysFR](https://github.com/KrzysFR), in `build/VS_scripts`,
 172   which will build `zstd` cli and `libzstd` library without any need to open Visual Studio solution.
 173
 174 ### Buck
 175
 176 You can build the zstd binary via buck by executing: `buck build programs:zstd` from the root of the repo.
 177 The output binary will be in `buck-out/gen/programs/`.
 178
 179 ## Testing
 180
 181 You can run quick local smoke tests by executing the `playTest.sh` script from the `src/tests` directory.
 182 Two env variables `$ZSTD_BIN` and `$DATAGEN_BIN` are needed for the test script to locate the zstd and datagen binary.
 183 For information on CI testing, please refer to TESTING.md
 184
 185 ## Status
 186
 187 Zstandard is currently deployed within Facebook. It is used continuously to compress large amounts of data in multiple formats and use cases.
 188 Zstandard is considered safe for production environments.
 189
 190 ## License
 191
 192 Zstandard is dual-licensed under [BSD](LICENSE) and [GPLv2](COPYING).
 193
 194 ## Contributing
 195
 196 The `dev` branch is the one where all contributions are merged before reaching `release`.
 197 If you plan to propose a patch, please commit into the `dev` branch, or its own feature branch.
 198 Direct commit to `release` are not permitted.
 199 For more information, please read [CONTRIBUTING](CONTRIBUTING.md).