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 Platform-specific notes
  73
  74     On some Tru64 systems using the native C99 compiler, the configure
  75     script may reject the compiler as non-C99 compiler. This may happen
  76     if there is no stdbool.h available. You can still compile XZ Utils
  77     on such a system by passing ac_cv_prog_cc_c99= to configure script.
  78     Fixing this bug seems to be non-trivial since if the configure
  79     doesn't check for stdbool.h, it runs into problems at least on
  80     Solaris.
  81
  82
  83 Version numbering
  84
  85     The version number of XZ Utils has absolutely nothing to do with
  86     the version number of LZMA SDK or 7-Zip. The new version number
  87     format of XZ Utils is X.Y.ZS:
  88
  89       - X is the major version. When this is incremented, the library
  90         API and ABI break.
  91
  92       - Y is the minor version. It is incremented when new features are
  93         added without breaking existing API or ABI. Even Y indicates
  94         stable release and odd Y indicates unstable (alpha or beta
  95         version).
  96
  97       - Z is the revision. This has different meaning for stable and
  98         unstable releases:
  99           * Stable: Z is incremented when bugs get fixed without adding
 100             any new features.
 101           * Unstable: Z is just a counter. API or ABI of features added
 102             in earlier unstable releases having the same X.Y may break.
 103
 104       - S indicates stability of the release. It is missing from the
 105         stable releases where Y is an even number. When Y is odd, S
 106         is either "alpha" or "beta" to make it very clear that such
 107         versions are not stable releases. The same X.Y.Z combination is
 108         not used for more than one stability level i.e. after X.Y.Zalpha,
 109         the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta.
 110
 111
 112 configure options
 113
 114     If you are not familiar with `configure' scripts, read the file
 115     INSTALL first.
 116
 117     In most cases, the default --enable/--disable/--with/--without options
 118     are what you want. Don't touch them if you are unsure.
 119
 120     --disable-encoder
 121                 Do not compile the encoder component of liblzma. This
 122                 implies --disable-match-finders. If you need only
 123                 the decoder, you can decrease the library size
 124                 dramatically with this option.
 125
 126                 The default is to build the encoder.
 127
 128     --disable-decoder
 129                 Do not compile the decoder component of liblzma.
 130
 131                 The default is to build the decoder.
 132
 133     --enable-filters=
 134                 liblzma supports several filters. See liblzma-intro.txt
 135                 for a little more information about these.
 136
 137                 The default is to build all the filters.
 138
 139     --enable-match-finders=
 140                 liblzma includes two categories of match finders:
 141                 hash chains and binary trees. Hash chains (hc3 and hc4)
 142                 are quite fast but they don't provide the best compression
 143                 ratio. Binary trees (bt2, bt3 and bt4) give excellent
 144                 compression ratio, but they are slower and need more
 145                 memory than hash chains.
 146
 147                 You need to enable at least one match finder to build the
 148                 LZMA filter encoder. Usually hash chains are used only in
 149                 the fast mode, while binary trees are used to when the best
 150                 compression ratio is wanted.
 151
 152                 The default is to build all the match finders.
 153
 154     --enable-checks=
 155                 liblzma support multiple integrity checks. CRC32 is
 156                 mandatory, and cannot be omitted. See liblzma-intro.txt
 157                 for more information about usage of the integrity checks.
 158
 159     --disable-assembler
 160                 liblzma includes some assembler optimizations. Currently
 161                 there is only assembler code for CRC32 and CRC64 for
 162                 32-bit x86.
 163
 164                 All the assembler code in liblzma is position-independent
 165                 code, which is suitable for use in shared libraries and
 166                 position-independent executables. So far only i386
 167                 instructions are used, but the code is optimized for i686
 168                 class CPUs. If you are compiling liblzma exclusively for
 169                 pre-i686 systems, you may want to disable the assembler
 170                 code.
 171
 172     --enable-small
 173                 Omits precomputed tables. This makes liblzma a few KiB
 174                 smaller. Startup time increases, because the tables need
 175                 to be computed first.
 176
 177     --enable-debug
 178                 This enables the assert() macro and possibly some other
 179                 run-time consistency checks. It slows down things somewhat,
 180                 so you normally don't want to have this enabled.
 181
 182     --enable-werror
 183                 Makes all compiler warnings an error, that abort the
 184                 compilation. This may help catching bugs, and should work
 185                 on most systems. This has no effect on the resulting
 186                 binaries.
 187
 188
 189 Static vs. dynamic linking of the command line tools
 190
 191     By default, the command line tools are linked statically against
 192     liblzma. There a are a few reasons:
 193
 194       - The executable(s) can be in /bin while the shared liblzma can still
 195         be in /usr/lib (if the distro uses such file system hierachy).
 196
 197       - It's easier to copy the executables to other systems, since they
 198         depend only on libc.
 199
 200       - It's slightly faster on some architectures like x86.
 201
 202     If you don't like this, you can get the command line tools linked
 203     against the shared liblzma by specifying --disable-static to configure.
 204     This disables building static liblzma completely.
 205