sys/contrib/zstd/lib/README.md

   1 Zstandard library files
   2 ================================
   3
   4 The __lib__ directory is split into several sub-directories,
   5 in 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,
  11 directories, 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
  18 Zstandard's stable API is exposed within [lib/zstd.h](zstd.h).
  19
  20
  21 #### Advanced API
  22
  23 Optional 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
  57 Multithreading is disabled by default when building with `make`.
  58 Enabling multithreading requires 2 conditions :
  59 - set macro `ZSTD_MULTITHREAD`
  60 - on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc` for example)
  61
  62 Both conditions are automatically triggered by invoking `make lib-mt` target.
  63 Note that, when linking a POSIX program with a multithreaded version of `libzstd`,
  64 it's necessary to trigger `-pthread` flag during link stage.
  65
  66 Multithreading 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
  77 DLL can be created using MinGW+MSYS with the `make libzstd` command.
  78 This command creates `dll\libzstd.dll` and the import library `dll\libzstd.lib`.
  79 The import library is only required with Visual C++.
  80 The header file `zstd.h` and the dynamic library `dll\libzstd.dll` are required to
  81 compile a project using gcc/MinGW.
  82 The dynamic library has to be added to linking options.
  83 It means that if a project that uses ZSTD consists of a single `test-dll.c`
  84 file 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 ```
  88 The compiled executable will require ZSTD DLL which is available at `dll\libzstd.dll`.
  89
  90
  91 #### Deprecated API
  92
  93 Obsolete API on their way out are stored in directory `lib/deprecated`.
  94 At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`.
  95 Presence in this directory is temporary.
  96 These prototypes will be removed in some future version.
  97 Consider migrating code towards supported streaming API exposed in `zstd.h`.
  98
  99
 100 #### Miscellaneous
 101
 102 The 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