NameDateSize

..12-May-201923

.buckconfig14-Nov-2017407

.buckversion14-Nov-201741

.gitattributes22-Oct-2018348

appveyor.yml25-May-202013.6 KiB

CHANGELOG25-May-202028.4 KiB

CONTRIBUTING.md25-May-202022 KiB

COPYING14-Nov-201717.7 KiB

doc/25-May-20207

examples/25-May-202014

FREEBSD-upgrade07-Nov-2019399

FREEBSD-Xlist25-May-2020109

lib/25-May-202014

LICENSE14-Nov-20171.5 KiB

Makefile25-May-202013.3 KiB

programs/25-May-202029

README.md25-May-20209.2 KiB

TESTING.md25-May-20201.8 KiB

zlibWrapper/25-May-202014

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,
4targeting real-time compression scenarios at zlib-level and better compression ratios.
5It's backed by a very fast entropy stage, provided by [Huff0 and FSE library](https://github.com/Cyan4973/FiniteStateEntropy).
6
7The project is provided as an open-source dual [BSD](LICENSE) and [GPLv2](COPYING) licensed **C** library,
8and a command line utility producing and decoding `.zst`, `.gz`, `.xz` and `.lz4` files.
9Should your project require another programming language,
10a 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
33For reference, several fast compression algorithms were tested and compared
34on a server running Arch Linux (`Linux version 5.5.11-arch1-1`),
35with a Core i9-9900K CPU @ 5.0GHz,
36using [lzbench], an open-source in-memory benchmark by @inikep
37compiled with [gcc] 9.3.0,
38on 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
62The negative compression levels, specified with `--fast=#`,
63offer faster compression and decompression speed in exchange for some loss in
64compression ratio compared to level 1, as seen in the table above.
65
66Zstd can also offer stronger compression ratios at the cost of compression speed.
67Speed vs Compression trade-off is configurable by small increments.
68Decompression speed is preserved and remains roughly the same at all settings,
69a property shared by most LZ compression algorithms, such as [zlib] or lzma.
70
71The following tests were run
72on a server running Linux Debian (`Linux version 4.14.0-3-amd64`)
73with a Core i7-6700K CPU @ 4.0GHz,
74using [lzbench], an open-source in-memory benchmark by @inikep
75compiled with [gcc] 7.3.0,
76on the [Silesia compression corpus].
77
78Compression 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
82A few other algorithms can produce higher compression ratios at slower speeds, falling outside of the graph.
83For a larger picture including slow modes, [click on this link](doc/images/DCspeed5.png).
84
85
86## The case for Small Data compression
87
88Previous charts provide results applicable to typical file and stream scenarios (several MB). Small data comes with different perspectives.
89
90The 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
92To solve this situation, Zstd offers a __training mode__, which can be used to tune the algorithm for a selected type of data.
93Training 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.
94Using this dictionary, the compression ratio achievable on small data improves dramatically.
95
96The 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).
97It consists of roughly 10K records weighing about 1KB each.
98
99Compression 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
104These compression gains are achieved while simultaneously providing _faster_ compression and decompression speeds.
105
106Training 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_).
107Hence, deploying one dictionary per type of data will provide the greatest benefits.
108Dictionary 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
1121. Create the dictionary
113
114   `zstd --train FullPathToTrainingSet/* -o dictionaryName`
115
1162. Compress with dictionary
117
118   `zstd -D dictionaryName FILE`
119
1203. Decompress with dictionary
121
122   `zstd -D dictionaryName --decompress FILE.zst`
123
124
125## Build instructions
126
127### Makefile
128
129If your system is compatible with standard `make` (or `gmake`),
130invoking `make` in root directory will generate `zstd` cli in root directory.
131
132Other 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
138A `cmake` project generator is provided within `build/cmake`.
139It can generate Makefiles or other build scripts
140to create `zstd` binary, and `libzstd` dynamic and static libraries.
141
142By default, `CMAKE_BUILD_TYPE` is set to `Release`.
143
144### Meson
145
146A Meson project is provided within [`build/meson`](build/meson). Follow
147build instructions in that directory.
148
149You can also take a look at [`.travis.yml`](.travis.yml) file for an
150example about how Meson is used to build this project.
151
152Note that default build type is **release**.
153
154### VCPKG
155You 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
163The zstd port in vcpkg is kept up to date by Microsoft team members and community contributors.
164If 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
168Going 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
176You can build the zstd binary via buck by executing: `buck build programs:zstd` from the root of the repo.
177The output binary will be in `buck-out/gen/programs/`.
178
179## Status
180
181Zstandard is currently deployed within Facebook. It is used continuously to compress large amounts of data in multiple formats and use cases.
182Zstandard is considered safe for production environments.
183
184## License
185
186Zstandard is dual-licensed under [BSD](LICENSE) and [GPLv2](COPYING).
187
188## Contributing
189
190The "dev" branch is the one where all contributions are merged before reaching "master".
191If you plan to propose a patch, please commit into the "dev" branch, or its own feature branch.
192Direct commit to "master" are not permitted.
193For more information, please read [CONTRIBUTING](CONTRIBUTING.md).
194