liblzma/README

XZ Utils
========

Important

    This is a beta version. The .xz file format is now stable though,
    which means that files created with the beta version will be
    decompressible with all future XZ Utils versions too (assuming
    that there are no catastrophic bugs).

    liblzma API is pretty stable now, although minor tweaks may still
    be done if really needed. The ABI is not stable yet. The major
    soname will be bumped right before the first stable release.
    Probably it will be bumped to something like .so.5.0.0 because
    some distributions using the alpha versions already had to use
    other versions than .so.0.0.0.

    Excluding the Doxygen style docs in libilzma API headers, the
    documentation in this package (including the rest of this
    README) is not very up to date, and may contain incorrect or
    misleading information.


Overview

    LZMA is a general purporse compression algorithm designed by
    Igor Pavlov as part of 7-Zip. It provides high compression ratio
    while keeping the decompression speed fast.

    XZ Utils are an attempt to make LZMA compression easy to use
    on free (as in freedom) operating systems. This is achieved by
    providing tools and libraries which are similar to use than the
    equivalents of the most popular existing compression algorithms.

    XZ Utils consist of a few relatively separate parts:
      * liblzma is an encoder/decoder library with support for several
        filters (algorithm implementations). The primary filter is LZMA.
      * libzfile (or whatever the name will be) enables reading from and
        writing to gzip, bzip2 and LZMA compressed and uncompressed files
        with an API similar to the standard ANSI-C file I/O.
        [ NOTE: libzfile is not implemented yet. ]
      * xz command line tool has almost identical syntax than gzip
        and bzip2. It makes LZMA easy for average users, but also
        provides advanced options to finetune the compression settings.
      * A few shell scripts make diffing and grepping LZMA compressed
        files easy. The scripts were adapted from gzip and bzip2.


Supported platforms

    XZ Utils are developed on GNU+Linux, but they should work at
    least on *BSDs and Solaris. They probably work on some other
    POSIX-like operating systems too.

    If you use GCC to compile XZ Utils, you need at least version
    3.x.x. GCC version 2.xx.x doesn't support some C99 features used
    in XZ Utils source code, thus GCC 2 won't compile XZ Utils.

    If you have written patches to make XZ Utils to work on previously
    unsupported platform, please send the patches to me! I will consider
    including them to the official version. It's nice to minimize the
    need of third-party patching.

    One exception: Don't request or send patches to change the whole
    source package to C89. I find C99 substantially nicer to write and
    maintain. However, the public library headers must be in C89 to
    avoid frustrating those who maintain programs, which are strictly
    in C89 or C++.


Version numbering

    The version number of XZ Utils has absolutely nothing to do with
    the version number of LZMA SDK or 7-Zip. The new version number
    format of XZ Utils is X.Y.ZS:

      - X is the major version. When this is incremented, the library
        API and ABI break.

      - Y is the minor version. It is incremented when new features are
        added without breaking existing API or ABI. Even Y indicates
        stable release and odd Y indicates unstable (alpha or beta
        version).

      - Z is the revision. This has different meaning for stable and
        unstable releases:
          * Stable: Z is incremented when bugs get fixed without adding
            any new features.
          * Unstable: Z is just a counter. API or ABI of features added
            in earlier unstable releases having the same X.Y may break.

      - S indicates stability of the release. It is missing from the
        stable releases where Y is an even number. When Y is odd, S
        is either "alpha" or "beta" to make it very clear that such
        versions are not stable releases. The same X.Y.Z combination is
        not used for more than one stability level i.e. after X.Y.Zalpha,
        the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta.


configure options

    If you are not familiar with `configure' scripts, read the file
    INSTALL first.

    In most cases, the default --enable/--disable/--with/--without options
    are what you want. Don't touch them if you are unsure.

    --disable-encoder
                Do not compile the encoder component of liblzma. This
                implies --disable-match-finders. If you need only
                the decoder, you can decrease the library size
                dramatically with this option.

                The default is to build the encoder.

    --disable-decoder
                Do not compile the decoder component of liblzma.

                The default is to build the decoder.

    --enable-filters=
                liblzma supports several filters. See liblzma-intro.txt
                for a little more information about these.

                The default is to build all the filters.

    --enable-match-finders=
                liblzma includes two categories of match finders:
                hash chains and binary trees. Hash chains (hc3 and hc4)
                are quite fast but they don't provide the best compression
                ratio. Binary trees (bt2, bt3 and bt4) give excellent
                compression ratio, but they are slower and need more
                memory than hash chains.

                You need to enable at least one match finder to build the
                LZMA filter encoder. Usually hash chains are used only in
                the fast mode, while binary trees are used to when the best
                compression ratio is wanted.

                The default is to build all the match finders.

    --enable-checks=
                liblzma support multiple integrity checks. CRC32 is
                mandatory, and cannot be omitted. See liblzma-intro.txt
                for more information about usage of the integrity checks.

    --disable-assembler
                liblzma includes some assembler optimizations. Currently
                there is only assembler code for CRC32 and CRC64 for
                32-bit x86.

                All the assembler code in liblzma is position-independent
                code, which is suitable for use in shared libraries and
                position-independent executables. So far only i386
                instructions are used, but the code is optimized for i686
                class CPUs. If you are compiling liblzma exclusively for
                pre-i686 systems, you may want to disable the assembler
                code.

    --enable-small
                Omits precomputed tables. This makes liblzma a few KiB
                smaller. Startup time increases, because the tables need
                to be computed first.

    --enable-debug
                This enables the assert() macro and possibly some other
                run-time consistency checks. It slows down things somewhat,
                so you normally don't want to have this enabled.

    --enable-werror
                Makes all compiler warnings an error, that abort the
                compilation. This may help catching bugs, and should work
                on most systems. This has no effect on the resulting
                binaries.


Static vs. dynamic linking of the command line tools

    By default, the command line tools are linked statically against
    liblzma. There a are a few reasons:

      - The executable(s) can be in /bin while the shared liblzma can still
        be in /usr/lib (if the distro uses such file system hierachy).

      - It's easier to copy the executables to other systems, since they
        depend only on libc.

      - It's slightly faster on some architectures like x86.

    If you don't like this, you can get the command line tools linked
    against the shared liblzma by specifying --disable-static to configure.
    This disables building static liblzma completely.