ceph/src/zstd/lib/README.md

   1 Zstandard library files
   2 ================================
   3
   4 The __lib__ directory contains several directories.
   5 Depending on target use case, it's enough to include only files from relevant directories.
   6
   7
   8 #### API
   9
  10 Zstandard's stable API is exposed within [zstd.h](zstd.h),
  11 at the root of `lib` directory.
  12
  13
  14 #### Advanced API
  15
  16 Some additional API may be useful if you're looking into advanced features :
  17 - common/error_public.h : transforms `size_t` function results into an `enum`,
  18                           for precise error handling.
  19 - ZSTD_STATIC_LINKING_ONLY : if you define this macro _before_ including `zstd.h`,
  20                           it will give access to advanced and experimental API.
  21                           These APIs shall ___never be used with dynamic library___ !
  22                           They are not "stable", their definition may change in the future.
  23                           Only static linking is allowed.
  24
  25
  26 #### Modular build
  27
  28 Directory `common/` is required in all circumstances.
  29 You can select to support compression only, by just adding files from the `compress/` directory,
  30 In a similar way, you can build a decompressor-only library with the `decompress/` directory.
  31
  32 Other optional functionalities provided are :
  33
  34 - `dictBuilder/`  : source files to create dictionaries.
  35                     The API can be consulted in `dictBuilder/zdict.h`.
  36                     This module also depends on `common/` and `compress/` .
  37
  38 - `legacy/` : source code to decompress previous versions of zstd, starting from `v0.1`.
  39               This module also depends on `common/` and `decompress/` .
  40               Library compilation must include directive `ZSTD_LEGACY_SUPPORT = 1` .
  41               The main API can be consulted in `legacy/zstd_legacy.h`.
  42               Advanced API from each version can be found in their relevant header file.
  43               For example, advanced API for version `v0.4` is in `legacy/zstd_v04.h` .
  44
  45
  46 #### Using MinGW+MSYS to create DLL
  47
  48 DLL can be created using MinGW+MSYS with the `make libzstd` command.
  49 This command creates `dll\libzstd.dll` and the import library `dll\libzstd.lib`.
  50 The import library is only required with Visual C++.
  51 The header file `zstd.h` and the dynamic library `dll\libzstd.dll` are required to
  52 compile a project using gcc/MinGW.
  53 The dynamic library has to be added to linking options.
  54 It means that if a project that uses ZSTD consists of a single `test-dll.c`
  55 file it should be linked with `dll\libzstd.dll`. For example:
  56 ```
  57     gcc $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\libzstd.dll
  58 ```
  59 The compiled executable will require ZSTD DLL which is available at `dll\libzstd.dll`.
  60
  61
  62 #### Obsolete streaming API
  63
  64 Streaming is now provided within `zstd.h`.
  65 Older streaming API is still available within `deprecated/zbuff.h`.
  66 It will be removed in a future version.
  67 Consider migrating code towards newer streaming API in `zstd.h`.
  68
  69
  70 #### Miscellaneous
  71
  72 The other files are not source code. There are :
  73
  74  - LICENSE : contains the BSD license text
  75  - Makefile : script to compile or install zstd library (static and dynamic)
  76  - libzstd.pc.in : for pkg-config (`make install`)
  77  - README.md : this file