From 23706fb743564ec5ab663b8d3105440b5a7783fb Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Sat, 19 Aug 2017 01:14:36 -0700 Subject: [PATCH] updated doc on compilation variables --- programs/README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/programs/README.md b/programs/README.md index bd8fba069..3ac2c8f6d 100644 --- a/programs/README.md +++ b/programs/README.md @@ -3,39 +3,38 @@ Command Line Interface for Zstandard library Command Line Interface (CLI) can be created using the `make` command without any additional parameters. There are however other Makefile targets that create different variations of CLI: -- `zstd` : default CLI supporting gzip-like arguments; includes dictionary builder, benchmark, and support for decompression of legacy zstd versions -- `zstd32` : Same as `zstd`, but forced to compile in 32-bits mode -- `zstd_nolegacy` : Same as `zstd` except of support for decompression of legacy zstd versions -- `zstd-small` : CLI optimized for minimal size; without dictionary builder, benchmark, and support for decompression of legacy zstd versions -- `zstd-compress` : compressor-only version of CLI; without dictionary builder, benchmark, and support for decompression of legacy zstd versions -- `zstd-decompress` : decompressor-only version of CLI; without dictionary builder, benchmark, and support for decompression of legacy zstd versions +- `zstd` : default CLI supporting gzip-like arguments; includes dictionary builder, benchmark, and support for decompression of legacy zstd formats +- `zstd_nolegacy` : Same as `zstd` but without support for legacy zstd formats +- `zstd-small` : CLI optimized for minimal size; no dictionary builder, no benchmark, and no support for legacy zstd formats +- `zstd-compress` : version of CLI which can only compress into zstd format +- `zstd-decompress` : version of CLI which can only decompress zstd format #### Compilation variables `zstd` tries to detect and use the following features automatically : - __HAVE_THREAD__ : multithreading is automatically enabled when `pthread` is detected. - It's possible to disable multithread support, by either compiling `zstd-nomt` target or using HAVE_THREAD=0 variable. + It's possible to disable multithread support, by setting HAVE_THREAD=0 . Example : make zstd HAVE_THREAD=0 It's also possible to force compilation with multithread support, using HAVE_THREAD=1. In which case, linking stage will fail if `pthread` library cannot be found. This might be useful to prevent silent feature disabling. - __HAVE_ZLIB__ : `zstd` can compress and decompress files in `.gz` format. - This is done through command `--format=gzip`. + This is ordered through command `--format=gzip`. Alternatively, symlinks named `gzip` or `gunzip` will mimic intended behavior. `.gz` support is automatically enabled when `zlib` library is detected at build time. - It's possible to disable `.gz` support, by either compiling `zstd-nogz` target or using HAVE_ZLIB=0 variable. + It's possible to disable `.gz` support, by setting HAVE_ZLIB=0. Example : make zstd HAVE_ZLIB=0 It's also possible to force compilation with zlib support, using HAVE_ZLIB=1. In which case, linking stage will fail if `zlib` library cannot be found. This might be useful to prevent silent feature disabling. - __HAVE_LZMA__ : `zstd` can compress and decompress files in `.xz` and `.lzma` formats. - This is done through commands `--format=xz` and `--format=lzma` respectively. + This is ordered through commands `--format=xz` and `--format=lzma` respectively. Alternatively, symlinks named `xz`, `unxz`, `lzma`, or `unlzma` will mimic intended behavior. `.xz` and `.lzma` support is automatically enabled when `lzma` library is detected at build time. - It's possible to disable `.xz` and `.lzma` support, by either compiling `zstd-noxz` target or using HAVE_LZMA=0 variable. + It's possible to disable `.xz` and `.lzma` support, by setting HAVE_LZMA=0 . Example : make zstd HAVE_LZMA=0 It's also possible to force compilation with lzma support, using HAVE_LZMA=1. In which case, linking stage will fail if `lzma` library cannot be found. @@ -61,7 +60,7 @@ will rely more and more on previously decoded content to compress the rest of th Usage of the dictionary builder and created dictionaries with CLI: -1. Create the dictionary : `zstd --train FullPathToTrainingSet/* -o dictionaryName` +1. Create the dictionary : `zstd --train PathToTrainingSet/* -o dictionaryName` 2. Compress with the dictionary: `zstd FILE -D dictionaryName` 3. Decompress with the dictionary: `zstd --decompress FILE.zst -D dictionaryName` @@ -70,8 +69,8 @@ Usage of the dictionary builder and created dictionaries with CLI: CLI includes in-memory compression benchmark module for zstd. The benchmark is conducted using given filenames. The files are read into memory and joined together. It makes benchmark more precise as it eliminates I/O overhead. -Many filenames can be supplied as multiple parameters, parameters with wildcards or -names of directories can be used as parameters with the `-r` option. +Multiple filenames can be supplied, as multiple parameters, with wildcards, +or names of directories can be used as parameters with `-r` option. The benchmark measures ratio, compressed size, compression and decompression speed. One can select compression levels starting from `-b` and ending with `-e`. @@ -101,13 +100,14 @@ Advanced arguments : -v : verbose mode; specify multiple times to increase verbosity -q : suppress warnings; specify twice to suppress errors too -c : force write to standard output, even if it is the console + -l : print information about zstd compressed files --ultra : enable levels beyond 19, up to 22 (requires more memory) - -T# : use # threads for compression (default:1) - -B# : select size of each job (default:0==automatic) --no-dictID : don't write dictID into header (dictionary compression) --[no-]check : integrity check (default:enabled) -r : operate recursively on directories --format=gzip : compress files to the .gz format +--format=xz : compress files to the .xz format +--format=lzma : compress files to the .lzma format --test : test compressed file integrity --[no-]sparse : sparse mode (default:disabled) -M# : Set a memory usage limit for decompression -- 2.47.2