Adding README.Debian documenting lzip-alternatives.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 94 insertions, 0 deletions

diff --git a/debian/lzip.README.Debian b/debian/lzip.README.Debian
new file mode 100644
index 0000000..38e3c90
--- /dev/null
+++ b/debian/lzip.README.Debian
@@ -0,0 +1,94 @@
+Lzip for Debian
+===============
+
+1. Lzip implementations
+-----------------------
+
+Lzip is available in different implementations:
+
+  lzip           original C++ implementation
+  plzip          parallel C++ implementation
+
+  lziprecover    C++ implementation with extra recovery functionality
+  clzip          C implementation
+
+  lunzip         C implementation, decompressor only
+  xlunzip        C implementation using lzip_decompress kernel module, decompressor only
+
+  lzd            simple C implementation, decompressor only, educational purpose
+  minilzip       simple C implementation, using lzlib, educational purpose
+  pdlzip         simple C implementation, Public Domain
+
+All Lzip implementations are fully compatible (files can be compressed and
+decompressed with any implementation interchangeably).
+
+All Lzip implementations support the same command line switches: if an option
+is not implemented it is silently ignored (e.g. the -n option to set the number
+of threads is accepted by all implementations but only plzip makes use of it).
+
+
+2. update-alternatives
+----------------------
+
+On Debian based systems all Lzip implementations are installed as
+lzip.$implementation (e.g. /usr/bin/lzip.plzip) and /usr/bin/lzip is a symlink
+managed by update-altenatives to point to the currently selected
+implementation. All Lzip packages provide the virtual lzip-alternatives package.
+
+The following automatic priorities are used:
+
+  Decompressors:
+    xlunzip        -3000
+    lzd            -2000
+    lunzip         -1000
+
+  Compressor and decompressors:
+    lzlib          1000
+    pdlzip         2000
+    clzip          3000
+    lziprecover    4000
+    lzip           5000
+    plzip          6000
+
+
+This allows:
+
+  * users to manually switch the implementation conveniently with:
+
+      sudo update-alternative --config lzip
+
+    if more than one lzip imlementation is installed.
+
+  * automatically have the system use the 'best' implementation installed.
+
+  * allows to switch back and forth, transparently, from single-threaded lzip
+    to parallel plzip with one update-alternative command - no scripts or
+    commands need to be changed.
+
+    If you were using lzip before, install plzip and all your lzip operations
+    are now parallelized automatically.
+
+
+3. Best practise
+----------------
+
+To make the best use of lzip, the following should be considered:
+
+  * use lzip in scripts and commands, don't hardcode a specific implementation
+    (e.g. use lzip, not plzip).
+
+  * use alternative depends in debian packages, don't depend on a specific
+    implementation (e.g. use 'Depends: lzip-alternative | lzip' or
+    'Depends: lzip-alternative | plzip', not 'Depends: lzip').
+
+
+4. See also
+-----------
+
+  * tarlz: archiver with multimember lzip compression
+  * zutils: utilities for dealing with compressed files transparently
+
+  * Xz format inadequate for long-term archiving
+    http://lzip.nongnu.org/xz_inadequate.html
+
+ -- Daniel Baumann <daniel.baumann@progress-linux.org>  Sun, 26 Aug 2018 11:06:17 +0200