1Zstandard library files 2================================ 3 4The __lib__ directory is split into several sub-directories, 5in order to make it easier to select or exclude specific features. 6 7 8#### Building 9 10`Makefile` script is provided, supporting the standard set of commands, 11directories, and variables (see https://www.gnu.org/prep/standards/html_node/Command-Variables.html). 12- `make` : generates both static and dynamic libraries 13- `make install` : install libraries in default system directories 14 15 16#### API 17 18Zstandard's stable API is exposed within [lib/zstd.h](zstd.h). 19 20 21#### Advanced API 22 23Optional advanced features are exposed via : 24 25- `lib/common/zstd_errors.h` : translates `size_t` function results 26 into an `ZSTD_ErrorCode`, for accurate error handling. 27- `ZSTD_STATIC_LINKING_ONLY` : if this macro is defined _before_ including `zstd.h`, 28 it unlocks access to advanced experimental API, 29 exposed in second part of `zstd.h`. 30 These APIs shall ___never be used with dynamic library___ ! 31 They are not "stable", their definition may change in the future. 32 Only static linking is allowed. 33 34 35#### Modular build 36 37- Directory `lib/common` is always required, for all variants. 38- Compression source code lies in `lib/compress` 39- Decompression source code lies in `lib/decompress` 40- It's possible to include only `compress` or only `decompress`, they don't depend on each other. 41- `lib/dictBuilder` : makes it possible to generate dictionaries from a set of samples. 42 The API is exposed in `lib/dictBuilder/zdict.h`. 43 This module depends on both `lib/common` and `lib/compress` . 44- `lib/legacy` : source code to decompress older zstd formats, starting from `v0.1`. 45 This module depends on `lib/common` and `lib/decompress`. 46 To enable this feature, it's necessary to define `ZSTD_LEGACY_SUPPORT = 1` during compilation. 47 Typically, with `gcc`, add argument `-DZSTD_LEGACY_SUPPORT=1`. 48 Using higher number limits the number of version supported. 49 For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats starting from v0.2+". 50 The API is exposed in `lib/legacy/zstd_legacy.h`. 51 Each version also provides a (dedicated) set of advanced API. 52 For example, advanced API for version `v0.4` is exposed in `lib/legacy/zstd_v04.h` . 53 54 55#### Multithreading support 56 57Multithreading is disabled by default when building with `make`. 58Enabling multithreading requires 2 conditions : 59- set macro `ZSTD_MULTITHREAD` 60- on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc` for example) 61 62Both conditions are automatically triggered by invoking `make lib-mt` target. 63Note that, when linking a POSIX program with a multithreaded version of `libzstd`, 64it's necessary to trigger `-pthread` flag during link stage. 65 66Multithreading capabilities are exposed via : 67- private API `lib/compress/zstdmt_compress.h`. 68 Symbols defined in this header are currently exposed in `libzstd`, hence usable. 69 Note however that this API is planned to be locked and remain strictly internal in the future. 70- advanced API `ZSTD_compress_generic()`, defined in `lib/zstd.h`, experimental section. 71 This API is still considered experimental, but is designed to be labelled "stable" at some point in the future. 72 It's the recommended entry point for multi-threading operations. 73 74 75#### Windows : using MinGW+MSYS to create DLL 76 77DLL can be created using MinGW+MSYS with the `make libzstd` command. 78This command creates `dll\libzstd.dll` and the import library `dll\libzstd.lib`. 79The import library is only required with Visual C++. 80The header file `zstd.h` and the dynamic library `dll\libzstd.dll` are required to 81compile a project using gcc/MinGW. 82The dynamic library has to be added to linking options. 83It means that if a project that uses ZSTD consists of a single `test-dll.c` 84file it should be linked with `dll\libzstd.dll`. For example: 85``` 86 gcc $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\libzstd.dll 87``` 88The compiled executable will require ZSTD DLL which is available at `dll\libzstd.dll`. 89 90 91#### Deprecated API 92 93Obsolete API on their way out are stored in directory `lib/deprecated`. 94At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`. 95Presence in this directory is temporary. 96These prototypes will be removed in some future version. 97Consider migrating code towards supported streaming API exposed in `zstd.h`. 98 99 100#### Miscellaneous 101 102The other files are not source code. There are : 103 104 - `LICENSE` : contains the BSD license text 105 - `Makefile` : `make` script to build and install zstd library (static and dynamic) 106 - `BUCK` : support for `buck` build system (https://buckbuild.com/) 107 - `libzstd.pc.in` : for `pkg-config` (used in `make install`) 108 - `README.md` : this file 109