1207753Smm 2207753SmmXZ Utils 3207753Smm======== 4207753Smm 5207753Smm 0. Overview 6207753Smm 1. Documentation 7207753Smm 1.1. Overall documentation 8244601Smm 1.2. Documentation for command-line tools 9207753Smm 1.3. Documentation for liblzma 10207753Smm 2. Version numbering 11207753Smm 3. Reporting bugs 12360523Sdelphij 4. Translations 13213700Smm 5. Other implementations of the .xz format 14213700Smm 6. Contact information 15207753Smm 16207753Smm 17207753Smm0. Overview 18207753Smm----------- 19207753Smm 20244601Smm XZ Utils provide a general-purpose data-compression library plus 21244601Smm command-line tools. The native file format is the .xz format, but 22207753Smm also the legacy .lzma format is supported. The .xz format supports 23244601Smm multiple compression algorithms, which are called "filters" in the 24207753Smm context of XZ Utils. The primary filter is currently LZMA2. With 25207753Smm typical files, XZ Utils create about 30 % smaller files than gzip. 26207753Smm 27207753Smm To ease adapting support for the .xz format into existing applications 28207753Smm and scripts, the API of liblzma is somewhat similar to the API of the 29244601Smm popular zlib library. For the same reason, the command-line tool xz 30244601Smm has a command-line syntax similar to that of gzip. 31207753Smm 32244601Smm When aiming for the highest compression ratio, the LZMA2 encoder uses 33207753Smm a lot of CPU time and may use, depending on the settings, even 34244601Smm hundreds of megabytes of RAM. However, in fast modes, the LZMA2 encoder 35207753Smm competes with bzip2 in compression speed, RAM usage, and compression 36207753Smm ratio. 37207753Smm 38207753Smm LZMA2 is reasonably fast to decompress. It is a little slower than 39207753Smm gzip, but a lot faster than bzip2. Being fast to decompress means 40207753Smm that the .xz format is especially nice when the same file will be 41207753Smm decompressed very many times (usually on different computers), which 42207753Smm is the case e.g. when distributing software packages. In such 43207753Smm situations, it's not too bad if the compression takes some time, 44207753Smm since that needs to be done only once to benefit many people. 45207753Smm 46207753Smm With some file types, combining (or "chaining") LZMA2 with an 47244601Smm additional filter can improve the compression ratio. A filter chain may 48244601Smm contain up to four filters, although usually only one or two are used. 49207753Smm For example, putting a BCJ (Branch/Call/Jump) filter before LZMA2 50207753Smm in the filter chain can improve compression ratio of executable files. 51207753Smm 52207753Smm Since the .xz format allows adding new filter IDs, it is possible that 53207753Smm some day there will be a filter that is, for example, much faster to 54207753Smm compress than LZMA2 (but probably with worse compression ratio). 55207753Smm Similarly, it is possible that some day there is a filter that will 56207753Smm compress better than LZMA2. 57207753Smm 58360523Sdelphij XZ Utils supports multithreaded compression. XZ Utils doesn't support 59360523Sdelphij multithreaded decompression yet. It has been planned though and taken 60360523Sdelphij into account when designing the .xz file format. In the future, files 61360523Sdelphij that were created in threaded mode can be decompressed in threaded 62360523Sdelphij mode too. 63207753Smm 64207753Smm 65207753Smm1. Documentation 66207753Smm---------------- 67207753Smm 68207753Smm1.1. Overall documentation 69207753Smm 70207753Smm README This file 71207753Smm 72207753Smm INSTALL.generic Generic install instructions for those not familiar 73207753Smm with packages using GNU Autotools 74207753Smm INSTALL Installation instructions specific to XZ Utils 75207753Smm PACKAGERS Information to packagers of XZ Utils 76207753Smm 77207753Smm COPYING XZ Utils copyright and license information 78207753Smm COPYING.GPLv2 GNU General Public License version 2 79207753Smm COPYING.GPLv3 GNU General Public License version 3 80207753Smm COPYING.LGPLv2.1 GNU Lesser General Public License version 2.1 81207753Smm 82207753Smm AUTHORS The main authors of XZ Utils 83207753Smm THANKS Incomplete list of people who have helped making 84207753Smm this software 85207753Smm NEWS User-visible changes between XZ Utils releases 86207753Smm ChangeLog Detailed list of changes (commit log) 87207753Smm TODO Known bugs and some sort of to-do list 88207753Smm 89207753Smm Note that only some of the above files are included in binary 90207753Smm packages. 91207753Smm 92207753Smm 93244601Smm1.2. Documentation for command-line tools 94207753Smm 95244601Smm The command-line tools are documented as man pages. In source code 96207753Smm releases (and possibly also in some binary packages), the man pages 97207753Smm are also provided in plain text (ASCII only) and PDF formats in the 98207753Smm directory "doc/man" to make the man pages more accessible to those 99207753Smm whose operating system doesn't provide an easy way to view man pages. 100207753Smm 101207753Smm 102207753Smm1.3. Documentation for liblzma 103207753Smm 104207753Smm The liblzma API headers include short docs about each function 105207753Smm and data type as Doxygen tags. These docs should be quite OK as 106207753Smm a quick reference. 107207753Smm 108360523Sdelphij There are a few example/tutorial programs that should help in 109360523Sdelphij getting started with liblzma. In the source package the examples 110360523Sdelphij are in "doc/examples" and in binary packages they may be under 111360523Sdelphij "examples" in the same directory as this README. 112207753Smm 113360523Sdelphij Since the liblzma API has similarities to the zlib API, some people 114360523Sdelphij may find it useful to read the zlib docs and tutorial too: 115207753Smm 116207753Smm http://zlib.net/manual.html 117207753Smm http://zlib.net/zlib_how.html 118207753Smm 119207753Smm 120207753Smm2. Version numbering 121207753Smm-------------------- 122207753Smm 123207753Smm The version number format of XZ Utils is X.Y.ZS: 124207753Smm 125207753Smm - X is the major version. When this is incremented, the library 126207753Smm API and ABI break. 127207753Smm 128244601Smm - Y is the minor version. It is incremented when new features 129244601Smm are added without breaking the existing API or ABI. An even Y 130244601Smm indicates a stable release and an odd Y indicates unstable 131244601Smm (alpha or beta version). 132207753Smm 133244601Smm - Z is the revision. This has a different meaning for stable and 134207753Smm unstable releases: 135244601Smm 136207753Smm * Stable: Z is incremented when bugs get fixed without adding 137244601Smm any new features. This is intended to be convenient for 138244601Smm downstream distributors that want bug fixes but don't want 139244601Smm any new features to minimize the risk of introducing new bugs. 140244601Smm 141207753Smm * Unstable: Z is just a counter. API or ABI of features added 142207753Smm in earlier unstable releases having the same X.Y may break. 143207753Smm 144207753Smm - S indicates stability of the release. It is missing from the 145244601Smm stable releases, where Y is an even number. When Y is odd, S 146207753Smm is either "alpha" or "beta" to make it very clear that such 147207753Smm versions are not stable releases. The same X.Y.Z combination is 148244601Smm not used for more than one stability level, i.e. after X.Y.Zalpha, 149207753Smm the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta. 150207753Smm 151207753Smm 152207753Smm3. Reporting bugs 153207753Smm----------------- 154207753Smm 155207753Smm Naturally it is easiest for me if you already know what causes the 156207753Smm unexpected behavior. Even better if you have a patch to propose. 157207753Smm However, quite often the reason for unexpected behavior is unknown, 158207753Smm so here are a few things to do before sending a bug report: 159207753Smm 160207753Smm 1. Try to create a small example how to reproduce the issue. 161207753Smm 162207753Smm 2. Compile XZ Utils with debugging code using configure switches 163207753Smm --enable-debug and, if possible, --disable-shared. If you are 164207753Smm using GCC, use CFLAGS='-O0 -ggdb3'. Don't strip the resulting 165207753Smm binaries. 166207753Smm 167207753Smm 3. Turn on core dumps. The exact command depends on your shell; 168207753Smm for example in GNU bash it is done with "ulimit -c unlimited", 169207753Smm and in tcsh with "limit coredumpsize unlimited". 170207753Smm 171207753Smm 4. Try to reproduce the suspected bug. If you get "assertion failed" 172207753Smm message, be sure to include the complete message in your bug 173207753Smm report. If the application leaves a coredump, get a backtrace 174207753Smm using gdb: 175207753Smm $ gdb /path/to/app-binary # Load the app to the debugger. 176207753Smm (gdb) core core # Open the coredump. 177207753Smm (gdb) bt # Print the backtrace. Copy & paste to bug report. 178207753Smm (gdb) quit # Quit gdb. 179207753Smm 180207753Smm Report your bug via email or IRC (see Contact information below). 181207753Smm Don't send core dump files or any executables. If you have a small 182207753Smm example file(s) (total size less than 256 KiB), please include 183207753Smm it/them as an attachment. If you have bigger test files, put them 184244601Smm online somewhere and include a URL to the file(s) in the bug report. 185207753Smm 186207753Smm Always include the exact version number of XZ Utils in the bug report. 187207753Smm If you are using a snapshot from the git repository, use "git describe" 188207753Smm to get the exact snapshot version. If you are using XZ Utils shipped 189207753Smm in an operating system distribution, mention the distribution name, 190207753Smm distribution version, and exact xz package version; if you cannot 191207753Smm repeat the bug with the code compiled from unpatched source code, 192207753Smm you probably need to report a bug to your distribution's bug tracking 193207753Smm system. 194207753Smm 195207753Smm 196360523Sdelphij4. Translations 197360523Sdelphij--------------- 198213700Smm 199360523Sdelphij The xz command line tool and all man pages can be translated. 200360523Sdelphij The translations are handled via the Translation Project. If you 201360523Sdelphij wish to help translating xz, please join the Translation Project: 202213700Smm 203360523Sdelphij https://translationproject.org/html/translators.html 204213700Smm 205360523Sdelphij Several strings will change in a future version of xz so if you 206360523Sdelphij wish to start a new translation, look at the code in the xz git 207360523Sdelphij repostiory instead of a 5.2.x release. 208213700Smm 209213700Smm 210213700Smm5. Other implementations of the .xz format 211207753Smm------------------------------------------ 212207753Smm 213207753Smm 7-Zip and the p7zip port of 7-Zip support the .xz format starting 214207753Smm from the version 9.00alpha. 215207753Smm 216207753Smm http://7-zip.org/ 217207753Smm http://p7zip.sourceforge.net/ 218207753Smm 219207753Smm XZ Embedded is a limited implementation written for use in the Linux 220207753Smm kernel, but it is also suitable for other embedded use. 221207753Smm 222334607Sdelphij https://tukaani.org/xz/embedded.html 223207753Smm 224207753Smm 225213700Smm6. Contact information 226207753Smm---------------------- 227207753Smm 228207753Smm If you have questions, bug reports, patches etc. related to XZ Utils, 229207753Smm contact Lasse Collin <lasse.collin@tukaani.org> (in Finnish or English). 230207753Smm I'm sometimes slow at replying. If you haven't got a reply within two 231207753Smm weeks, assume that your email has got lost and resend it or use IRC. 232207753Smm 233207753Smm You can find me also from #tukaani on Freenode; my nick is Larhzu. 234207753Smm The channel tends to be pretty quiet, so just ask your question and 235207753Smm someone may wake up. 236207753Smm 237