|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 03-May-2022 | - |
| common/ | H | 03-May-2022 | - | 4,753 | 2,570 |
| compress/ | H | 03-May-2022 | - | 9,424 | 7,142 |
| decompress/ | H | 03-May-2022 | - | 3,663 | 2,819 |
| deprecated/ | H | 03-May-2022 | - | 465 | 178 |
| dictBuilder/ | H | 03-May-2022 | - | 4,316 | 3,239 |
| dll/ | H | 03-May-2022 | - | 434 | 389 |
| legacy/ | H | 03-May-2022 | - | 26,426 | 16,173 |
| .gitignore | H A D | 29-Nov-2018 | 48 | 4 | 3 |
| BUCK | H A D | 29-Nov-2018 | 3.9 KiB | 208 | 192 |
| Makefile | H A D | 29-Nov-2018 | 6.9 KiB | 190 | 138 |
| README.md | H A D | 29-Nov-2018 | 4.9 KiB | 109 | 79 |
| libzstd.pc.in | H A D | 29-Nov-2018 | 391 | 15 | 12 |
| zstd.h | H A D | 29-Nov-2018 | 84 KiB | 1,400 | 359 |
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 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