README revision 207753
11638Srgrimes 21638SrgrimesXZ Utils 31638Srgrimes======== 41638Srgrimes 51638Srgrimes 0. Overview 61638Srgrimes 1. Documentation 71638Srgrimes 1.1. Overall documentation 81638Srgrimes 1.2. Documentation for command line tools 91638Srgrimes 1.3. Documentation for liblzma 101638Srgrimes 2. Version numbering 111638Srgrimes 3. Reporting bugs 12263142Seadler 4. Other implementations of the .xz format 131638Srgrimes 5. Contact information 141638Srgrimes 151638Srgrimes 161638Srgrimes0. Overview 171638Srgrimes----------- 181638Srgrimes 191638Srgrimes XZ Utils provide a general-purpose data compression library and 201638Srgrimes command line tools. The native file format is the .xz format, but 211638Srgrimes also the legacy .lzma format is supported. The .xz format supports 221638Srgrimes multiple compression algorithms, which are called "filters" in 231638Srgrimes context of XZ Utils. The primary filter is currently LZMA2. With 241638Srgrimes typical files, XZ Utils create about 30 % smaller files than gzip. 251638Srgrimes 261638Srgrimes To ease adapting support for the .xz format into existing applications 271638Srgrimes and scripts, the API of liblzma is somewhat similar to the API of the 282942Swollman popular zlib library. For the same reason, the command line tool xz 2950476Speter has similar command line syntax than that of gzip. 301638Srgrimes 31246552Sdes When aiming for the highest compression ratio, LZMA2 encoder uses 321638Srgrimes a lot of CPU time and may use, depending on the settings, even 331638Srgrimes hundreds of megabytes of RAM. However, in fast modes, LZMA2 encoder 341638Srgrimes competes with bzip2 in compression speed, RAM usage, and compression 351638Srgrimes ratio. 361638Srgrimes 371638Srgrimes LZMA2 is reasonably fast to decompress. It is a little slower than 38111185Sceri gzip, but a lot faster than bzip2. Being fast to decompress means 3965532Snectar that the .xz format is especially nice when the same file will be 4068952Ssheldonh decompressed very many times (usually on different computers), which 4168952Ssheldonh is the case e.g. when distributing software packages. In such 4265532Snectar situations, it's not too bad if the compression takes some time, 4379727Sschweikh since that needs to be done only once to benefit many people. 4465532Snectar 4565532Snectar With some file types, combining (or "chaining") LZMA2 with an 461638Srgrimes additional filter can improve compression ratio. A filter chain may 4768952Ssheldonh contain up to four filters, although usually only one two is used. 481638Srgrimes For example, putting a BCJ (Branch/Call/Jump) filter before LZMA2 491638Srgrimes in the filter chain can improve compression ratio of executable files. 501638Srgrimes 511638Srgrimes Since the .xz format allows adding new filter IDs, it is possible that 5257731Ssheldonh some day there will be a filter that is, for example, much faster to 5357731Ssheldonh compress than LZMA2 (but probably with worse compression ratio). 541638Srgrimes Similarly, it is possible that some day there is a filter that will 551638Srgrimes compress better than LZMA2. 561638Srgrimes 571638Srgrimes XZ Utils doesn't support multithreaded compression or decompression 581638Srgrimes yet. It has been planned though and taken into account when designing 591638Srgrimes the .xz file format. 601638Srgrimes 611638Srgrimes 621638Srgrimes1. Documentation 631638Srgrimes---------------- 641638Srgrimes 651638Srgrimes1.1. Overall documentation 661638Srgrimes 6723772Smpp README This file 6857731Ssheldonh 6979727Sschweikh INSTALL.generic Generic install instructions for those not familiar 7023776Smpp with packages using GNU Autotools 7123572Swosch INSTALL Installation instructions specific to XZ Utils 721638Srgrimes PACKAGERS Information to packagers of XZ Utils 731638Srgrimes 741638Srgrimes COPYING XZ Utils copyright and license information 751638Srgrimes COPYING.GPLv2 GNU General Public License version 2 761638Srgrimes COPYING.GPLv3 GNU General Public License version 3 771638Srgrimes COPYING.LGPLv2.1 GNU Lesser General Public License version 2.1 781638Srgrimes 791638Srgrimes AUTHORS The main authors of XZ Utils 801638Srgrimes THANKS Incomplete list of people who have helped making 811638Srgrimes this software 821638Srgrimes NEWS User-visible changes between XZ Utils releases 831638Srgrimes ChangeLog Detailed list of changes (commit log) 841638Srgrimes TODO Known bugs and some sort of to-do list 851638Srgrimes 861638Srgrimes Note that only some of the above files are included in binary 871638Srgrimes packages. 881638Srgrimes 8979727Sschweikh 901638Srgrimes1.2. Documentation for command line tools 911638Srgrimes 921638Srgrimes The command line tools are documented as man pages. In source code 931638Srgrimes releases (and possibly also in some binary packages), the man pages 941638Srgrimes are also provided in plain text (ASCII only) and PDF formats in the 951638Srgrimes directory "doc/man" to make the man pages more accessible to those 961638Srgrimes whose operating system doesn't provide an easy way to view man pages. 971638Srgrimes 9868953Ssheldonh 9968953Ssheldonh1.3. Documentation for liblzma 1001638Srgrimes 1011638Srgrimes The liblzma API headers include short docs about each function 1021638Srgrimes and data type as Doxygen tags. These docs should be quite OK as 1031638Srgrimes a quick reference. 1041638Srgrimes 1051638Srgrimes I have planned to write a bunch of very well documented example 106119893Sru programs, which (due to comments) should work as a tutorial to 1071638Srgrimes various features of liblzma. No such example programs have been 1081638Srgrimes written yet. 1091638Srgrimes 1101638Srgrimes For now, if you have never used liblzma, libbzip2, or zlib, I 1111638Srgrimes recommend learning *basics* of zlib API. Once you know that, it 1121638Srgrimes should be easier to learn liblzma. 1131638Srgrimes 1141638Srgrimes http://zlib.net/manual.html 115246949Sjoel http://zlib.net/zlib_how.html 116246949Sjoel 117246949Sjoel 118246949Sjoel2. Version numbering 119246949Sjoel-------------------- 120246949Sjoel 121246949Sjoel The version number format of XZ Utils is X.Y.ZS: 122246949Sjoel 123246949Sjoel - X is the major version. When this is incremented, the library 124246949Sjoel API and ABI break. 125246949Sjoel 12621443Swosch - Y is the minor version. It is incremented when new features are 12721443Swosch added without breaking existing API or ABI. Even Y indicates 12837247Shoek stable release and odd Y indicates unstable (alpha or beta 12921443Swosch version). 13068954Ssheldonh 13179727Sschweikh - Z is the revision. This has different meaning for stable and 13257731Ssheldonh unstable releases: 13357731Ssheldonh * Stable: Z is incremented when bugs get fixed without adding 13421443Swosch any new features. 13557731Ssheldonh * Unstable: Z is just a counter. API or ABI of features added 13657731Ssheldonh in earlier unstable releases having the same X.Y may break. 13737247Shoek 13821443Swosch - S indicates stability of the release. It is missing from the 13937247Shoek stable releases where Y is an even number. When Y is odd, S 14068716Sru is either "alpha" or "beta" to make it very clear that such 14168716Sru versions are not stable releases. The same X.Y.Z combination is 14268716Sru not used for more than one stability level i.e. after X.Y.Zalpha, 14382596Slogo the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta. 1441638Srgrimes 1451638Srgrimes 1461638Srgrimes3. Reporting bugs 1471638Srgrimes----------------- 1481638Srgrimes 149246552Sdes Naturally it is easiest for me if you already know what causes the 15020914Swosch unexpected behavior. Even better if you have a patch to propose. 15120914Swosch However, quite often the reason for unexpected behavior is unknown, 1522942Swollman so here are a few things to do before sending a bug report: 1532942Swollman 1541638Srgrimes 1. Try to create a small example how to reproduce the issue. 15565532Snectar 15689362Sru 2. Compile XZ Utils with debugging code using configure switches 157155816Sbrueffer --enable-debug and, if possible, --disable-shared. If you are 158117186Sjkoshy using GCC, use CFLAGS='-O0 -ggdb3'. Don't strip the resulting 15989362Sru binaries. 1601638Srgrimes 1611638Srgrimes 3. Turn on core dumps. The exact command depends on your shell; 1621638Srgrimes for example in GNU bash it is done with "ulimit -c unlimited", 1631638Srgrimes and in tcsh with "limit coredumpsize unlimited". 1641638Srgrimes 16523772Smpp 4. Try to reproduce the suspected bug. If you get "assertion failed" 16623572Swosch message, be sure to include the complete message in your bug 167 report. If the application leaves a coredump, get a backtrace 168 using gdb: 169 $ gdb /path/to/app-binary # Load the app to the debugger. 170 (gdb) core core # Open the coredump. 171 (gdb) bt # Print the backtrace. Copy & paste to bug report. 172 (gdb) quit # Quit gdb. 173 174 Report your bug via email or IRC (see Contact information below). 175 Don't send core dump files or any executables. If you have a small 176 example file(s) (total size less than 256 KiB), please include 177 it/them as an attachment. If you have bigger test files, put them 178 online somewhere and include an URL to the file(s) in the bug report. 179 180 Always include the exact version number of XZ Utils in the bug report. 181 If you are using a snapshot from the git repository, use "git describe" 182 to get the exact snapshot version. If you are using XZ Utils shipped 183 in an operating system distribution, mention the distribution name, 184 distribution version, and exact xz package version; if you cannot 185 repeat the bug with the code compiled from unpatched source code, 186 you probably need to report a bug to your distribution's bug tracking 187 system. 188 189 1904. Other implementations of the .xz format 191------------------------------------------ 192 193 7-Zip and the p7zip port of 7-Zip support the .xz format starting 194 from the version 9.00alpha. 195 196 http://7-zip.org/ 197 http://p7zip.sourceforge.net/ 198 199 XZ Embedded is a limited implementation written for use in the Linux 200 kernel, but it is also suitable for other embedded use. 201 202 http://tukaani.org/xz/embedded.html 203 204 2055. Contact information 206---------------------- 207 208 If you have questions, bug reports, patches etc. related to XZ Utils, 209 contact Lasse Collin <lasse.collin@tukaani.org> (in Finnish or English). 210 tukaani.org uses greylisting to reduce spam, thus when you send your 211 first email, it may get delayed by a few hours. In addition to that, 212 I'm sometimes slow at replying. If you haven't got a reply within two 213 weeks, assume that your email has got lost and resend it or use IRC. 214 215 You can find me also from #tukaani on Freenode; my nick is Larhzu. 216 The channel tends to be pretty quiet, so just ask your question and 217 someone may wake up. 218 219