README

Overview

Easylzma is a C library and command line tools for LZMA compression and 
decompression.  It uses a Igor Pavlov's reference implementation and SDK
written in C.

License

All the cruft you find here is public domain.  You don't have to credit
anyone to use this code, but my personal request is that you mention
Igor Pavlov for his hard, high quality work.

Project Goals

1. A tiny C wrapper and portable build system around a subset of
   Igor Pavlov's public domain LZMA compression and decompression
   implementation.
2. A tiny and straighforward API
3. Support for multiple different prominent LZMA file formats (see section on
   file formats below)
4. easy to build and use everywhere (doze and nix alike)
5. public domain licensing through and through.  (hats off to Igor)

Current State:

THIS IS A WORK IN PROGRESS.  The code here should be considered pre-alpha,
and this should only be used by tinkerers or hackers at this point.  Once
feature completion is attained this message will be updated.  See the
TODO file distributed with the source for remaining work to be done.

Platforms Supported

0.0.2 has been successfully compiled and run basic round trip testing
on the following platforms & compilers:

  * win32 - visual studio 2005
  * osx - 10.4 & 10.5 (intel)
  * netbsd ppc - 4.0.1 with gcc 4.1.2
    (NOTE: memory allocation errors when dict size is default)
  * freebsd 6.1 - amd64 gcc 3.4.4

Features

XXX: write me (and the code)

Usage

XXX: write me (and the code)

The Saga of LZMA File Formats, and a couple cents.

As far as I can tell, there are at least four different ways to put LZMA
compressed data in a stream:

1. The LZMA-Alone format, which consists of a 13 byte header including
   compression properties, dictionary size, and the uncompressed size of
   the file, followed by compressed data.  This format has some support
   in Igor Pavlov's reference implementation and is in widespread use, as
   it's supported by lzmautils: http://tukaani.org/lzma/

   The canonical (afaict) implementation of this format (lzmautis) is
   BSD licensed.

2. The lzip format (http://www.nongnu.org/lzip/lzip.html) - which
   includes a CRC footer and leading "magic number".  The former
   affords data integrity gaurantees, while the latter simplifies
   heuristic determination of file format.  This format looks to have
   reasonably widespread usage, though not quite as significant as
   LZMA-Alone.

   The only implementation of this format I can find (lzip) is GPL licensed.

3. the xz format ( http://tukaani.org/xz/xz-file-format.txt ) which is
   a more complex representation that includes CRC support and a magic
   number.  This format is to be supported by the next iteration of
   XZ Utils which is currently in beta.  The source may be obtained
   here: git://ctrl.tukaani.org/xz.git

   This format will address some criticisms to the LZMA-Alone format and
   was developed collaboratively by Lasse Collin (the current maintainer
   of XZ utils) and Igor Pavlov (the author of 7zip and the refrence
   implementation of LZMA).

   The xz format will employ LZMA2 which consists of extensions on top
   of LZMA, in the xz utils maintainer's words:

   "The primary compression algorithm in .xz is currently LZMA2, which
    is an extension on top of the orignal LZMA to fix a few practical
    issues, like adding support for flushing the encoder (equivalent
    to zlib's Z_SYNC_FLUSH), which isn't possible with the original
    LZMA."

   Again, maintainers words, regarding licensing:

   "XZ Utils currently contains a zlib-like compression library and a 
    gzip-like command line tool. It's currently under LGPLv2.1+ but I will 
    put it into the public domain before the first stable release."

4. The 7zip disk format which can contain multiple files possibly stored in
   LZMA compressed format.

Given the state of things, the goal of this project is to develop something
based on the existing formats, and quickly leverage code generated by the XZ
Utils project, or simply kill this thing if that project produces something
that's easy to embed and has a clean API at a similar level of abstraction
as easylzma.

lloyd - sometime in oh nine.