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 The project is provided as an open-source dual [BSD](LICENSE) and [GPLv2](COPYING) licensed **C** library,
   8 and a command line utility producing and decoding `.zst`, `.gz`, `.xz` and `.lz4` files.
   9 Should your project require another programming language,
  10 a list of known ports and bindings is provided on [Zstandard homepage](http://www.zstd.net/#other-languages).
  11
  12 **Development branch status:**
  13
  14 [![Build Status][travisDevBadge]][travisLink]
  15 [![Build status][AppveyorDevBadge]][AppveyorLink]
  16 [![Build status][CircleDevBadge]][CircleLink]
  17 [![Build status][CirrusDevBadge]][CirrusLink]
  18 [![Fuzzing Status][OSSFuzzBadge]][OSSFuzzLink]
  19
  20 [travisDevBadge]: https://travis-ci.org/facebook/zstd.svg?branch=dev "Continuous Integration test suite"
  21 [travisLink]: https://travis-ci.org/facebook/zstd
  22 [AppveyorDevBadge]: https://ci.appveyor.com/api/projects/status/xt38wbdxjk5mrbem/branch/dev?svg=true "Windows test suite"
  23 [AppveyorLink]: https://ci.appveyor.com/project/YannCollet/zstd-p0yf0
  24 [CircleDevBadge]: https://circleci.com/gh/facebook/zstd/tree/dev.svg?style=shield "Short test suite"
  25 [CircleLink]: https://circleci.com/gh/facebook/zstd
  26 [CirrusDevBadge]: https://api.cirrus-ci.com/github/facebook/zstd.svg?branch=dev
  27 [CirrusLink]: https://cirrus-ci.com/github/facebook/zstd
  28 [OSSFuzzBadge]: https://oss-fuzz-build-logs.storage.googleapis.com/badges/zstd.svg
  29 [OSSFuzzLink]: https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:zstd
  30
  31 ## Benchmarks
  32
  33 For reference, several fast compression algorithms were tested and compared
  34 on a server running Arch Linux (`Linux version 5.5.11-arch1-1`),
  35 with a Core i9-9900K CPU @ 5.0GHz,
  36 using [lzbench], an open-source in-memory benchmark by @inikep
  37 compiled with [gcc] 9.3.0,
  38 on the [Silesia compression corpus].
  39
  40 [lzbench]: https://github.com/inikep/lzbench
  41 [Silesia compression corpus]: http://sun.aei.polsl.pl/~sdeor/index.php?page=silesia
  42 [gcc]: https://gcc.gnu.org/
  43
  44 | Compressor name         | Ratio | Compression| Decompress.|
  45 | ---------------         | ------| -----------| ---------- |
  46 | **zstd 1.4.5 -1**       | 2.884 |   500 MB/s |  1660 MB/s |
  47 | zlib 1.2.11 -1          | 2.743 |    90 MB/s |   400 MB/s |
  48 | brotli 1.0.7 -0         | 2.703 |   400 MB/s |   450 MB/s |
  49 | **zstd 1.4.5 --fast=1** | 2.434 |   570 MB/s |  2200 MB/s |
  50 | **zstd 1.4.5 --fast=3** | 2.312 |   640 MB/s |  2300 MB/s |
  51 | quicklz 1.5.0 -1        | 2.238 |   560 MB/s |   710 MB/s |
  52 | **zstd 1.4.5 --fast=5** | 2.178 |   700 MB/s |  2420 MB/s |
  53 | lzo1x 2.10 -1           | 2.106 |   690 MB/s |   820 MB/s |
  54 | lz4 1.9.2               | 2.101 |   740 MB/s |  4530 MB/s |
  55 | **zstd 1.4.5 --fast=7** | 2.096 |   750 MB/s |  2480 MB/s |
  56 | lzf 3.6 -1              | 2.077 |   410 MB/s |   860 MB/s |
  57 | snappy 1.1.8            | 2.073 |   560 MB/s |  1790 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 in exchange for some loss in
  64 compression ratio compared to level 1, as seen in the table above.
  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 ## Status
 180
 181 Zstandard is currently deployed within Facebook. It is used continuously to compress large amounts of data in multiple formats and use cases.
 182 Zstandard is considered safe for production environments.
 183
 184 ## License
 185
 186 Zstandard is dual-licensed under [BSD](LICENSE) and [GPLv2](COPYING).
 187
 188 ## Contributing
 189
 190 The "dev" branch is the one where all contributions are merged before reaching "master".
 191 If you plan to propose a patch, please commit into the "dev" branch, or its own feature branch.
 192 Direct commit to "master" are not permitted.
 193 For more information, please read [CONTRIBUTING](CONTRIBUTING.md).