
LZMA Utils
----------

    Copyright (C) 2007 Lasse Collin

    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.


Warning

    This is an early alpha version. Don't trust the files produced by
    this version of the software - not even if the software can
    uncompress the files properly! This is because the file format
    isn't completely frozen yet.

    So please test a lot, but don't use for anything serious yet.


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.

    LZMA 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.

    LZMA Utils consist of a few relatively separate parts:
      * liblzma is an encoder/decoder library with support for several
        filters (algorithms). The primary filter is LZMA.
      * libzfile 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. ]
      * lzma 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

    LZMA 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 LZMA Utils, you need at least version
    3.x.x. GCC version 2.xx.x doesn't support some C99 features used
    in LZMA Utils source code, thus GCC 2 won't compile LZMA Utils.

    If you have written patches to make LZMA 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++.


Reporting bugs

    Naturally it is easiest for me if you already know what causes the
    unexpected behavior. Even better if you have a patch to propose.
    However, quite often the reason for unexpected behavior is unknown,
    so below are a few things what to do before sending a bug report.

    In case of a crash (usually segmentation violation):
      1. Try to create a small example how to reprocude the issue.
      2. If you are writing an application using liblzma or libzfile,
         double check that you are using the libraries correctly (for
         example, that you didn't forget to call lzma_init()). If it is
         the command line tool included in LZMA Utils that is crashing,
         ignore this step.
      3. Compile LZMA Utils with debugging code using configure switch
         `--enable-debug'. If you are using GCC as the compiler, use
         CFLAGS='-O0 -ggdb'. Don't strip the resulting binaries.
      4. Turn on core dumps. The exact command depends on your shell;
         for example in GNU bash it is done with `ulimit -c unlimited',
         and in tcsh with `limit coredumpsize unlimited'.
      5. Try to reproduce the suspected bug. If you get `assertion failed'
         message, be sure to include the complete message in your bug
         report. If the application leaves a coredump, get a backtrace
         using gdb:
           $ gdb /path/to/app-binary   # Loads the app to the debugger.
           (gdb) core core   # Opens the coredump.
           (gdb) bt   # Prints the backtrace. Copy & paste to bug report.
           (gdb) quit   # Quits gdb.

    Send your bug report to Lasse Collin <lasse.collin@tukaani.org>.
    Keep the total size of attachments smaller than 100 KiB.

    Do NOT complain about problems with LZMA Utils to Igor Pavlov.
    Although the code of LZMA Utils is derived from his code, there are
    a lot of changes, which may have introduced bugs not present in
    the original version.

