mirror of
https://github.com/facebook/zstd.git
synced 2025-03-06 16:56:49 +02:00
update and clarify lib/README
This commit is contained in:
Yann Collet
parent
e6b0945c3e
commit
36374cc3b4
106
lib/README.md
106
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user