README

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