README

   1
   2 LZMA Utils
   3 ----------
   4
   5 Warning
   6
   7     This is an early alpha version. Don't trust the files produced by
   8     this version of the software - not even if the software can
   9     uncompress the files properly! This is because the file format
  10     isn't completely frozen yet.
  11
  12     So please test a lot, but don't use for anything serious yet.
  13
  14
  15 Overview
  16
  17     LZMA is a general purporse compression algorithm designed by
  18     Igor Pavlov as part of 7-Zip. It provides high compression ratio
  19     while keeping the decompression speed fast.
  20
  21     LZMA Utils are an attempt to make LZMA compression easy to use
  22     on free (as in freedom) operating systems. This is achieved by
  23     providing tools and libraries which are similar to use than the
  24     equivalents of the most popular existing compression algorithms.
  25
  26     LZMA Utils consist of a few relatively separate parts:
  27       * liblzma is an encoder/decoder library with support for several
  28         filters (algorithm implementations). The primary filter is LZMA.
  29       * libzfile enables reading from and writing to gzip, bzip2 and
  30         LZMA compressed and uncompressed files with an API similar to
  31         the standard ANSI-C file I/O.
  32         [ NOTE: libzfile is not implemented yet. ]
  33       * lzma command line tool has almost identical syntax than gzip
  34         and bzip2. It makes LZMA easy for average users, but also
  35         provides advanced options to finetune the compression settings.
  36       * A few shell scripts make diffing and grepping LZMA compressed
  37         files easy. The scripts were adapted from gzip and bzip2.
  38
  39
  40 Supported platforms
  41
  42     LZMA Utils are developed on GNU+Linux, but they should work at
  43     least on *BSDs and Solaris. They probably work on some other
  44     POSIX-like operating systems too.
  45
  46     If you use GCC to compile LZMA Utils, you need at least version
  47     3.x.x. GCC version 2.xx.x doesn't support some C99 features used
  48     in LZMA Utils source code, thus GCC 2 won't compile LZMA Utils.
  49
  50     If you have written patches to make LZMA Utils to work on previously
  51     unsupported platform, please send the patches to me! I will consider
  52     including them to the official version. It's nice to minimize the
  53     need of third-party patching.
  54
  55     One exception: Don't request or send patches to change the whole
  56     source package to C89. I find C99 substantially nicer to write and
  57     maintain. However, the public library headers must be in C89 to
  58     avoid frustrating those who maintain programs, which are strictly
  59     in C89 or C++.
  60
  61
  62 Version numbering
  63
  64     Starting from LZMA Utils 5, the version number of LZMA Utils has
  65     absolutely nothing to do with the version number of LZMA SDK or
  66     7-Zip. The new version number format of LZMA Utils is X.Y.ZS:
  67
  68       - X is the major version. When this is incremented, the library
  69         API and ABI break.
  70
  71       - Y is the minor version. It is incremented when new features are
  72         added without breaking existing API or ABI. Even Y indicates
  73         stable release and odd Y indicates unstable (alpha or beta
  74         version).
  75
  76       - Z is the revision. This has different meaning for stable and
  77         unstable releases:
  78           * Stable: Z is incremented when bugs get fixed without adding
  79             any new features.
  80           * Unstable: Z is just a counter. API or ABI of features added
  81             in earlier unstable releases having the same X.Y may break.
  82
  83       - S indicates stability of the release. It is missing from the
  84         stable releases where Y is an even number. When Y is odd, S
  85         is either "alpha" or "beta" to make it very clear that such
  86         versions are not stable releases. The same X.Y.Z combination is
  87         not used for more than one stability level i.e. after X.Y.Zalpha,
  88         the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta.
  89
  90
  91 configure options
  92
  93     If you are not familiar with `configure' scripts, read the file
  94     INSTALL first.
  95
  96     In most cases, the default --enable/--disable/--with/--without options
  97     are what you want. Don't touch them if you are unsure.
  98
  99     --disable-encoder
 100                 Do not compile the encoder component of liblzma. This
 101                 implies --disable-match-finders. If you need only
 102                 the decoder, you can decrease the library size
 103                 dramatically with this option.
 104
 105                 The default is to build the encoder.
 106
 107     --disable-decoder
 108                 Do not compile the decoder component of liblzma.
 109
 110                 The default is to build the decoder.
 111
 112     --enable-filters=
 113                 liblzma supports several filters. See liblzma-intro.txt
 114                 for a little more information about these.
 115
 116                 The default is to build all the filters.
 117
 118     --enable-match-finders=
 119                 liblzma includes two categories of match finders:
 120                 hash chains and binary trees. Hash chains (hc3 and hc4)
 121                 are quite fast but they don't provide the best compression
 122                 ratio. Binary trees (bt2, bt3 and bt4) give excellent
 123                 compression ratio, but they are slower and need more
 124                 memory than hash chains.
 125
 126                 You need to enable at least one match finder to build the
 127                 LZMA filter encoder. Usually hash chains are used only in
 128                 the fast mode, while binary trees are used to when the best
 129                 compression ratio is wanted.
 130
 131                 The default is to build all the match finders.
 132
 133     --enable-checks=
 134                 liblzma support multiple integrity checks. CRC32 is
 135                 mandatory, and cannot be omitted. See liblzma-intro.txt
 136                 for more information about usage of the integrity checks.
 137
 138     --disable-assembler
 139                 liblzma includes some assembler optimizations. Currently
 140                 there is only assembler code for CRC32 and CRC64 for
 141                 32-bit x86.
 142
 143                 All the assembler code in liblzma is position-independent
 144                 code, which is suitable for use in shared libraries and
 145                 position-independent executables. So far only i386
 146                 instructions are used, but the code is optimized for i686
 147                 class CPUs. If you are compiling liblzma exclusively for
 148                 pre-i686 systems, you may want to disable the assembler
 149                 code.
 150
 151     --enable-small
 152                 Omits precomputed tables. This makes liblzma a few KiB
 153                 smaller. Startup time increases, because the tables need
 154                 to be computed first.
 155
 156     --enable-debug
 157                 This enables the assert() macro and possibly some other
 158                 run-time consistency checks. It slows down things somewhat,
 159                 so you normally don't want to have this enabled.
 160
 161     --enable-werror
 162                 Makes all compiler warnings an error, that abort the
 163                 compilation. This may help catching bugs, and should work
 164                 on most systems. This has no effect on the resulting
 165                 binaries.
 166
 167
 168 Static vs. dynamic linking of the command line tools
 169
 170     By default, the command line tools are linked statically against
 171     liblzma. There a are a few reasons:
 172
 173       - The executable(s) can be in /bin while the shared liblzma can still
 174         be in /usr/lib (if the distro uses such file system hierachy).
 175
 176       - It's easier to copy the executables to other systems, since they
 177         depend only on libc.
 178
 179       - It's slightly faster on some architectures like x86.
 180
 181     If you don't like this, you can get the command line tools linked
 182     against the shared liblzma by specifying --disable-static to configure.
 183     This disables building static liblzma completely.
 184