1LZ4 - Library Files
2================================
3
4The `/lib` directory contains many files, but depending on project's objectives,
5not all of them are necessary.
6
7#### Minimal LZ4 build
8
9The minimum required is **`lz4.c`** and **`lz4.h`**,
10which provides the fast compression and decompression algorithms.
11They generate and decode data using the [LZ4 block format].
12
13
14#### High Compression variant
15
16For more compression ratio at the cost of compression speed,
17the High Compression variant called **lz4hc** is available.
18Add files **`lz4hc.c`** and **`lz4hc.h`**.
19This variant also compresses data using the [LZ4 block format],
20and depends on regular `lib/lz4.*` source files.
21
22
23#### Frame support, for interoperability
24
25In order to produce compressed data compatible with `lz4` command line utility,
26it's necessary to use the [official interoperable frame format].
27This format is generated and decoded automatically by the **lz4frame** library.
28Its public API is described in `lib/lz4frame.h`.
29In order to work properly, lz4frame needs all other modules present in `/lib`,
30including, lz4 and lz4hc, and also **xxhash**.
31So it's necessary to include all `*.c` and `*.h` files present in `/lib`.
32
33
34#### Advanced / Experimental API
35
36Definitions which are not guaranteed to remain stable in future versions,
37are protected behind macros, such as `LZ4_STATIC_LINKING_ONLY`.
38As the name strongly implies, these definitions should only be invoked
39in the context of static linking ***only***.
40Otherwise, dependent application may fail on API or ABI break in the future.
41The associated symbols are also not exposed by the dynamic library by default.
42Should they be nonetheless needed, it's possible to force their publication
43by using build macros `LZ4_PUBLISH_STATIC_FUNCTIONS`
44and `LZ4F_PUBLISH_STATIC_FUNCTIONS`.
45
46
47#### Build macros
48
49The following build macro can be selected to adjust source code behavior at compilation time :
50
51- `LZ4_FAST_DEC_LOOP` : this triggers a speed optimized decompression loop, more powerful on modern cpus.
52  This loop works great on `x86`, `x64` and `aarch64` cpus, and is automatically enabled for them.
53  It's also possible to enable or disable it manually, by passing `LZ4_FAST_DEC_LOOP=1` or `0` to the preprocessor.
54  For example, with `gcc` : `-DLZ4_FAST_DEC_LOOP=1`,
55  and with `make` : `CPPFLAGS+=-DLZ4_FAST_DEC_LOOP=1 make lz4`.
56
57- `LZ4_DISTANCE_MAX` : control the maximum offset that the compressor will allow.
58  Set to 65535 by default, which is the maximum value supported by lz4 format.
59  Reducing maximum distance will reduce opportunities for LZ4 to find matches,
60  hence will produce a worse compression ratio.
61  However, a smaller max distance can allow compatibility with specific decoders using limited memory budget.
62  This build macro only influences the compressed output of the compressor.
63
64- `LZ4_DISABLE_DEPRECATE_WARNINGS` : invoking a deprecated function will make the compiler generate a warning.
65  This is meant to invite users to update their source code.
66  Should this be a problem, it's generally possible to make the compiler ignore these warnings,
67  for example with `-Wno-deprecated-declarations` on `gcc`,
68  or `_CRT_SECURE_NO_WARNINGS` for Visual Studio.
69  This build macro offers another project-specific method
70  by defining `LZ4_DISABLE_DEPRECATE_WARNINGS` before including the LZ4 header files.
71
72- `LZ4_USER_MEMORY_FUNCTIONS` : replace calls to <stdlib>'s `malloc`, `calloc` and `free`
73  by user-defined functions, which must be called `LZ4_malloc()`, `LZ4_calloc()` and `LZ4_free()`.
74  User functions must be available at link time.
75
76- `LZ4_FORCE_SW_BITCOUNT` : by default, the compression algorithm tries to determine lengths
77  by using bitcount instructions, generally implemented as fast single instructions in many cpus.
78  In case the target cpus doesn't support it, or compiler intrinsic doesn't work, or feature bad performance,
79  it's possible to use an optimized software path instead.
80  This is achieved by setting this build macros .
81  In most cases, it's not expected to be necessary,
82  but it can be legitimately considered for less common platforms.
83
84- `LZ4_ALIGN_TEST` : alignment test ensures that the memory area
85  passed as argument to become a compression state is suitably aligned.
86  This test can be disabled if it proves flaky, by setting this value to 0.
87
88
89#### Amalgamation
90
91lz4 source code can be amalgamated into a single file.
92One can combine all source code into `lz4_all.c` by using following command:
93```
94cat lz4.c lz4hc.c lz4frame.c > lz4_all.c
95```
96(`cat` file order is important) then compile `lz4_all.c`.
97All `*.h` files present in `/lib` remain necessary to compile `lz4_all.c`.
98
99
100#### Windows : using MinGW+MSYS to create DLL
101
102DLL can be created using MinGW+MSYS with the `make liblz4` command.
103This command creates `dll\liblz4.dll` and the import library `dll\liblz4.lib`.
104To override the `dlltool` command  when cross-compiling on Linux, just set the `DLLTOOL` variable. Example of cross compilation on Linux with mingw-w64 64 bits:
105```
106make BUILD_STATIC=no CC=x86_64-w64-mingw32-gcc DLLTOOL=x86_64-w64-mingw32-dlltool OS=Windows_NT
107```
108The import library is only required with Visual C++.
109The header files `lz4.h`, `lz4hc.h`, `lz4frame.h` and the dynamic library
110`dll\liblz4.dll` are required to compile a project using gcc/MinGW.
111The dynamic library has to be added to linking options.
112It means that if a project that uses LZ4 consists of a single `test-dll.c`
113file it should be linked with `dll\liblz4.dll`. For example:
114```
115    $(CC) $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\liblz4.dll
116```
117The compiled executable will require LZ4 DLL which is available at `dll\liblz4.dll`.
118
119
120#### Miscellaneous
121
122Other files present in the directory are not source code. They are :
123
124 - `LICENSE` : contains the BSD license text
125 - `Makefile` : `make` script to compile and install lz4 library (static and dynamic)
126 - `liblz4.pc.in` : for `pkg-config` (used in `make install`)
127 - `README.md` : this file
128
129[official interoperable frame format]: ../doc/lz4_Frame_format.md
130[LZ4 block format]: ../doc/lz4_Block_format.md
131
132
133#### License
134
135All source material within __lib__ directory are BSD 2-Clause licensed.
136See [LICENSE](LICENSE) for details.
137The license is also reminded at the top of each source file.
138