mirror of
https://git.tukaani.org/xz.git
synced 2025-11-03 23:12:57 +00:00
99f9e879a6
Installation and packaging instructions were added. README and other generic docs were revised. Some of the documentation files are now installed to $docdir.
173 lines
6.8 KiB
Plaintext
173 lines
6.8 KiB
Plaintext
|
|
XZ Utils
|
|
========
|
|
|
|
0. Overview
|
|
1. Documentation
|
|
1.1. Overall documentation
|
|
1.2. Documentation for command line tools
|
|
1.3. Documentation for liblzma
|
|
2. Version numbering
|
|
3. Other implementations of the .xz format
|
|
4. Contact information
|
|
|
|
|
|
0. Overview
|
|
-----------
|
|
|
|
XZ Utils provide a general purporse data compression library and
|
|
command line tools. The native file format is the .xz format, but
|
|
also the legacy .lzma format is supported. The .xz format supports
|
|
multiple compression algorithms, which are called "filters" in
|
|
context of XZ Utils. The primary filter is currently LZMA2. With
|
|
typical files, XZ Utils create about 30 % smaller files than gzip.
|
|
|
|
To ease adapting support for the .xz format into existing applications
|
|
and scripts, the API of liblzma is somewhat similar to the API of the
|
|
popular zlib library. For the same reason, the command line tool xz
|
|
has similar command line syntax than that of gzip.
|
|
|
|
When aiming for the highest compression ratio, LZMA2 encoder uses
|
|
a lot of CPU time and may use, depending on the settings, even
|
|
hundreds of megabytes of RAM. However, in fast modes, LZMA2 encoder
|
|
competes with bzip2 in compression speed, RAM usage, and compression
|
|
ratio.
|
|
|
|
LZMA2 is reasonably fast to decompress. It is a little slower than
|
|
gzip, but a lot faster than bzip2. Being fast to decompress means
|
|
that the .xz format is especially nice when the same file will be
|
|
decompressed very many times (usually on different computers), which
|
|
is the case e.g. when distributing software packages. In such
|
|
situations, it's not too bad if the compression takes some time,
|
|
since that needs to be done only once to benefit many people.
|
|
|
|
With some file types, combining (or "chaining") LZMA2 with an
|
|
additional filter can improve compression ratio. A filter chain may
|
|
contain up to four filters, although usually only one two is used.
|
|
For example, putting a BCJ (Branch/Call/Jump) filter before LZMA2
|
|
in the filter chain can improve compression ratio of executable files.
|
|
|
|
Since the .xz format allows adding new filter IDs, it is possible that
|
|
some day there will be a filter that is, for example, much faster to
|
|
compress than LZMA2 (but probably with worse compression ratio).
|
|
Similarly, it is possible that some day there is a filter that will
|
|
compress better than LZMA2.
|
|
|
|
XZ Utils doesn't support multithreaded compression or decompression
|
|
yet. It has been planned though and taken into account when designing
|
|
the .xz file format.
|
|
|
|
|
|
1. Documentation
|
|
----------------
|
|
|
|
1.1. Overall documentation
|
|
|
|
README This file
|
|
|
|
INSTALL.generic Generic install instructions for those not familiar
|
|
with packages using GNU Autotools
|
|
INSTALL Installation instructions specific to XZ Utils
|
|
PACKAGERS Information to packagers of XZ Utils
|
|
|
|
COPYING XZ Utils copyright and license information
|
|
COPYING.GPLv2 GNU General Public License version 2
|
|
COPYING.GPLv3 GNU General Public License version 3
|
|
COPYING.LGPLv2.1 GNU Lesser General Public License version 2.1
|
|
|
|
AUTHORS The main authors of XZ Utils
|
|
THANKS Incomplete list of people who have helped making
|
|
this software
|
|
NEWS User-visible changes between XZ Utils releases
|
|
ChangeLog Detailed list of changes (commit log)
|
|
|
|
Note that only some of the above files are included in binary
|
|
packages.
|
|
|
|
|
|
1.2. Documentation for command line tools
|
|
|
|
The command line tools are documented as man pages. In source code
|
|
releases (and possibly also in some binary packages), the man pages
|
|
are also provided in plain text (ASCII only) and PDF formats in the
|
|
directory "doc/man" to make the man pages more accessible to those
|
|
whose operating system doesn't provide an easy way to view man pages.
|
|
|
|
|
|
1.3. Documentation for liblzma
|
|
|
|
The liblzma API headers include short docs about each function
|
|
and data type as Doxygen tags. These docs should be quite OK as
|
|
a quick reference.
|
|
|
|
I have planned to write a bunch of very well documented example
|
|
programs, which (due to comments) should work as a tutorial to
|
|
various features of liblzma. No such example programs have been
|
|
written yet.
|
|
|
|
For now, if you have never used liblzma, libbzip2, or zlib, I
|
|
recommend learning *basics* of zlib API. Once you know that, it
|
|
should be easier to learn liblzma.
|
|
|
|
http://zlib.net/manual.html
|
|
http://zlib.net/zlib_how.html
|
|
|
|
|
|
2. Version numbering
|
|
--------------------
|
|
|
|
The 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.
|
|
|
|
|
|
3. Other implementations of the .xz format
|
|
------------------------------------------
|
|
|
|
7-Zip and the p7zip port of 7-Zip support the .xz format starting
|
|
from the version 9.00alpha.
|
|
|
|
http://7-zip.org/
|
|
http://p7zip.sourceforge.net/
|
|
|
|
XZ Embedded is a limited implementation written for use in the Linux
|
|
kernel, but it is also suitable for other embedded use.
|
|
|
|
http://tukaani.org/xz-embedded/
|
|
|
|
|
|
4. Contact information
|
|
----------------------
|
|
|
|
If you have questions, bug reports, patches etc. related to XZ Utils,
|
|
contact Lasse Collin <lasse.collin@tukaani.org>. tukaani.org uses
|
|
greylisting to reduce spam, thus when you send your first email, it
|
|
may get delayed by a few hours. In addition to that, I'm sometimes
|
|
slow at replying. If you haven't got a reply within two weeks, assume
|
|
that your email has got lost and resend it or use IRC.
|
|
|
|
You can find me also from #tukaani on Freenode; my nick is Larhzu.
|
|
The channel tends to be pretty quiet, so just ask your question and
|
|
someone may wake up.
|
|
|