]>
Commit | Line | Data |
---|---|---|
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 |