xref: /zstd/
Name Date Size

..27-Apr.-20224 KiB

.buckconfigH A D18-Oct.-2021407

.buckversionH A D18-Oct.-202141

.circleci/H02-Dec.-20214 KiB

.cirrus.ymlH A D10-May-2022248

.gitattributesH A D18-Oct.-2021348

.github/H18-Oct.-20214 KiB

.gitignoreH A D18-Oct.-2021506

.travis.ymlH A D19-Apr.-20223.5 KiB

appveyor.ymlH A D30-Nov.-20217.3 KiB

build/H18-Oct.-20214 KiB

CHANGELOGH A D29-Jun.-202242.3 KiB

CODE_OF_CONDUCT.mdH A D18-Oct.-2021244

contrib/H18-Oct.-20214 KiB

CONTRIBUTING.mdH A D14-Mar.-202230.1 KiB

COPYINGH A D18-Oct.-202117.7 KiB

doc/H29-Jun.-20224 KiB

examples/H28-Dec.-20214 KiB

lib/H29-Jun.-20224 KiB

LICENSEH A D18-Oct.-20211.5 KiB

MakefileH A D03-Mar.-202214.7 KiB

Package.swiftH A D06-Jan.-20221.2 KiB

programs/H29-Jun.-20224 KiB

README.mdH A D19-Jun.-202210.1 KiB

TESTING.mdH A D18-Oct.-20211.8 KiB

tests/H24-Jun.-20224 KiB

zlibWrapper/H14-Mar.-20224 KiB

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
7Zstandard's format is stable and documented in [RFC8878](https://datatracker.ietf.org/doc/html/rfc8878). Multiple independent implementations are already available.
8This repository represents the reference implementation, provided as an open-source dual [BSD](LICENSE) and [GPLv2](COPYING) licensed **C** library,
9and a command line utility producing and decoding `.zst`, `.gz`, `.xz` and `.lz4` files.
10Should your project require another programming language,
11a 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
34For reference, several fast compression algorithms were tested and compared
35on a desktop running Ubuntu 20.04 (`Linux 5.11.0-41-generic`),
36with a Core i7-9700K CPU @ 4.9GHz,
37using [lzbench], an open-source in-memory benchmark by @inikep
38compiled with [gcc] 9.3.0,
39on 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
62The negative compression levels, specified with `--fast=#`,
63offer faster compression and decompression speed
64at the cost of compression ratio (compared to level 1).
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`make` is the officially maintained build system of this project.
128All other build systems are "compatible" and 3rd-party maintained,
129they may feature small differences in advanced options.
130When your system allows it, prefer using `make` to build `zstd` and `libzstd`.
131
132### Makefile
133
134If your system is compatible with standard `make` (or `gmake`),
135invoking `make` in root directory will generate `zstd` cli in root directory.
136It will also create `libzstd` into `lib/`.
137
138Other available options include:
139- `make install` : create and install zstd cli, library and man pages
140- `make check` : create and run `zstd`, test its behavior on local platform
141
142The `Makefile` follows the [GNU Standard Makefile conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html),
143allowing staged install, standard flags, directory variables and command variables.
144
145### cmake
146
147A `cmake` project generator is provided within `build/cmake`.
148It can generate Makefiles or other build scripts
149to create `zstd` binary, and `libzstd` dynamic and static libraries.
150
151By default, `CMAKE_BUILD_TYPE` is set to `Release`.
152
153### Meson
154
155A Meson project is provided within [`build/meson`](build/meson). Follow
156build instructions in that directory.
157
158You can also take a look at [`.travis.yml`](.travis.yml) file for an
159example about how Meson is used to build this project.
160
161Note that default build type is **release**.
162
163### VCPKG
164You can build and install zstd [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
165
166    git clone https://github.com/Microsoft/vcpkg.git
167    cd vcpkg
168    ./bootstrap-vcpkg.sh
169    ./vcpkg integrate install
170    ./vcpkg install zstd
171
172The zstd port in vcpkg is kept up to date by Microsoft team members and community contributors.
173If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
174
175### Visual Studio (Windows)
176
177Going into `build` directory, you will find additional possibilities:
178- Projects for Visual Studio 2005, 2008 and 2010.
179  + VS2010 project is compatible with VS2012, VS2013, VS2015 and VS2017.
180- Automated build scripts for Visual compiler by [@KrzysFR](https://github.com/KrzysFR), in `build/VS_scripts`,
181  which will build `zstd` cli and `libzstd` library without any need to open Visual Studio solution.
182
183### Buck
184
185You can build the zstd binary via buck by executing: `buck build programs:zstd` from the root of the repo.
186The output binary will be in `buck-out/gen/programs/`.
187
188## Testing
189
190You can run quick local smoke tests by executing the `playTest.sh` script from the `src/tests` directory.
191Two env variables `$ZSTD_BIN` and `$DATAGEN_BIN` are needed for the test script to locate the zstd and datagen binary.
192For information on CI testing, please refer to TESTING.md
193
194## Status
195
196Zstandard is currently deployed within Facebook. It is used continuously to compress large amounts of data in multiple formats and use cases.
197Zstandard is considered safe for production environments.
198
199## License
200
201Zstandard is dual-licensed under [BSD](LICENSE) and [GPLv2](COPYING).
202
203## Contributing
204
205The `dev` branch is the one where all contributions are merged before reaching `release`.
206If you plan to propose a patch, please commit into the `dev` branch, or its own feature branch.
207Direct commit to `release` are not permitted.
208For more information, please read [CONTRIBUTING](CONTRIBUTING.md).
209