From 36374cc3b4f819099baf7b901b227a84a83e179f Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Wed, 6 Sep 2017 16:15:18 -0700 Subject: [PATCH] update and clarify lib/README --- lib/README.md | 106 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 43 deletions(-) diff --git a/lib/README.md b/lib/README.md index 79b6fd500..b54bdc91c 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,57 +1,76 @@ Zstandard library files ================================ -The __lib__ directory contains several directories. -Depending on target use case, it's enough to include only files from relevant directories. +The __lib__ directory is split into several sub-directories, +in order to make it easier to select or exclude specific features. + + +#### Building + +- `make` : generates both static and dynamic libraries +- `make install` : install libraries in default system directories #### API -Zstandard's stable API is exposed within [zstd.h](zstd.h), -at the root of `lib` directory. +Zstandard's stable API is exposed within [lib/zstd.h](zstd.h). #### Advanced API -Some additional API may be useful if you're looking into advanced features : -- common/error_public.h : transforms `size_t` function results into an `enum`, - for precise error handling. -- ZSTD_STATIC_LINKING_ONLY : if you define this macro _before_ including `zstd.h`, - it will give access to advanced and experimental API. +Optional advanced features are exposed via : + +- `lib/common/zstd_errors.h` : translates `size_t` function results + into an `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 shall ___never be used with dynamic library___ ! They are not "stable", their definition may change in the future. Only static linking is allowed. -#### ZSTDMT API - -To enable multithreaded compression within the library, invoke `make lib-mt` target. -Prototypes are defined in header file `compress/zstdmt_compress.h`. -When linking a program that uses ZSTDMT API against libzstd.a on a POSIX system, -`-pthread` flag must be provided to the compiler and linker. -Note : ZSTDMT prototypes can still be used with a library built without multithread support, -but in this case, they will be single threaded only. #### Modular build -Directory `common/` is required in all circumstances. -You can select to support compression only, by just adding files from the `compress/` directory, -In a similar way, you can build a decompressor-only library with the `decompress/` directory. - -Other optional functionalities provided are : - -- `dictBuilder/` : source files to create dictionaries. - The API can be consulted in `dictBuilder/zdict.h`. - This module also depends on `common/` and `compress/` . - -- `legacy/` : source code to decompress previous versions of zstd, starting from `v0.1`. - This module also depends on `common/` and `decompress/` . - Library compilation must include directive `ZSTD_LEGACY_SUPPORT = 1` . - The main API can be consulted in `legacy/zstd_legacy.h`. - Advanced API from each version can be found in their relevant header file. - For example, advanced API for version `v0.4` is in `legacy/zstd_v04.h` . +- 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 older zstd formats, starting from `v0.1`. + This module depends on `lib/common` and `lib/decompress`. + To enable this feature, it's necessary to define `ZSTD_LEGACY_SUPPORT = 1` during compilation. + Typically, with `gcc`, add argument `-DZSTD_LEGACY_SUPPORT=1`. + Using higher number limits the number of version supported. + For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats starting from v0.2+" + The API is exposed in `lib/legacy/zstd_legacy.h`. + Each version also provides a (dedicated) set of advanced API. + For example, advanced API for version `v0.4` is exposed in `lib/legacy/zstd_v04.h` . -#### Using MinGW+MSYS to create DLL +#### Multithreading support + +Multithreading is disabled by default for the library. +Enabling multithreading requires 2 conditions : +- set macro `ZSTD_MULTITHREAD` +- on POSIX systems : compile with pthread (using `-pthread` with `gcc` for example) + +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 : +- private API `lib/compress/zstdmt_compress.h`. + Symbols defined in this header are exposed in library, hence usable. + Note however that this API is planned to be locked and remain strictly internal 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 to trigger multi-threading. + + +#### Windows : using MinGW+MSYS to create DLL DLL can be created using MinGW+MSYS with the `make libzstd` command. This command creates `dll\libzstd.dll` and the import library `dll\libzstd.lib`. @@ -67,19 +86,20 @@ file it should be linked with `dll\libzstd.dll`. For example: The compiled executable will require ZSTD DLL which is available at `dll\libzstd.dll`. -#### Obsolete streaming API +#### Deprecated API -Streaming is now provided within `zstd.h`. -Older streaming API is still available within `deprecated/zbuff.h`. -It will be removed in a future version. -Consider migrating code towards newer streaming API in `zstd.h`. +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`. +Presence in this directory is temporary. +These prototypes will be removed in some future version. +Consider migrating code towards supported streaming API exposed in `zstd.h`. #### Miscellaneous The other files are not source code. There are : - - LICENSE : contains the BSD license text - - Makefile : script to compile or install zstd library (static and dynamic) - - libzstd.pc.in : for pkg-config (`make install`) - - README.md : this file + - `LICENSE` : contains the BSD license text + - `Makefile` : script to build and install zstd library (static and dynamic) + - `libzstd.pc.in` : for `pkg-config` (used in `make install`) + - `README.md` : this file