README.md
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.4.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 consequencem, 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, it's required to define `ZSTD_LEGACY_SUPPORT` during compilation.
52 Typically, with `gcc`, add argument `-DZSTD_LEGACY_SUPPORT=1`.
53 Using higher number limits versions supported.
54 For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats >= v0.2.0".
55 `ZSTD_LEGACY_SUPPORT=3` means : "support legacy formats >= v0.3.0", and so on.
56 Starting v0.8.0, all versions of `zstd` produce frames compliant with specification.
57 As a consequence, `ZSTD_LEGACY_SUPPORT=8` (or more) doesn't trigger legacy support.
58 Also, `ZSTD_LEGACY_SUPPORT=0` means "do __not__ support legacy formats".
59 Once enabled, this capability is transparently triggered within decompression functions.
60 It's also possible to invoke directly legacy API, as exposed in `lib/legacy/zstd_legacy.h`.
61 Each version also provides an additional dedicated set of advanced API.
62 For example, advanced API for version `v0.4` is exposed in `lib/legacy/zstd_v04.h` .
63 Note : `lib/legacy` only supports _decoding_ legacy formats.
64
65
66#### Multithreading support
67
68Multithreading is disabled by default when building with `make`.
69Enabling multithreading requires 2 conditions :
70- set macro `ZSTD_MULTITHREAD`
71- on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc`)
72
73Both conditions are automatically triggered by invoking `make lib-mt` target.
74Note that, when linking a POSIX program with a multithreaded version of `libzstd`,
75it's necessary to trigger `-pthread` flag during link stage.
76
77Multithreading capabilities are exposed
78via [advanced API `ZSTD_compress_generic()` defined in `lib/zstd.h`](https://github.com/facebook/zstd/blob/dev/lib/zstd.h#L919).
79This API is still considered experimental,
80but is expected to become "stable" at some point in the future.
81
82
83#### Windows : using MinGW+MSYS to create DLL
84
85DLL can be created using MinGW+MSYS with the `make libzstd` command.
86This command creates `dll\libzstd.dll` and the import library `dll\libzstd.lib`.
87The import library is only required with Visual C++.
88The header file `zstd.h` and the dynamic library `dll\libzstd.dll` are required to
89compile a project using gcc/MinGW.
90The dynamic library has to be added to linking options.
91It means that if a project that uses ZSTD consists of a single `test-dll.c`
92file it should be linked with `dll\libzstd.dll`. For example:
93```
94 gcc $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\libzstd.dll
95```
96The compiled executable will require ZSTD DLL which is available at `dll\libzstd.dll`.
97
98
99#### Deprecated API
100
101Obsolete API on their way out are stored in directory `lib/deprecated`.
102At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`.
103These prototypes will be removed in some future version.
104Consider migrating code towards supported streaming API exposed in `zstd.h`.
105
106
107#### Miscellaneous
108
109The other files are not source code. There are :
110
111 - `LICENSE` : contains the BSD license text
112 - `Makefile` : `make` script to build and install zstd library (static and dynamic)
113 - `BUCK` : support for `buck` build system (https://buckbuild.com/)
114 - `libzstd.pc.in` : for `pkg-config` (used in `make install`)
115 - `README.md` : this file
116