projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
1 | Zstandard library files |
| 2 | ================================ | |
| 3 | ||
| 11fdf7f2 TL |
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 | |
| 7c673cae FG |
14 | |
| 15 | ||
| 16 | #### API | |
| 17 | ||
| 11fdf7f2 | 18 | Zstandard's stable API is exposed within [lib/zstd.h](zstd.h). |
| 7c673cae FG |
19 | |
| 20 | ||
| 21 | #### Advanced API | |
| 22 | ||
| 11fdf7f2 TL |
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`. | |
| 7c673cae FG |
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 | ||
| 11fdf7f2 TL |
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 | |
| 7c673cae FG |
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 | ||
| 11fdf7f2 | 91 | #### Deprecated API |
| 7c673cae | 92 | |
| 11fdf7f2 TL |
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`. | |
| 7c673cae FG |
98 | |
| 99 | ||
| 100 | #### Miscellaneous | |
| 101 | ||
| 102 | The other files are not source code. There are : | |
| 103 | ||
| 11fdf7f2 TL |
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 |