diff options
| -rw-r--r-- | doc/lz4_manual.html | 18 | ||||
| -rw-r--r-- | lib/README.md | 9 | ||||
| -rw-r--r-- | lib/lz4.h | 18 | ||||
| -rw-r--r-- | lib/lz4frame.h | 13 | ||||
| -rw-r--r-- | programs/README.md | 14 |
5 files changed, 46 insertions, 26 deletions
diff --git a/doc/lz4_manual.html b/doc/lz4_manual.html index 4cd21fc..356a60d 100644 --- a/doc/lz4_manual.html +++ b/doc/lz4_manual.html @@ -26,19 +26,23 @@ multiple GB/s per core, typically reaching RAM speed limits on multi-core systems. The LZ4 compression library provides in-memory compression and decompression functions. + It gives full buffer control to user. Compression can be done in: - a single step (described as Simple Functions) - a single step, reusing a context (described in Advanced Functions) - unbounded multiple steps (described as Streaming compression) - lz4.h provides block compression functions. It gives full buffer control to user. - Decompressing an lz4-compressed block also requires metadata (such as compressed size). - Each application is free to encode such metadata in whichever way it wants. + lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md). + Decompressing a block requires additional metadata, such as its compressed size. + Each application is free to encode and pass such metadata in whichever way it wants. - An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md), - take care of encoding standard metadata alongside LZ4-compressed blocks. - Frame format is required for interoperability. - It is delivered through a companion API, declared in lz4frame.h. + lz4.h only handle blocks, it can not generate Frames. + + Blocks are different from Frames (doc/lz4_Frame_format.md). + Frames bundle both blocks and metadata in a specified manner. + This are required for compressed data to be self-contained and portable. + Frame format is delivered through a companion API, declared in lz4frame.h. + Note that the `lz4` CLI can only manage frames. <BR></pre> <a name="Chapter2"></a><h2>Version</h2><pre></pre> diff --git a/lib/README.md b/lib/README.md index c6daaea..b753195 100644 --- a/lib/README.md +++ b/lib/README.md @@ -16,13 +16,14 @@ They generate and decode data using the [LZ4 block format]. 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`**. -This variant also depends on regular `lib/lz4.*` source files. +This variant also compresses data using the [LZ4 block format], +and depends on regular `lib/lz4.*` source files. #### Frame support, for interoperability 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]. +it's necessary to use the [official interoperable frame format]. This format is generated and decoded automatically by the **lz4frame** library. Its public API is described in `lib/lz4frame.h`. In order to work properly, lz4frame needs all other modules present in `/lib`, @@ -44,7 +45,7 @@ by using build macro `LZ4_PUBLISH_STATIC_FUNCTIONS`. #### Build macros -The following build macro can be determined at compilation time : +The following build macro can be selected at compilation time : - `LZ4_FAST_DEC_LOOP` : this triggers the optimized decompression loop. This loops works great on x86/x64 cpus, and is automatically enabled on this platform. @@ -61,7 +62,7 @@ The following build macro can be determined at compilation time : - `LZ4_DISABLE_DEPRECATE_WARNINGS` : invoking a deprecated function will make the compiler generate a warning. This is meant to invite users to update their source code. - Should this be a problem, it's generally to make the compiler ignore these warnings, + Should this be a problem, it's generally possible to make the compiler ignore these warnings, for example with `-Wno-deprecated-declarations` on `gcc`, or `_CRT_SECURE_NO_WARNINGS` for Visual Studio. Another method is to define `LZ4_DISABLE_DEPRECATE_WARNINGS` @@ -51,19 +51,23 @@ extern "C" { multiple GB/s per core, typically reaching RAM speed limits on multi-core systems. The LZ4 compression library provides in-memory compression and decompression functions. + It gives full buffer control to user. Compression can be done in: - a single step (described as Simple Functions) - a single step, reusing a context (described in Advanced Functions) - unbounded multiple steps (described as Streaming compression) - lz4.h provides block compression functions. It gives full buffer control to user. - Decompressing an lz4-compressed block also requires metadata (such as compressed size). - Each application is free to encode such metadata in whichever way it wants. + lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md). + Decompressing a block requires additional metadata, such as its compressed size. + Each application is free to encode and pass such metadata in whichever way it wants. - An additional format, called LZ4 frame specification (doc/lz4_Frame_format.md), - take care of encoding standard metadata alongside LZ4-compressed blocks. - Frame format is required for interoperability. - It is delivered through a companion API, declared in lz4frame.h. + lz4.h only handle blocks, it can not generate Frames. + + Blocks are different from Frames (doc/lz4_Frame_format.md). + Frames bundle both blocks and metadata in a specified manner. + This are required for compressed data to be self-contained and portable. + Frame format is delivered through a companion API, declared in lz4frame.h. + Note that the `lz4` CLI can only manage frames. */ /*^*************************************************************** diff --git a/lib/lz4frame.h b/lib/lz4frame.h index 5c68628..ca20dc9 100644 --- a/lib/lz4frame.h +++ b/lib/lz4frame.h @@ -32,11 +32,14 @@ - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c */ -/* LZ4F is a stand-alone API to create LZ4-compressed frames - * conformant with specification v1.6.1. - * It also offers streaming capabilities. +/* LZ4F is a stand-alone API able to create and decode LZ4 frames + * conformant with specification v1.6.1 in doc/lz4_Frame_format.md . + * Generated frames are compatible with `lz4` CLI. + * + * LZ4F also offers streaming capabilities. + * * lz4.h is not required when using lz4frame.h, - * except to get constant such as LZ4_VERSION_NUMBER. + * except to extract common constant such as LZ4_VERSION_NUMBER. * */ #ifndef LZ4F_H_09782039843 @@ -195,7 +198,7 @@ typedef struct { * Simple compression function ***********************************/ -LZ4FLIB_API int LZ4F_compressionLevel_max(void); +LZ4FLIB_API int LZ4F_compressionLevel_max(void); /* v1.8.0+ */ /*! LZ4F_compressFrameBound() : * Returns the maximum possible compressed size with LZ4F_compressFrame() given srcSize and preferences. diff --git a/programs/README.md b/programs/README.md index 23c944b..c1995af 100644 --- a/programs/README.md +++ b/programs/README.md @@ -1,18 +1,26 @@ Command Line Interface for LZ4 library ============================================ -Command Line Interface (CLI) can be created using the `make` command without any additional parameters. -There are also multiple targets that create different variations of CLI: +### Build +The Command Line Interface (CLI) can be generated +using the `make` command without any additional parameters. + +The `Makefile` script supports all [standard conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html), +including standard targets (`all`, `install`, `clean`, etc.) +and standard variables (`CC`, `CFLAGS`, `CPPFLAGS`, etc.). + +For advanced use cases, there are targets to different variations of the CLI: - `lz4` : default CLI, with a command line syntax close to gzip - `lz4c` : Same as `lz4` with additional support legacy lz4 commands (incompatible with gzip) - `lz4c32` : Same as `lz4c`, but forced to compile in 32-bits mode +The CLI generates and decodes [LZ4-compressed frames](../doc/lz4_Frame_format.md). + #### Aggregation of parameters CLI supports aggregation of parameters i.e. `-b1`, `-e18`, and `-i1` can be joined into `-b1e18i1`. - #### Benchmark in Command Line Interface CLI includes in-memory compression benchmark module for lz4. The benchmark is conducted using a given filename. |