12940b44dSPeter Avalos 22940b44dSPeter AvalosXZ Utils 32940b44dSPeter Avalos======== 42940b44dSPeter Avalos 52940b44dSPeter Avalos 0. Overview 62940b44dSPeter Avalos 1. Documentation 72940b44dSPeter Avalos 1.1. Overall documentation 8b892b6baSPeter Avalos 1.2. Documentation for command-line tools 92940b44dSPeter Avalos 1.3. Documentation for liblzma 102940b44dSPeter Avalos 2. Version numbering 112940b44dSPeter Avalos 3. Reporting bugs 12*e151908bSDaniel Fojt 4. Translations 132940b44dSPeter Avalos 5. Other implementations of the .xz format 142940b44dSPeter Avalos 6. Contact information 152940b44dSPeter Avalos 162940b44dSPeter Avalos 172940b44dSPeter Avalos0. Overview 182940b44dSPeter Avalos----------- 192940b44dSPeter Avalos 20b892b6baSPeter Avalos XZ Utils provide a general-purpose data-compression library plus 21b892b6baSPeter Avalos command-line tools. The native file format is the .xz format, but 222940b44dSPeter Avalos also the legacy .lzma format is supported. The .xz format supports 23b892b6baSPeter Avalos multiple compression algorithms, which are called "filters" in the 242940b44dSPeter Avalos context of XZ Utils. The primary filter is currently LZMA2. With 252940b44dSPeter Avalos typical files, XZ Utils create about 30 % smaller files than gzip. 262940b44dSPeter Avalos 272940b44dSPeter Avalos To ease adapting support for the .xz format into existing applications 282940b44dSPeter Avalos and scripts, the API of liblzma is somewhat similar to the API of the 29b892b6baSPeter Avalos popular zlib library. For the same reason, the command-line tool xz 30b892b6baSPeter Avalos has a command-line syntax similar to that of gzip. 312940b44dSPeter Avalos 32b892b6baSPeter Avalos When aiming for the highest compression ratio, the LZMA2 encoder uses 332940b44dSPeter Avalos a lot of CPU time and may use, depending on the settings, even 34b892b6baSPeter Avalos hundreds of megabytes of RAM. However, in fast modes, the LZMA2 encoder 352940b44dSPeter Avalos competes with bzip2 in compression speed, RAM usage, and compression 362940b44dSPeter Avalos ratio. 372940b44dSPeter Avalos 382940b44dSPeter Avalos LZMA2 is reasonably fast to decompress. It is a little slower than 392940b44dSPeter Avalos gzip, but a lot faster than bzip2. Being fast to decompress means 402940b44dSPeter Avalos that the .xz format is especially nice when the same file will be 412940b44dSPeter Avalos decompressed very many times (usually on different computers), which 422940b44dSPeter Avalos is the case e.g. when distributing software packages. In such 432940b44dSPeter Avalos situations, it's not too bad if the compression takes some time, 442940b44dSPeter Avalos since that needs to be done only once to benefit many people. 452940b44dSPeter Avalos 462940b44dSPeter Avalos With some file types, combining (or "chaining") LZMA2 with an 47b892b6baSPeter Avalos additional filter can improve the compression ratio. A filter chain may 48b892b6baSPeter Avalos contain up to four filters, although usually only one or two are used. 492940b44dSPeter Avalos For example, putting a BCJ (Branch/Call/Jump) filter before LZMA2 502940b44dSPeter Avalos in the filter chain can improve compression ratio of executable files. 512940b44dSPeter Avalos 522940b44dSPeter Avalos Since the .xz format allows adding new filter IDs, it is possible that 532940b44dSPeter Avalos some day there will be a filter that is, for example, much faster to 542940b44dSPeter Avalos compress than LZMA2 (but probably with worse compression ratio). 552940b44dSPeter Avalos Similarly, it is possible that some day there is a filter that will 562940b44dSPeter Avalos compress better than LZMA2. 572940b44dSPeter Avalos 58*e151908bSDaniel Fojt XZ Utils supports multithreaded compression. XZ Utils doesn't support 59*e151908bSDaniel Fojt multithreaded decompression yet. It has been planned though and taken 60*e151908bSDaniel Fojt into account when designing the .xz file format. In the future, files 61*e151908bSDaniel Fojt that were created in threaded mode can be decompressed in threaded 62*e151908bSDaniel Fojt mode too. 632940b44dSPeter Avalos 642940b44dSPeter Avalos 652940b44dSPeter Avalos1. Documentation 662940b44dSPeter Avalos---------------- 672940b44dSPeter Avalos 682940b44dSPeter Avalos1.1. Overall documentation 692940b44dSPeter Avalos 702940b44dSPeter Avalos README This file 712940b44dSPeter Avalos 722940b44dSPeter Avalos INSTALL.generic Generic install instructions for those not familiar 732940b44dSPeter Avalos with packages using GNU Autotools 742940b44dSPeter Avalos INSTALL Installation instructions specific to XZ Utils 752940b44dSPeter Avalos PACKAGERS Information to packagers of XZ Utils 762940b44dSPeter Avalos 772940b44dSPeter Avalos COPYING XZ Utils copyright and license information 782940b44dSPeter Avalos COPYING.GPLv2 GNU General Public License version 2 792940b44dSPeter Avalos COPYING.GPLv3 GNU General Public License version 3 802940b44dSPeter Avalos COPYING.LGPLv2.1 GNU Lesser General Public License version 2.1 812940b44dSPeter Avalos 822940b44dSPeter Avalos AUTHORS The main authors of XZ Utils 832940b44dSPeter Avalos THANKS Incomplete list of people who have helped making 842940b44dSPeter Avalos this software 852940b44dSPeter Avalos NEWS User-visible changes between XZ Utils releases 862940b44dSPeter Avalos ChangeLog Detailed list of changes (commit log) 872940b44dSPeter Avalos TODO Known bugs and some sort of to-do list 882940b44dSPeter Avalos 892940b44dSPeter Avalos Note that only some of the above files are included in binary 902940b44dSPeter Avalos packages. 912940b44dSPeter Avalos 922940b44dSPeter Avalos 93b892b6baSPeter Avalos1.2. Documentation for command-line tools 942940b44dSPeter Avalos 95b892b6baSPeter Avalos The command-line tools are documented as man pages. In source code 962940b44dSPeter Avalos releases (and possibly also in some binary packages), the man pages 972940b44dSPeter Avalos are also provided in plain text (ASCII only) and PDF formats in the 982940b44dSPeter Avalos directory "doc/man" to make the man pages more accessible to those 992940b44dSPeter Avalos whose operating system doesn't provide an easy way to view man pages. 1002940b44dSPeter Avalos 1012940b44dSPeter Avalos 1022940b44dSPeter Avalos1.3. Documentation for liblzma 1032940b44dSPeter Avalos 1042940b44dSPeter Avalos The liblzma API headers include short docs about each function 1052940b44dSPeter Avalos and data type as Doxygen tags. These docs should be quite OK as 1062940b44dSPeter Avalos a quick reference. 1072940b44dSPeter Avalos 108*e151908bSDaniel Fojt There are a few example/tutorial programs that should help in 109*e151908bSDaniel Fojt getting started with liblzma. In the source package the examples 110*e151908bSDaniel Fojt are in "doc/examples" and in binary packages they may be under 111*e151908bSDaniel Fojt "examples" in the same directory as this README. 1122940b44dSPeter Avalos 113*e151908bSDaniel Fojt Since the liblzma API has similarities to the zlib API, some people 114*e151908bSDaniel Fojt may find it useful to read the zlib docs and tutorial too: 1152940b44dSPeter Avalos 1162940b44dSPeter Avalos http://zlib.net/manual.html 1172940b44dSPeter Avalos http://zlib.net/zlib_how.html 1182940b44dSPeter Avalos 1192940b44dSPeter Avalos 1202940b44dSPeter Avalos2. Version numbering 1212940b44dSPeter Avalos-------------------- 1222940b44dSPeter Avalos 1232940b44dSPeter Avalos The version number format of XZ Utils is X.Y.ZS: 1242940b44dSPeter Avalos 1252940b44dSPeter Avalos - X is the major version. When this is incremented, the library 1262940b44dSPeter Avalos API and ABI break. 1272940b44dSPeter Avalos 128b892b6baSPeter Avalos - Y is the minor version. It is incremented when new features 129b892b6baSPeter Avalos are added without breaking the existing API or ABI. An even Y 130b892b6baSPeter Avalos indicates a stable release and an odd Y indicates unstable 131b892b6baSPeter Avalos (alpha or beta version). 1322940b44dSPeter Avalos 133b892b6baSPeter Avalos - Z is the revision. This has a different meaning for stable and 1342940b44dSPeter Avalos unstable releases: 135b892b6baSPeter Avalos 1362940b44dSPeter Avalos * Stable: Z is incremented when bugs get fixed without adding 137b892b6baSPeter Avalos any new features. This is intended to be convenient for 138b892b6baSPeter Avalos downstream distributors that want bug fixes but don't want 139b892b6baSPeter Avalos any new features to minimize the risk of introducing new bugs. 140b892b6baSPeter Avalos 1412940b44dSPeter Avalos * Unstable: Z is just a counter. API or ABI of features added 1422940b44dSPeter Avalos in earlier unstable releases having the same X.Y may break. 1432940b44dSPeter Avalos 1442940b44dSPeter Avalos - S indicates stability of the release. It is missing from the 145b892b6baSPeter Avalos stable releases, where Y is an even number. When Y is odd, S 1462940b44dSPeter Avalos is either "alpha" or "beta" to make it very clear that such 1472940b44dSPeter Avalos versions are not stable releases. The same X.Y.Z combination is 148b892b6baSPeter Avalos not used for more than one stability level, i.e. after X.Y.Zalpha, 1492940b44dSPeter Avalos the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta. 1502940b44dSPeter Avalos 1512940b44dSPeter Avalos 1522940b44dSPeter Avalos3. Reporting bugs 1532940b44dSPeter Avalos----------------- 1542940b44dSPeter Avalos 1552940b44dSPeter Avalos Naturally it is easiest for me if you already know what causes the 1562940b44dSPeter Avalos unexpected behavior. Even better if you have a patch to propose. 1572940b44dSPeter Avalos However, quite often the reason for unexpected behavior is unknown, 1582940b44dSPeter Avalos so here are a few things to do before sending a bug report: 1592940b44dSPeter Avalos 1602940b44dSPeter Avalos 1. Try to create a small example how to reproduce the issue. 1612940b44dSPeter Avalos 1622940b44dSPeter Avalos 2. Compile XZ Utils with debugging code using configure switches 1632940b44dSPeter Avalos --enable-debug and, if possible, --disable-shared. If you are 1642940b44dSPeter Avalos using GCC, use CFLAGS='-O0 -ggdb3'. Don't strip the resulting 1652940b44dSPeter Avalos binaries. 1662940b44dSPeter Avalos 1672940b44dSPeter Avalos 3. Turn on core dumps. The exact command depends on your shell; 1682940b44dSPeter Avalos for example in GNU bash it is done with "ulimit -c unlimited", 1692940b44dSPeter Avalos and in tcsh with "limit coredumpsize unlimited". 1702940b44dSPeter Avalos 1712940b44dSPeter Avalos 4. Try to reproduce the suspected bug. If you get "assertion failed" 1722940b44dSPeter Avalos message, be sure to include the complete message in your bug 1732940b44dSPeter Avalos report. If the application leaves a coredump, get a backtrace 1742940b44dSPeter Avalos using gdb: 1752940b44dSPeter Avalos $ gdb /path/to/app-binary # Load the app to the debugger. 1762940b44dSPeter Avalos (gdb) core core # Open the coredump. 1772940b44dSPeter Avalos (gdb) bt # Print the backtrace. Copy & paste to bug report. 1782940b44dSPeter Avalos (gdb) quit # Quit gdb. 1792940b44dSPeter Avalos 1802940b44dSPeter Avalos Report your bug via email or IRC (see Contact information below). 1812940b44dSPeter Avalos Don't send core dump files or any executables. If you have a small 1822940b44dSPeter Avalos example file(s) (total size less than 256 KiB), please include 1832940b44dSPeter Avalos it/them as an attachment. If you have bigger test files, put them 184b892b6baSPeter Avalos online somewhere and include a URL to the file(s) in the bug report. 1852940b44dSPeter Avalos 1862940b44dSPeter Avalos Always include the exact version number of XZ Utils in the bug report. 1872940b44dSPeter Avalos If you are using a snapshot from the git repository, use "git describe" 1882940b44dSPeter Avalos to get the exact snapshot version. If you are using XZ Utils shipped 1892940b44dSPeter Avalos in an operating system distribution, mention the distribution name, 1902940b44dSPeter Avalos distribution version, and exact xz package version; if you cannot 1912940b44dSPeter Avalos repeat the bug with the code compiled from unpatched source code, 1922940b44dSPeter Avalos you probably need to report a bug to your distribution's bug tracking 1932940b44dSPeter Avalos system. 1942940b44dSPeter Avalos 1952940b44dSPeter Avalos 196*e151908bSDaniel Fojt4. Translations 197*e151908bSDaniel Fojt--------------- 1982940b44dSPeter Avalos 199*e151908bSDaniel Fojt The xz command line tool and all man pages can be translated. 200*e151908bSDaniel Fojt The translations are handled via the Translation Project. If you 201*e151908bSDaniel Fojt wish to help translating xz, please join the Translation Project: 2022940b44dSPeter Avalos 203*e151908bSDaniel Fojt https://translationproject.org/html/translators.html 2042940b44dSPeter Avalos 205*e151908bSDaniel Fojt Several strings will change in a future version of xz so if you 206*e151908bSDaniel Fojt wish to start a new translation, look at the code in the xz git 207*e151908bSDaniel Fojt repostiory instead of a 5.2.x release. 2082940b44dSPeter Avalos 2092940b44dSPeter Avalos 2102940b44dSPeter Avalos5. Other implementations of the .xz format 2112940b44dSPeter Avalos------------------------------------------ 2122940b44dSPeter Avalos 2132940b44dSPeter Avalos 7-Zip and the p7zip port of 7-Zip support the .xz format starting 2142940b44dSPeter Avalos from the version 9.00alpha. 2152940b44dSPeter Avalos 2162940b44dSPeter Avalos http://7-zip.org/ 2172940b44dSPeter Avalos http://p7zip.sourceforge.net/ 2182940b44dSPeter Avalos 2192940b44dSPeter Avalos XZ Embedded is a limited implementation written for use in the Linux 2202940b44dSPeter Avalos kernel, but it is also suitable for other embedded use. 2212940b44dSPeter Avalos 22246a2189dSzrj https://tukaani.org/xz/embedded.html 2232940b44dSPeter Avalos 2242940b44dSPeter Avalos 2252940b44dSPeter Avalos6. Contact information 2262940b44dSPeter Avalos---------------------- 2272940b44dSPeter Avalos 2282940b44dSPeter Avalos If you have questions, bug reports, patches etc. related to XZ Utils, 2292940b44dSPeter Avalos contact Lasse Collin <lasse.collin@tukaani.org> (in Finnish or English). 2302940b44dSPeter Avalos I'm sometimes slow at replying. If you haven't got a reply within two 2312940b44dSPeter Avalos weeks, assume that your email has got lost and resend it or use IRC. 2322940b44dSPeter Avalos 2332940b44dSPeter Avalos You can find me also from #tukaani on Freenode; my nick is Larhzu. 2342940b44dSPeter Avalos The channel tends to be pretty quiet, so just ask your question and 2352940b44dSPeter Avalos someone may wake up. 2362940b44dSPeter Avalos 237