ddidderr/zstd-rs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updated /lib documentation

Browse Source
This commit is contained in:
Yann Collet
2017-12-31 15:50:00 +01:00
parent b6887b6d43
commit 2eff217136
1 changed files with 32 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/README.md
+32 -25
View File
@@ -2,16 +2,19 @@ Zstandard library files
================================ ================================
The __lib__ directory is split into several sub-directories, The __lib__ directory is split into several sub-directories,
in order to make it easier to select or exclude specific features. in order to make it easier to select or exclude features.
#### Building #### Building
`Makefile` script is provided, supporting the standard set of commands, `Makefile` script is provided, supporting all standard [Makefile conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html#Makefile-Conventions),
directories, and variables (see https://www.gnu.org/prep/standards/html_node/Command-Variables.html). including commands variables, staged install, directory variables and standard targets.
- `make` : generates both static and dynamic libraries - `make` : generates both static and dynamic libraries
- `make install` : install libraries in default system directories - `make install` : install libraries in default system directories
`libzstd` default scope includes compression, decompression, dictionary building,
and decoding support for legacy formats >= v0.4.0.
#### API #### API
@@ -27,29 +30,37 @@ Optional advanced features are exposed via :
- `ZSTD_STATIC_LINKING_ONLY` : if this macro is defined _before_ including `zstd.h`, - `ZSTD_STATIC_LINKING_ONLY` : if this macro is defined _before_ including `zstd.h`,
it unlocks access to advanced experimental API, it unlocks access to advanced experimental API,
exposed in second part of `zstd.h`. exposed in second part of `zstd.h`.
These APIs shall ___never be used with dynamic library___ ! These APIs are not "stable", their definition may change in the future.
They are not "stable", their definition may change in the future. As a consequencem, it shall ___never be used with dynamic library___ !
Only static linking is allowed. Only static linking is allowed.
#### Modular build #### Modular build
It's possible to compile only a limited set of features.
- Directory `lib/common` is always required, for all variants. - Directory `lib/common` is always required, for all variants.
- Compression source code lies in `lib/compress` - Compression source code lies in `lib/compress`
- Decompression source code lies in `lib/decompress` - Decompression source code lies in `lib/decompress`
- It's possible to include only `compress` or only `decompress`, they don't depend on each other. - It's possible to include only `compress` or only `decompress`, they don't depend on each other.
- `lib/dictBuilder` : makes it possible to generate dictionaries from a set of samples. - `lib/dictBuilder` : makes it possible to generate dictionaries from a set of samples.
The API is exposed in `lib/dictBuilder/zdict.h`. The API is exposed in `lib/dictBuilder/zdict.h`.
This module depends on both `lib/common` and `lib/compress` . This module depends on both `lib/common` and `lib/compress` .
- `lib/legacy` : source code to decompress older zstd formats, starting from `v0.1`. - `lib/legacy` : source code to decompress legacy zstd formats, starting from `v0.1.0`.
This module depends on `lib/common` and `lib/decompress`. This module depends on `lib/common` and `lib/decompress`.
To enable this feature, it's necessary to define `ZSTD_LEGACY_SUPPORT = 1` during compilation. To enable this feature, it's required to define `ZSTD_LEGACY_SUPPORT` during compilation.
Typically, with `gcc`, add argument `-DZSTD_LEGACY_SUPPORT=1`. Typically, with `gcc`, add argument `-DZSTD_LEGACY_SUPPORT=1`.
Using higher number limits the number of version supported. Using higher number limits versions supported.
For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats starting from v0.2+". For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats >= v0.2.0".
The API is exposed in `lib/legacy/zstd_legacy.h`. `ZSTD_LEGACY_SUPPORT=3` means : "support legacy formats >= v0.3.0", and so on.
Each version also provides a (dedicated) set of advanced API. Starting v0.8.0, all versions of `zstd` produce frames compliant with specification.
For example, advanced API for version `v0.4` is exposed in `lib/legacy/zstd_v04.h` . As a consequence, `ZSTD_LEGACY_SUPPORT=8` (or more) doesn't trigger legacy support.
Also, `ZSTD_LEGACY_SUPPORT=0` means "do __not__ support legacy formats".
Once enabled, this capability is transparently triggered within decompression functions.
It's also possible to invoke directly legacy API, as exposed in `lib/legacy/zstd_legacy.h`.
Each version also provides an additional dedicated set of advanced API.
For example, advanced API for version `v0.4` is exposed in `lib/legacy/zstd_v04.h` .
Note : `lib/legacy` only supports _decoding_ legacy formats.
#### Multithreading support #### Multithreading support
@@ -57,19 +68,16 @@ Optional advanced features are exposed via :
Multithreading is disabled by default when building with `make`. Multithreading is disabled by default when building with `make`.
Enabling multithreading requires 2 conditions : Enabling multithreading requires 2 conditions :
- set macro `ZSTD_MULTITHREAD` - set macro `ZSTD_MULTITHREAD`
- on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc` for example) - on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc`)
Both conditions are automatically triggered by invoking `make lib-mt` target. Both conditions are automatically triggered by invoking `make lib-mt` target.
Note that, when linking a POSIX program with a multithreaded version of `libzstd`, Note that, when linking a POSIX program with a multithreaded version of `libzstd`,
it's necessary to trigger `-pthread` flag during link stage. it's necessary to trigger `-pthread` flag during link stage.
Multithreading capabilities are exposed via : Multithreading capabilities are exposed
- private API `lib/compress/zstdmt_compress.h`. via [advanced API `ZSTD_compress_generic()` defined in `lib/zstd.h`](https://github.com/facebook/zstd/blob/dev/lib/zstd.h#L919).
Symbols defined in this header are currently exposed in `libzstd`, hence usable. This API is still considered experimental,
Note however that this API is planned to be locked and remain strictly internal in the future. but is expected to become "stable" at some point in the future.
- advanced API `ZSTD_compress_generic()`, defined in `lib/zstd.h`, experimental section.
This API is still considered experimental, but is designed to be labelled "stable" at some point in the future.
It's the recommended entry point for multi-threading operations.
#### Windows : using MinGW+MSYS to create DLL #### Windows : using MinGW+MSYS to create DLL
@@ -92,7 +100,6 @@ The compiled executable will require ZSTD DLL which is available at `dll\libzstd
Obsolete API on their way out are stored in directory `lib/deprecated`. Obsolete API on their way out are stored in directory `lib/deprecated`.
At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`. At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`.
Presence in this directory is temporary.
These prototypes will be removed in some future version. These prototypes will be removed in some future version.
Consider migrating code towards supported streaming API exposed in `zstd.h`. Consider migrating code towards supported streaming API exposed in `zstd.h`.