From: Yann Collet Date: Tue, 25 Dec 2018 11:10:07 +0000 (-0800) Subject: updated libzstd documentation X-Git-Tag: v1.3.8~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0fb4b21d1ad4b3dc523aed73ed001e6e71649d8a;p=thirdparty%2Fzstd.git updated libzstd documentation --- diff --git a/lib/README.md b/lib/README.md index 45fd62551..0c9cd6d58 100644 --- a/lib/README.md +++ b/lib/README.md @@ -7,13 +7,32 @@ in order to make it easier to select or exclude features. #### Building -`Makefile` script is provided, supporting all standard [Makefile conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html#Makefile-Conventions), +`Makefile` script is provided, supporting [Makefile conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html#Makefile-Conventions), including commands variables, staged install, directory variables and standard targets. - `make` : generates both static and dynamic libraries -- `make install` : install libraries in default system directories +- `make install` : install libraries and headers in target system directories -`libzstd` default scope includes compression, decompression, dictionary building, -and decoding support for legacy formats >= v0.5.0. +`libzstd` default scope is pretty large, including compression, decompression, dictionary builder, +and support for decoding legacy formats >= v0.5.0. +The scope can be reduced on demand (see paragraph _modular build_). + + +#### Multithreading support + +Multithreading is disabled by default when building with `make`. +Enabling multithreading requires 2 conditions : +- set build macro `ZSTD_MULTITHREAD` (`-DZSTD_MULTITHREAD` for `gcc`) +- for POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc`) + +Both conditions are automatically applied when invoking `make lib-mt` target. + +When linking a POSIX program with a multithreaded version of `libzstd`, +note that it's necessary to request the `-pthread` flag during link stage. + +Multithreading capabilities are exposed +via the [advanced API defined in `lib/zstd.h`](https://github.com/facebook/zstd/blob/v1.3.8/lib/zstd.h#L592). +This API is still labelled experimental, +but is expected to become "stable" in the near future. #### API @@ -26,47 +45,53 @@ Zstandard's stable API is exposed within [lib/zstd.h](zstd.h). Optional advanced features are exposed via : - `lib/common/zstd_errors.h` : translates `size_t` function results - into an `ZSTD_ErrorCode`, for accurate error handling. + into a `ZSTD_ErrorCode`, for accurate error handling. + - `ZSTD_STATIC_LINKING_ONLY` : if this macro is defined _before_ including `zstd.h`, - it unlocks access to advanced experimental API, - exposed in second part of `zstd.h`. - These APIs are not "stable", their definition may change in the future. - As a consequence, it shall ___never be used with dynamic library___ ! + it unlocks access to the experimental API, + exposed in the second part of `zstd.h`. + All definitions in the experimental APIs are unstable, + they may still change in the future, or even be removed. + As a consequence, experimental definitions shall ___never be used with dynamic library___ ! Only static linking is allowed. #### Modular build -It's possible to compile only a limited set of features. +It's possible to compile only a limited set of features within `libzstd`. +The file structure is designed to make this selection manually achievable for any build system : - Directory `lib/common` is always required, for all variants. + - Compression source code lies in `lib/compress` + - Decompression source code lies in `lib/decompress` + - 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. The API is exposed in `lib/dictBuilder/zdict.h`. This module depends on both `lib/common` and `lib/compress` . -- `lib/legacy` : source code to decompress legacy zstd formats, starting from `v0.1.0`. + +- `lib/legacy` : makes it possible to decompress legacy zstd formats, starting from `v0.1.0`. This module depends on `lib/common` and `lib/decompress`. To enable this feature, define `ZSTD_LEGACY_SUPPORT` during compilation. Specifying a number limits versions supported to that version onward. For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats >= v0.2.0". - `ZSTD_LEGACY_SUPPORT=3` means : "support legacy formats >= v0.3.0", and so on. - Currently, the default library setting is `ZST_LEGACY_SUPPORT=5`. - It can be changed at build by any other value. - Note that any number >= 8 translates into "do __not__ support legacy formats", - since all versions of `zstd` >= v0.8 are compatible with v1+ specification. - `ZSTD_LEGACY_SUPPORT=0` also 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. + Conversely, `ZSTD_LEGACY_SUPPORT=0` means "do __not__ support legacy formats". + By default, this build macro is set as `ZSTD_LEGACY_SUPPORT=5`. + Decoding supported legacy format is a transparent capability triggered within decompression functions. + It's also allowed to invoke legacy API directly, exposed in `lib/legacy/zstd_legacy.h`. + Each version does also provide its own 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. -- Similarly, you can define `ZSTD_LIB_COMPRESSION, ZSTD_LIB_DECOMPRESSION`, `ZSTD_LIB_DICTBUILDER`, - and `ZSTD_LIB_DEPRECATED` as 0 to forgo compilation of the corresponding features. This will - also disable compilation of all dependencies (eg. `ZSTD_LIB_COMPRESSION=0` will also disable - dictBuilder). -- There are some additional macros that can be used to minify the decoder. + +- While invoking `make libzstd`, it's possible to define build macros + `ZSTD_LIB_COMPRESSION, ZSTD_LIB_DECOMPRESSION`, `ZSTD_LIB_DICTBUILDER`, + and `ZSTD_LIB_DEPRECATED` as `0` to forgo compilation of the corresponding features. + This will also disable compilation of all dependencies + (eg. `ZSTD_LIB_COMPRESSION=0` will also disable dictBuilder). + +- There are some additional build macros that can be used to minify the decoder. Zstandard often has more than one implementation of a piece of functionality, where each implementation optimizes for different scenarios. For example, the @@ -86,23 +111,6 @@ It's possible to compile only a limited set of features. `ZSTD_getErrorName`. -#### Multithreading support - -Multithreading is disabled by default when building with `make`. -Enabling multithreading requires 2 conditions : -- set macro `ZSTD_MULTITHREAD` -- on POSIX systems : compile with pthread (`-pthread` compilation flag for `gcc`) - -Both conditions are automatically triggered by invoking `make lib-mt` target. -Note that, when linking a POSIX program with a multithreaded version of `libzstd`, -it's necessary to trigger `-pthread` flag during link stage. - -Multithreading capabilities are exposed -via [advanced API `ZSTD_compress_generic()` defined in `lib/zstd.h`](https://github.com/facebook/zstd/blob/dev/lib/zstd.h#L919). -This API is still considered experimental, -but is expected to become "stable" at some point in the future. - - #### Windows : using MinGW+MSYS to create DLL DLL can be created using MinGW+MSYS with the `make libzstd` command. @@ -131,8 +139,8 @@ Consider migrating code towards supported streaming API exposed in `zstd.h`. The other files are not source code. There are : - - `LICENSE` : contains the BSD license text - - `Makefile` : `make` script to build and install zstd library (static and dynamic) - `BUCK` : support for `buck` build system (https://buckbuild.com/) - - `libzstd.pc.in` : for `pkg-config` (used in `make install`) + - `Makefile` : `make` script to build and install zstd library (static and dynamic) - `README.md` : this file + - `dll/` : resources directory for Windows compilation + - `libzstd.pc.in` : script for `pkg-config` (used in `make install`)