diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 303 |
1 files changed, 303 insertions, 0 deletions
@@ -0,0 +1,303 @@ + +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. Reporting bugs + 4. Translations + 5. Other implementations of the .xz format + 6. Contact information + + +0. Overview +----------- + + XZ Utils provide a general-purpose data-compression library plus + 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 the + 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 a command-line syntax similar to that of gzip. + + When aiming for the highest compression ratio, the 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, the 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 the compression ratio. A filter chain may + contain up to four filters, although usually only one or two are 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 supports multithreaded compression. XZ Utils doesn't support + multithreaded decompression yet. It has been planned though and taken + into account when designing the .xz file format. In the future, files + that were created in threaded mode can be decompressed in threaded + mode too. + + +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) + TODO Known bugs and some sort of to-do list + + 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. + + There are a few example/tutorial programs that should help in + getting started with liblzma. In the source package the examples + are in "doc/examples" and in binary packages they may be under + "examples" in the same directory as this README. + + Since the liblzma API has similarities to the zlib API, some people + may find it useful to read the zlib docs and tutorial too: + + 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 the existing API or ABI. An even Y + indicates a stable release and an odd Y indicates unstable + (alpha or beta version). + + - Z is the revision. This has a different meaning for stable and + unstable releases: + + * Stable: Z is incremented when bugs get fixed without adding + any new features. This is intended to be convenient for + downstream distributors that want bug fixes but don't want + any new features to minimize the risk of introducing new bugs. + + * 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. Reporting bugs +----------------- + + Naturally it is easiest for me if you already know what causes the + unexpected behavior. Even better if you have a patch to propose. + However, quite often the reason for unexpected behavior is unknown, + so here are a few things to do before sending a bug report: + + 1. Try to create a small example how to reproduce the issue. + + 2. Compile XZ Utils with debugging code using configure switches + --enable-debug and, if possible, --disable-shared. If you are + using GCC, use CFLAGS='-O0 -ggdb3'. Don't strip the resulting + binaries. + + 3. Turn on core dumps. The exact command depends on your shell; + for example in GNU bash it is done with "ulimit -c unlimited", + and in tcsh with "limit coredumpsize unlimited". + + 4. Try to reproduce the suspected bug. If you get "assertion failed" + message, be sure to include the complete message in your bug + report. If the application leaves a coredump, get a backtrace + using gdb: + $ gdb /path/to/app-binary # Load the app to the debugger. + (gdb) core core # Open the coredump. + (gdb) bt # Print the backtrace. Copy & paste to bug report. + (gdb) quit # Quit gdb. + + Report your bug via email or IRC (see Contact information below). + Don't send core dump files or any executables. If you have a small + example file(s) (total size less than 256 KiB), please include + it/them as an attachment. If you have bigger test files, put them + online somewhere and include a URL to the file(s) in the bug report. + + Always include the exact version number of XZ Utils in the bug report. + If you are using a snapshot from the git repository, use "git describe" + to get the exact snapshot version. If you are using XZ Utils shipped + in an operating system distribution, mention the distribution name, + distribution version, and exact xz package version; if you cannot + repeat the bug with the code compiled from unpatched source code, + you probably need to report a bug to your distribution's bug tracking + system. + + +4. Translations +--------------- + + The xz command line tool and all man pages can be translated. + The translations are handled via the Translation Project. If you + wish to help translating xz, please join the Translation Project: + + https://translationproject.org/html/translators.html + + Below are notes and testing instructions specific to xz + translations. + + Testing can be done by installing xz into a temporary directory: + + ./configure --disable-shared --prefix=/tmp/xz-test + # <Edit the .po file in the po directory.> + make -C po update-po + make install + bash debug/translation.bash | less + bash debug/translation.bash | less -S # For --list outputs + + Repeat the above as needed (no need to re-run configure though). + + Note especially the following: + + - The output of --help and --long-help must look nice on + an 80-column terminal. It's OK to add extra lines if needed. + + - In contrast, don't add extra lines to error messages and such. + They are often preceded with e.g. a filename on the same line, + so you have no way to predict where to put a \n. Let the terminal + do the wrapping even if it looks ugly. Adding new lines will be + even uglier in the generic case even if it looks nice in a few + limited examples. + + - Be careful with column alignment in tables and table-like output + (--list, --list --verbose --verbose, --info-memory, --help, and + --long-help): + + * All descriptions of options in --help should start in the + same column (but it doesn't need to be the same column as + in the English messages; just be consistent if you change it). + Check that both --help and --long-help look OK, since they + share several strings. + + * --list --verbose and --info-memory print lines that have + the format "Description: %s". If you need a longer + description, you can put extra space between the colon + and %s. Then you may need to add extra space to other + strings too so that the result as a whole looks good (all + values start at the same column). + + * The columns of the actual tables in --list --verbose --verbose + should be aligned properly. Abbreviate if necessary. It might + be good to keep at least 2 or 3 spaces between column headings + and avoid spaces in the headings so that the columns stand out + better, but this is a matter of opinion. Do what you think + looks best. + + - Be careful to put a period at the end of a sentence when the + original version has it, and don't put it when the original + doesn't have it. Similarly, be careful with \n characters + at the beginning and end of the strings. + + - Read the TRANSLATORS comments that have been extracted from the + source code and included in xz.pot. Some comments suggest + testing with a specific command which needs an .xz file. You + may use e.g. any tests/files/good-*.xz. However, these test + commands are included in translations.bash output, so reading + translations.bash output carefully can be enough. + + - If you find language problems in the original English strings, + feel free to suggest improvements. Ask if something is unclear. + + - The translated messages should be understandable (sometimes this + may be a problem with the original English messages too). Don't + make a direct word-by-word translation from English especially if + the result doesn't sound good in your language. + + Thanks for your help! + + +5. 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. + + https://tukaani.org/xz/embedded.html + + +6. Contact information +---------------------- + + If you have questions, bug reports, patches etc. related to XZ Utils, + the project maintainers Lasse Collin and Jia Tan can be reached via + <xz@tukaani.org>. + + You might find Lasse also from #tukaani on Libera Chat (IRC). + The nick is Larhzu. The channel tends to be pretty quiet, + so just ask your question and someone might wake up. + |