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 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),
  11 including 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,
  16 and decoding support for legacy formats >= v0.5.0.
  17
  18
  19 #### API
  20
  21 Zstandard's stable API is exposed within [lib/zstd.h](zstd.h).
  22
  23
  24 #### Advanced API
  25
  26 Optional 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
  40 It'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
  73 Multithreading is disabled by default when building with `make`.
  74 Enabling multithreading requires 2 conditions :
  75 - set macro `ZSTD_MULTITHREAD`
  76 - on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc`)
  77
  78 Both conditions are automatically triggered by invoking `make lib-mt` target.
  79 Note that, when linking a POSIX program with a multithreaded version of `libzstd`,
  80 it's necessary to trigger `-pthread` flag during link stage.
  81
  82 Multithreading capabilities are exposed
  83 via [advanced API `ZSTD_compress_generic()` defined in `lib/zstd.h`](https://github.com/facebook/zstd/blob/dev/lib/zstd.h#L919).
  84 This API is still considered experimental,
  85 but is expected to become "stable" at some point in the future.
  86
  87
  88 #### Windows : using MinGW+MSYS to create DLL
  89
  90 DLL can be created using MinGW+MSYS with the `make libzstd` command.
  91 This command creates `dll\libzstd.dll` and the import library `dll\libzstd.lib`.
  92 The import library is only required with Visual C++.
  93 The header file `zstd.h` and the dynamic library `dll\libzstd.dll` are required to
  94 compile a project using gcc/MinGW.
  95 The dynamic library has to be added to linking options.
  96 It means that if a project that uses ZSTD consists of a single `test-dll.c`
  97 file 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 ```
 101 The compiled executable will require ZSTD DLL which is available at `dll\libzstd.dll`.
 102
 103
 104 #### Deprecated API
 105
 106 Obsolete API on their way out are stored in directory `lib/deprecated`.
 107 At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`.
 108 These prototypes will be removed in some future version.
 109 Consider migrating code towards supported streaming API exposed in `zstd.h`.
 110
 111
 112 #### Miscellaneous
 113
 114 The 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