From 1ad9a36cfb9fc669b0b18bfcd902d3e52a3d2cbb Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Wed, 6 Sep 2017 11:22:45 -0700 Subject: updated lib/README clarifications, improved wording --- lib/README.md | 56 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/lib/README.md b/lib/README.md index b40442c..7082fe3 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,44 +1,43 @@ LZ4 - Library Files ================================ -The directory contains many files, but depending on project's objectives, +The `/lib` directory contains many files, but depending on project's objectives, not all of them are necessary. #### Minimal LZ4 build The minimum required is **`lz4.c`** and **`lz4.h`**, -which will provide the fast compression and decompression algorithm. +which provides the fast compression and decompression algorithm. +They generate and decode data using [LZ4 block format]. -#### The High Compression variant of LZ4 +#### High Compression variant -For more compression at the cost of compression speed, -the High Compression variant **lz4hc** is available. -It's necessary to add **`lz4hc.c`** and **`lz4hc.h`**. -The variant still depends on regular `lz4` source files. -In particular, the decompression is still provided by `lz4.c`. +For more compression ratio at the cost of compression speed, +the High Compression variant called **lz4hc** is available. +Add files **`lz4hc.c`** and **`lz4hc.h`**. +The variant still depends on regular `lib/lz4.*` source files. -#### Compatibility issues +#### Frame variant, for interoperability -In order to produce files or streams compatible with `lz4` command line utility, +In order to produce compressed data compatible with `lz4` command line utility, it's necessary to encode lz4-compressed blocks using the [official interoperable frame format]. This format is generated and decoded automatically by the **lz4frame** library. -In order to work properly, lz4frame needs lz4 and lz4hc, and also **xxhash**, -which provides error detection. -(_Advanced stuff_ : It's possible to hide xxhash symbols into a local namespace. -This is what `liblz4` does, to avoid symbol duplication -in case a user program would link to several libraries containing xxhash symbols.) +Its public API is described in `lib/lz4frame.h`. +In order to work properly, lz4frame needs all other modules present in `/lib`, +including, lz4 and lz4hc, and also **xxhash**. +So it's necessary to include all `*.c` and `*.h` files present in `/lib`. -#### Advanced API +#### Advanced / Experimental API -A more complex `lz4frame_static.h` is also provided. -It contains definitions which are not guaranteed to remain stable within future versions. -It must be used with static linking ***only***. +A complex API defined in `lz4frame_static.h` contains definitions +which are not guaranteed to remain stable in future versions. +As a consequence, it must be used with static linking ***only***. -#### Using MinGW+MSYS to create DLL +#### Windows : using MinGW+MSYS to create DLL DLL can be created using MinGW+MSYS with the `make liblz4` command. This command creates `dll\liblz4.dll` and the import library `dll\liblz4.lib`. @@ -51,23 +50,24 @@ file it should be linked with `dll\liblz4.dll`. For example: ``` gcc $(CFLAGS) -Iinclude/ test-dll.c -o test-dll dll\liblz4.dll ``` -The compiled executable will require LZ4 DLL which is available at `dll\liblz4.dll`. +The compiled executable will require LZ4 DLL which is available at `dll\liblz4.dll`. -#### Miscellaneous +#### Miscellaneous Other files present in the directory are not source code. There are : - - LICENSE : contains the BSD license text - - Makefile : script to compile or install lz4 library (static or dynamic) - - liblz4.pc.in : for pkg-config (make install) - - README.md : this file + - `LICENSE` : contains the BSD license text + - `Makefile` : `make` script to compile and install lz4 library (static and dynamic) + - `liblz4.pc.in` : for `pkg-config` (used in `make install`) + - `README.md` : this file [official interoperable frame format]: ../doc/lz4_Frame_format.md +[LZ4 block format]: ../doc/lz4_Block_format.md -#### License +#### License All source material within __lib__ directory are BSD 2-Clause licensed. See [LICENSE](LICENSE) for details. -The license is also repeated at the top of each source file. +The license is also reminded at the top of each source file. -- cgit v0.12