1Zstandard library files 2================================ 3 4The __lib__ directory is split into several sub-directories, 5in order to make it easier to select or exclude features. 6 7 8#### Building 9 10`Makefile` script is provided, supporting all standard [Makefile conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html#Makefile-Conventions), 11including commands variables, staged install, directory variables and standard targets. 12- `make` : generates both static and dynamic libraries 13- `make install` : install libraries in default system directories 14 15`libzstd` default scope includes compression, decompression, dictionary building, 16and decoding support for legacy formats >= v0.5.0. 17 18 19#### API 20 21Zstandard's stable API is exposed within [lib/zstd.h](zstd.h). 22 23 24#### Advanced API 25 26Optional advanced features are exposed via : 27 28- `lib/common/zstd_errors.h` : translates `size_t` function results 29 into an `ZSTD_ErrorCode`, for accurate error handling. 30- `ZSTD_STATIC_LINKING_ONLY` : if this macro is defined _before_ including `zstd.h`, 31 it unlocks access to advanced experimental API, 32 exposed in second part of `zstd.h`. 33 These APIs are not "stable", their definition may change in the future. 34 As a consequence, it shall ___never be used with dynamic library___ ! 35 Only static linking is allowed. 36 37 38#### Modular build 39 40It's possible to compile only a limited set of features. 41 42- Directory `lib/common` is always required, for all variants. 43- Compression source code lies in `lib/compress` 44- Decompression source code lies in `lib/decompress` 45- It's possible to include only `compress` or only `decompress`, they don't depend on each other. 46- `lib/dictBuilder` : makes it possible to generate dictionaries from a set of samples. 47 The API is exposed in `lib/dictBuilder/zdict.h`. 48 This module depends on both `lib/common` and `lib/compress` . 49- `lib/legacy` : source code to decompress legacy zstd formats, starting from `v0.1.0`. 50 This module depends on `lib/common` and `lib/decompress`. 51 To enable this feature, define `ZSTD_LEGACY_SUPPORT` during compilation. 52 Specifying a number limits versions supported to that version onward. 53 For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats >= v0.2.0". 54 `ZSTD_LEGACY_SUPPORT=3` means : "support legacy formats >= v0.3.0", and so on. 55 Currently, the default library setting is `ZST_LEGACY_SUPPORT=5`. 56 It can be changed at build by any other value. 57 Note that any number >= 8 translates into "do __not__ support legacy formats", 58 since all versions of `zstd` >= v0.8 are compatible with v1+ specification. 59 `ZSTD_LEGACY_SUPPORT=0` also means "do __not__ support legacy formats". 60 Once enabled, this capability is transparently triggered within decompression functions. 61 It's also possible to invoke directly legacy API, as exposed in `lib/legacy/zstd_legacy.h`. 62 Each version also provides an additional dedicated set of advanced API. 63 For example, advanced API for version `v0.4` is exposed in `lib/legacy/zstd_v04.h` . 64 Note : `lib/legacy` only supports _decoding_ legacy formats. 65- Similarly, you can define `ZSTD_LIB_COMPRESSION, ZSTD_LIB_DECOMPRESSION`, `ZSTD_LIB_DICTBUILDER`, 66 and `ZSTD_LIB_DEPRECATED` as 0 to forgo compilation of the corresponding features. This will 67 also disable compilation of all dependencies (eg. `ZSTD_LIB_COMPRESSION=0` will also disable 68 dictBuilder). 69 70 71#### Multithreading support 72 73Multithreading is disabled by default when building with `make`. 74Enabling multithreading requires 2 conditions : 75- set macro `ZSTD_MULTITHREAD` 76- on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc`) 77 78Both conditions are automatically triggered by invoking `make lib-mt` target. 79Note that, when linking a POSIX program with a multithreaded version of `libzstd`, 80it's necessary to trigger `-pthread` flag during link stage. 81 82Multithreading capabilities are exposed 83via [advanced API `ZSTD_compress_generic()` defined in `lib/zstd.h`](https://github.com/facebook/zstd/blob/dev/lib/zstd.h#L919). 84This API is still considered experimental, 85but is expected to become "stable" at some point in the future. 86 87 88#### Windows : using MinGW+MSYS to create DLL 89 90DLL can be created using MinGW+MSYS with the `make libzstd` command. 91This command creates `dll\libzstd.dll` and the import library `dll\libzstd.lib`. 92The import library is only required with Visual C++. 93The header file `zstd.h` and the dynamic library `dll\libzstd.dll` are required to 94compile a project using gcc/MinGW. 95The dynamic library has to be added to linking options. 96It means that if a project that uses ZSTD consists of a single `test-dll.c` 97file it should be linked with `dll\libzstd.dll`. For example: 98``` 99 gcc $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\libzstd.dll 100``` 101The compiled executable will require ZSTD DLL which is available at `dll\libzstd.dll`. 102 103 104#### Deprecated API 105 106Obsolete API on their way out are stored in directory `lib/deprecated`. 107At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`. 108These prototypes will be removed in some future version. 109Consider migrating code towards supported streaming API exposed in `zstd.h`. 110 111 112#### Miscellaneous 113 114The other files are not source code. There are : 115 116 - `LICENSE` : contains the BSD license text 117 - `Makefile` : `make` script to build and install zstd library (static and dynamic) 118 - `BUCK` : support for `buck` build system (https://buckbuild.com/) 119 - `libzstd.pc.in` : for `pkg-config` (used in `make install`) 120 - `README.md` : this file 121