krak/zstd
krak/zstd
1
0
Fork 0
mirror of https://github.com/facebook/zstd.git synced 2025-03-06 16:56:49 +02:00
Code Issues Releases 1 Activity

update and clarify lib/README

Browse Source
This commit is contained in:
Yann Collet 2017-09-06 16:15:18 -07:00
parent e6b0945c3e
commit 36374cc3b4
1 changed files with 63 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
lib/README.md
View File

@ -1,57 +1,76 @@
Zstandard library files Zstandard library files
================================ ================================
The __lib__ directory contains several directories. The __lib__ directory is split into several sub-directories,
Depending on target use case, it's enough to include only files from relevant 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 #### API
Zstandard's stable API is exposed within [zstd.h](zstd.h), Zstandard's stable API is exposed within [lib/zstd.h](zstd.h).
at the root of `lib` directory.
#### Advanced API #### Advanced API
Some additional API may be useful if you're looking into advanced features : Optional advanced features are exposed via :
- common/error_public.h : transforms `size_t` function results into an `enum`,
for precise error handling. - `lib/common/zstd_errors.h` : translates `size_t` function results
- ZSTD_STATIC_LINKING_ONLY : if you define this macro _before_ including `zstd.h`, into an `ZSTD_ErrorCode`, for accurate error handling.
it will give access to advanced and experimental API. - `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___ ! These APIs shall ___never be used with dynamic library___ !
They are not "stable", their definition may change in the future. They are not "stable", their definition may change in the future.
Only static linking is allowed. 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 #### Modular build
Directory `common/` is required in all circumstances. - Directory `lib/common` is always required, for all variants.
You can select to support compression only, by just adding files from the `compress/` directory, - Compression source code lies in `lib/compress`
In a similar way, you can build a decompressor-only library with the `decompress/` directory. - Decompression source code lies in `lib/decompress`
- It's possible to include only `compress` or only `decompress`, they don't depend on each other.
Other optional functionalities provided are : - `lib/dictBuilder` : makes it possible to generate dictionaries from a set of samples.
The API is exposed in `lib/dictBuilder/zdict.h`.
- `dictBuilder/` : source files to create dictionaries. This module depends on both `lib/common` and `lib/compress` .
The API can be consulted in `dictBuilder/zdict.h`. - `lib/legacy` : source code to decompress older zstd formats, starting from `v0.1`.
This module also depends on `common/` and `compress/` . This module depends on `lib/common` and `lib/decompress`.
To enable this feature, it's necessary to define `ZSTD_LEGACY_SUPPORT = 1` during compilation.
- `legacy/` : source code to decompress previous versions of zstd, starting from `v0.1`. Typically, with `gcc`, add argument `-DZSTD_LEGACY_SUPPORT=1`.
This module also depends on `common/` and `decompress/` . Using higher number limits the number of version supported.
Library compilation must include directive `ZSTD_LEGACY_SUPPORT = 1` . For example, `ZSTD_LEGACY_SUPPORT=2` means : "support legacy formats starting from v0.2+"
The main API can be consulted in `legacy/zstd_legacy.h`. The API is exposed in `lib/legacy/zstd_legacy.h`.
Advanced API from each version can be found in their relevant header file. Each version also provides a (dedicated) set of advanced API.
For example, advanced API for version `v0.4` is in `legacy/zstd_v04.h` . 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. 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`. 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`. 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`. Obsolete API on their way out are stored in directory `lib/deprecated`.
Older streaming API is still available within `deprecated/zbuff.h`. At this stage, it contains older streaming prototypes, in `lib/deprecated/zbuff.h`.
It will be removed in a future version. Presence in this directory is temporary.
Consider migrating code towards newer streaming API in `zstd.h`. These prototypes will be removed in some future version.
Consider migrating code towards supported streaming API exposed in `zstd.h`.
#### Miscellaneous #### Miscellaneous
The other files are not source code. There are : The other files are not source code. There are :
- LICENSE : contains the BSD license text - `LICENSE` : contains the BSD license text
- Makefile : script to compile or install zstd library (static and dynamic) - `Makefile` : script to build and install zstd library (static and dynamic)
- libzstd.pc.in : for pkg-config (`make install`) - `libzstd.pc.in` : for `pkg-config` (used in `make install`)
- README.md : this file - `README.md` : this file