mfbt/lz4/README.md

   1 LZ4 - Library Files
   2 ================================
   3
   4 The `/lib` directory contains many files, but depending on project's objectives,
   5 not all of them are required.
   6 Limited systems may want to reduce the nb of source files to include
   7 as a way to reduce binary size and dependencies.
   8
   9 Capabilities are added at the "level" granularity, detailed below.
  10
  11 #### Level 1 : Minimal LZ4 build
  12
  13 The minimum required is **`lz4.c`** and **`lz4.h`**,
  14 which provides the fast compression and decompression algorithms.
  15 They generate and decode data using the [LZ4 block format].
  16
  17
  18 #### Level 2 : High Compression variant
  19
  20 For more compression ratio at the cost of compression speed,
  21 the High Compression variant called **lz4hc** is available.
  22 Add files **`lz4hc.c`** and **`lz4hc.h`**.
  23 This variant also compresses data using the [LZ4 block format],
  24 and depends on regular `lib/lz4.*` source files.
  25
  26
  27 #### Level 3 : Frame support, for interoperability
  28
  29 In order to produce compressed data compatible with `lz4` command line utility,
  30 it's necessary to use the [official interoperable frame format].
  31 This format is generated and decoded automatically by the **lz4frame** library.
  32 Its public API is described in `lib/lz4frame.h`.
  33 In order to work properly, lz4frame needs all other modules present in `/lib`,
  34 including, lz4 and lz4hc, and also **xxhash**.
  35 So it's necessary to also include `xxhash.c` and `xxhash.h`.
  36
  37
  38 #### Level 4 : File compression operations
  39
  40 As a helper around file operations,
  41 the library has been recently extended with `lz4file.c` and `lz4file.h`
  42 (still considered experimental at the time of this writing).
  43 These helpers allow opening, reading, writing, and closing files
  44 using transparent LZ4 compression / decompression.
  45 As a consequence, using `lz4file` adds a dependency on `<stdio.h>`.
  46
  47 `lz4file` relies on `lz4frame` in order to produce compressed data
  48 conformant to the [LZ4 Frame format] specification.
  49 Consequently, to enable this capability,
  50 it's necessary to include all `*.c` and `*.h` files from `lib/` directory.
  51
  52
  53 #### Advanced / Experimental API
  54
  55 Definitions which are not guaranteed to remain stable in future versions,
  56 are protected behind macros, such as `LZ4_STATIC_LINKING_ONLY`.
  57 As the name suggests, these definitions should only be invoked
  58 in the context of static linking ***only***.
  59 Otherwise, dependent application may fail on API or ABI break in the future.
  60 The associated symbols are also not exposed by the dynamic library by default.
  61 Should they be nonetheless needed, it's possible to force their publication
  62 by using build macros `LZ4_PUBLISH_STATIC_FUNCTIONS`
  63 and `LZ4F_PUBLISH_STATIC_FUNCTIONS`.
  64
  65
  66 #### Build macros
  67
  68 The 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_FREESTANDING` : by setting this build macro to 1,
 112   LZ4/HC removes dependencies on the C standard library,
 113   including allocation functions and `memmove()`, `memcpy()`, and `memset()`.
 114   This build macro is designed to help use LZ4/HC in restricted environments
 115   (embedded, bootloader, etc).
 116   For more details, see description of this macro in `lib/lz4.h`.
 117
 118
 119
 120 #### Amalgamation
 121
 122 lz4 source code can be amalgamated into a single file.
 123 One can combine all source code into `lz4_all.c` by using following command:
 124 ```
 125 cat lz4.c lz4hc.c lz4frame.c > lz4_all.c
 126 ```
 127 (`cat` file order is important) then compile `lz4_all.c`.
 128 All `*.h` files present in `/lib` remain necessary to compile `lz4_all.c`.
 129
 130
 131 #### Windows : using MinGW+MSYS to create DLL
 132
 133 DLL can be created using MinGW+MSYS with the `make liblz4` command.
 134 This command creates `dll\liblz4.dll` and the import library `dll\liblz4.lib`.
 135 To 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:
 136 ```
 137 make BUILD_STATIC=no CC=x86_64-w64-mingw32-gcc DLLTOOL=x86_64-w64-mingw32-dlltool OS=Windows_NT
 138 ```
 139 The import library is only required with Visual C++.
 140 The header files `lz4.h`, `lz4hc.h`, `lz4frame.h` and the dynamic library
 141 `dll\liblz4.dll` are required to compile a project using gcc/MinGW.
 142 The dynamic library has to be added to linking options.
 143 It means that if a project that uses LZ4 consists of a single `test-dll.c`
 144 file it should be linked with `dll\liblz4.dll`. For example:
 145 ```
 146     $(CC) $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\liblz4.dll
 147 ```
 148 The compiled executable will require LZ4 DLL which is available at `dll\liblz4.dll`.
 149
 150
 151 #### Miscellaneous
 152
 153 Other files present in the directory are not source code. They are :
 154
 155  - `LICENSE` : contains the BSD license text
 156  - `Makefile` : `make` script to compile and install lz4 library (static and dynamic)
 157  - `liblz4.pc.in` : for `pkg-config` (used in `make install`)
 158  - `README.md` : this file
 159
 160 [official interoperable frame format]: ../doc/lz4_Frame_format.md
 161 [LZ4 Frame format]: ../doc/lz4_Frame_format.md
 162 [LZ4 block format]: ../doc/lz4_Block_format.md
 163
 164
 165 #### License
 166
 167 All source material within __lib__ directory are BSD 2-Clause licensed.
 168 See [LICENSE](LICENSE) for details.
 169 The license is also reminded at the top of each source file.