1LZ4 - Library Files 2================================ 3 4The `/lib` directory contains many files, but depending on project's objectives, 5not all of them are required. 6Limited systems may want to reduce the nb of source files to include 7as a way to reduce binary size and dependencies. 8 9Capabilities are added at the "level" granularity, detailed below. 10 11#### Level 1 : Minimal LZ4 build 12 13The minimum required is **`lz4.c`** and **`lz4.h`**, 14which provides the fast compression and decompression algorithms. 15They generate and decode data using the [LZ4 block format]. 16 17 18#### Level 2 : High Compression variant 19 20For more compression ratio at the cost of compression speed, 21the High Compression variant called **lz4hc** is available. 22Add files **`lz4hc.c`** and **`lz4hc.h`**. 23This variant also compresses data using the [LZ4 block format], 24and depends on regular `lib/lz4.*` source files. 25 26 27#### Level 3 : Frame support, for interoperability 28 29In order to produce compressed data compatible with `lz4` command line utility, 30it's necessary to use the [official interoperable frame format]. 31This format is generated and decoded automatically by the **lz4frame** library. 32Its public API is described in `lib/lz4frame.h`. 33In order to work properly, lz4frame needs all other modules present in `/lib`, 34including, lz4 and lz4hc, and also **xxhash**. 35So it's necessary to also include `xxhash.c` and `xxhash.h`. 36 37 38#### Level 4 : File compression operations 39 40As a helper around file operations, 41the library has been recently extended with `lz4file.c` and `lz4file.h` 42(still considered experimental at the time of this writing). 43These helpers allow opening, reading, writing, and closing files 44using transparent LZ4 compression / decompression. 45As a consequence, using `lz4file` adds a dependency on `<stdio.h>`. 46 47`lz4file` relies on `lz4frame` in order to produce compressed data 48conformant to the [LZ4 Frame format] specification. 49Consequently, to enable this capability, 50it's necessary to include all `*.c` and `*.h` files from `lib/` directory. 51 52 53#### Advanced / Experimental API 54 55Definitions which are not guaranteed to remain stable in future versions, 56are protected behind macros, such as `LZ4_STATIC_LINKING_ONLY`. 57As the name suggests, these definitions should only be invoked 58in the context of static linking ***only***. 59Otherwise, dependent application may fail on API or ABI break in the future. 60The associated symbols are also not exposed by the dynamic library by default. 61Should they be nonetheless needed, it's possible to force their publication 62by using build macros `LZ4_PUBLISH_STATIC_FUNCTIONS` 63and `LZ4F_PUBLISH_STATIC_FUNCTIONS`. 64 65 66#### Build macros 67 68The following build macro can be selected to adjust source code behavior at compilation time : 69 70- `LZ4_FAST_DEC_LOOP` : this triggers a speed optimized decompression loop, more powerful on modern cpus. 71 This loop works great on `x86`, `x64` and `aarch64` cpus, and is automatically enabled for them. 72 It's also possible to enable or disable it manually, by passing `LZ4_FAST_DEC_LOOP=1` or `0` to the preprocessor. 73 For example, with `gcc` : `-DLZ4_FAST_DEC_LOOP=1`, 74 and with `make` : `CPPFLAGS+=-DLZ4_FAST_DEC_LOOP=1 make lz4`. 75 76- `LZ4_DISTANCE_MAX` : control the maximum offset that the compressor will allow. 77 Set to 65535 by default, which is the maximum value supported by lz4 format. 78 Reducing maximum distance will reduce opportunities for LZ4 to find matches, 79 hence will produce a worse compression ratio. 80 Setting a smaller max distance could allow compatibility with specific decoders with limited memory budget. 81 This build macro only influences the compressed output of the compressor. 82 83- `LZ4_DISABLE_DEPRECATE_WARNINGS` : invoking a deprecated function will make the compiler generate a warning. 84 This is meant to invite users to update their source code. 85 Should this be a problem, it's generally possible to make the compiler ignore these warnings, 86 for example with `-Wno-deprecated-declarations` on `gcc`, 87 or `_CRT_SECURE_NO_WARNINGS` for Visual Studio. 88 This build macro offers another project-specific method 89 by defining `LZ4_DISABLE_DEPRECATE_WARNINGS` before including the LZ4 header files. 90 91- `LZ4_FORCE_SW_BITCOUNT` : by default, the compression algorithm tries to determine lengths 92 by using bitcount instructions, generally implemented as fast single instructions in many cpus. 93 In case the target cpus doesn't support it, or compiler intrinsic doesn't work, or feature bad performance, 94 it's possible to use an optimized software path instead. 95 This is achieved by setting this build macros. 96 In most cases, it's not expected to be necessary, 97 but it can be legitimately considered for less common platforms. 98 99- `LZ4_ALIGN_TEST` : alignment test ensures that the memory area 100 passed as argument to become a compression state is suitably aligned. 101 This test can be disabled if it proves flaky, by setting this value to 0. 102 103- `LZ4_USER_MEMORY_FUNCTIONS` : replace calls to `<stdlib.h>`'s `malloc()`, `calloc()` and `free()` 104 by user-defined functions, which must be named `LZ4_malloc()`, `LZ4_calloc()` and `LZ4_free()`. 105 User functions must be available at link time. 106 107- `LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION` : 108 Remove support of dynamic memory allocation. 109 For more details, see description of this macro in `lib/lz4.c`. 110 111- `LZ4_STATIC_LINKING_ONLY_ENDIANNESS_INDEPENDENT_OUTPUT` : experimental feature aimed at producing the same 112 compressed output on platforms of different endianness (i.e. little-endian and big-endian). 113 Output on little-endian platforms shall remain unchanged, while big-endian platforms will start producing 114 the same output as little-endian ones. This isn't expected to impact backward- and forward-compatibility 115 in any way. 116 117- `LZ4_FREESTANDING` : by setting this build macro to 1, 118 LZ4/HC removes dependencies on the C standard library, 119 including allocation functions and `memmove()`, `memcpy()`, and `memset()`. 120 This build macro is designed to help use LZ4/HC in restricted environments 121 (embedded, bootloader, etc). 122 For more details, see description of this macro in `lib/lz4.h`. 123 124- `LZ4_HEAPMODE` : Select how stateless compression functions like `LZ4_compress_default()` 125 allocate memory for their hash table, 126 in memory stack (0:default, fastest), or in memory heap (1:requires malloc()). 127 128- `LZ4HC_HEAPMODE` : Select how stateless HC compression functions like `LZ4_compress_HC()` 129 allocate memory for their workspace: 130 in stack (0), or in heap (1:default). 131 Since workspace is rather large, stack can be inconvenient, hence heap mode is recommended. 132 133- `LZ4F_HEAPMODE` : selects how `LZ4F_compressFrame()` allocates the compression state, 134 either on stack (default, value 0) or using heap memory (value 1). 135 136 137#### Makefile variables 138 139The following `Makefile` variables can be selected to alter the profile of produced binaries : 140- `BUILD_SHARED` : generate `liblz4` dynamic library (enabled by default) 141- `BUILD_STATIC` : generate `liblz4` static library (enabled by default) 142 143 144#### Amalgamation 145 146lz4 source code can be amalgamated into a single file. 147One can combine all source code into `lz4_all.c` by using following command: 148``` 149cat lz4.c lz4hc.c lz4frame.c > lz4_all.c 150``` 151(`cat` file order is important) then compile `lz4_all.c`. 152All `*.h` files present in `/lib` remain necessary to compile `lz4_all.c`. 153 154 155#### Windows : using MinGW+MSYS to create DLL 156 157DLL can be created using MinGW+MSYS with the `make liblz4` command. 158This command creates `dll\liblz4.dll` and the import library `dll\liblz4.lib`. 159To 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: 160``` 161make BUILD_STATIC=no CC=x86_64-w64-mingw32-gcc DLLTOOL=x86_64-w64-mingw32-dlltool OS=Windows_NT 162``` 163The import library is only required with Visual C++. 164The header files `lz4.h`, `lz4hc.h`, `lz4frame.h` and the dynamic library 165`dll\liblz4.dll` are required to compile a project using gcc/MinGW. 166The dynamic library has to be added to linking options. 167It means that if a project that uses LZ4 consists of a single `test-dll.c` 168file it should be linked with `dll\liblz4.dll`. For example: 169``` 170 $(CC) $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\liblz4.dll 171``` 172The compiled executable will require LZ4 DLL which is available at `dll\liblz4.dll`. 173 174 175#### Miscellaneous 176 177Other files present in the directory are not source code. They are : 178 179 - `LICENSE` : contains the BSD license text 180 - `Makefile` : `make` script to compile and install lz4 library (static and dynamic) 181 - `liblz4.pc.in` : for `pkg-config` (used in `make install`) 182 - `README.md` : this file 183 184[official interoperable frame format]: ../doc/lz4_Frame_format.md 185[LZ4 Frame format]: ../doc/lz4_Frame_format.md 186[LZ4 block format]: ../doc/lz4_Block_format.md 187 188 189#### License 190 191All source material within __lib__ directory are BSD 2-Clause licensed. 192See [LICENSE](LICENSE) for details. 193The license is also reminded at the top of each source file. 194