updated libzstd documentation
diff --git a/lib/README.md b/lib/README.md
index 45fd625..0c9cd6d 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -7,13 +7,32 @@
#### 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 @@
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 @@
`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 @@
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`)