README

   1
   2 XZ Utils
   3 ========
   4
   5     0. Overview
   6     1. Documentation
   7        1.1. Overall documentation
   8        1.2. Documentation for command-line tools
   9        1.3. Documentation for liblzma
  10     2. Version numbering
  11     3. Reporting bugs
  12     4. Translations
  13     5. Other implementations of the .xz format
  14     6. Contact information
  15
  16
  17 0. Overview
  18 -----------
  19
  20     XZ Utils provide a general-purpose data-compression library plus
  21     command-line tools. The native file format is the .xz format, but
  22     also the legacy .lzma format is supported. The .xz format supports
  23     multiple compression algorithms, which are called "filters" in the
  24     context of XZ Utils. The primary filter is currently LZMA2. With
  25     typical files, XZ Utils create about 30 % smaller files than gzip.
  26
  27     To ease adapting support for the .xz format into existing applications
  28     and scripts, the API of liblzma is somewhat similar to the API of the
  29     popular zlib library. For the same reason, the command-line tool xz
  30     has a command-line syntax similar to that of gzip.
  31
  32     When aiming for the highest compression ratio, the LZMA2 encoder uses
  33     a lot of CPU time and may use, depending on the settings, even
  34     hundreds of megabytes of RAM. However, in fast modes, the LZMA2 encoder
  35     competes with bzip2 in compression speed, RAM usage, and compression
  36     ratio.
  37
  38     LZMA2 is reasonably fast to decompress. It is a little slower than
  39     gzip, but a lot faster than bzip2. Being fast to decompress means
  40     that the .xz format is especially nice when the same file will be
  41     decompressed very many times (usually on different computers), which
  42     is the case e.g. when distributing software packages. In such
  43     situations, it's not too bad if the compression takes some time,
  44     since that needs to be done only once to benefit many people.
  45
  46     With some file types, combining (or "chaining") LZMA2 with an
  47     additional filter can improve the compression ratio. A filter chain may
  48     contain up to four filters, although usually only one or two are used.
  49     For example, putting a BCJ (Branch/Call/Jump) filter before LZMA2
  50     in the filter chain can improve compression ratio of executable files.
  51
  52     Since the .xz format allows adding new filter IDs, it is possible that
  53     some day there will be a filter that is, for example, much faster to
  54     compress than LZMA2 (but probably with worse compression ratio).
  55     Similarly, it is possible that some day there is a filter that will
  56     compress better than LZMA2.
  57
  58     XZ Utils supports multithreaded compression. XZ Utils doesn't support
  59     multithreaded decompression yet. It has been planned though and taken
  60     into account when designing the .xz file format. In the future, files
  61     that were created in threaded mode can be decompressed in threaded
  62     mode too.
  63
  64
  65 1. Documentation
  66 ----------------
  67
  68 1.1. Overall documentation
  69
  70     README                This file
  71
  72     INSTALL.generic       Generic install instructions for those not
  73                           familiar with packages using GNU Autotools
  74     INSTALL               Installation instructions specific to XZ Utils
  75     PACKAGERS             Information to packagers of XZ Utils
  76
  77     COPYING               XZ Utils copyright and license information
  78     COPYING.0BSD          BSD Zero Clause License
  79     COPYING.GPLv2         GNU General Public License version 2
  80     COPYING.GPLv3         GNU General Public License version 3
  81     COPYING.LGPLv2.1      GNU Lesser General Public License version 2.1
  82
  83     AUTHORS               The main authors of XZ Utils
  84     THANKS                Incomplete list of people who have helped making
  85                           this software
  86     NEWS                  User-visible changes between XZ Utils releases
  87     ChangeLog             Detailed list of changes (commit log)
  88     TODO                  Known bugs and some sort of to-do list
  89
  90     Note that only some of the above files are included in binary
  91     packages.
  92
  93
  94 1.2. Documentation for command-line tools
  95
  96     The command-line tools are documented as man pages. In source code
  97     releases (and possibly also in some binary packages), the man pages
  98     are also provided in plain text (ASCII only) format in the directory
  99     "doc/man" to make the man pages more accessible to those whose
 100     operating system doesn't provide an easy way to view man pages.
 101
 102
 103 1.3. Documentation for liblzma
 104
 105     The liblzma API headers include short docs about each function
 106     and data type as Doxygen tags. These docs should be quite OK as
 107     a quick reference.
 108
 109     There are a few example/tutorial programs that should help in
 110     getting started with liblzma. In the source package the examples
 111     are in "doc/examples" and in binary packages they may be under
 112     "examples" in the same directory as this README.
 113
 114     Since the liblzma API has similarities to the zlib API, some people
 115     may find it useful to read the zlib docs and tutorial too:
 116
 117         https://zlib.net/manual.html
 118         https://zlib.net/zlib_how.html
 119
 120
 121 2. Version numbering
 122 --------------------
 123
 124     The version number format of XZ Utils is X.Y.ZS:
 125
 126       - X is the major version. When this is incremented, the library
 127         API and ABI break.
 128
 129       - Y is the minor version. It is incremented when new features
 130         are added without breaking the existing API or ABI. An even Y
 131         indicates a stable release and an odd Y indicates unstable
 132         (alpha or beta version).
 133
 134       - Z is the revision. This has a different meaning for stable and
 135         unstable releases:
 136
 137           * Stable: Z is incremented when bugs get fixed without adding
 138             any new features. This is intended to be convenient for
 139             downstream distributors that want bug fixes but don't want
 140             any new features to minimize the risk of introducing new bugs.
 141
 142           * Unstable: Z is just a counter. API or ABI of features added
 143             in earlier unstable releases having the same X.Y may break.
 144
 145       - S indicates stability of the release. It is missing from the
 146         stable releases, where Y is an even number. When Y is odd, S
 147         is either "alpha" or "beta" to make it very clear that such
 148         versions are not stable releases. The same X.Y.Z combination is
 149         not used for more than one stability level, i.e. after X.Y.Zalpha,
 150         the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta.
 151
 152
 153 3. Reporting bugs
 154 -----------------
 155
 156     Naturally it is easiest for me if you already know what causes the
 157     unexpected behavior. Even better if you have a patch to propose.
 158     However, quite often the reason for unexpected behavior is unknown,
 159     so here are a few things to do before sending a bug report:
 160
 161       1. Try to create a small example how to reproduce the issue.
 162
 163       2. Compile XZ Utils with debugging code using configure switches
 164          --enable-debug and, if possible, --disable-shared. If you are
 165          using GCC, use CFLAGS='-O0 -ggdb3'. Don't strip the resulting
 166          binaries.
 167
 168       3. Turn on core dumps. The exact command depends on your shell;
 169          for example in GNU bash it is done with "ulimit -c unlimited",
 170          and in tcsh with "limit coredumpsize unlimited".
 171
 172       4. Try to reproduce the suspected bug. If you get "assertion failed"
 173          message, be sure to include the complete message in your bug
 174          report. If the application leaves a coredump, get a backtrace
 175          using gdb:
 176            $ gdb /path/to/app-binary   # Load the app to the debugger.
 177            (gdb) core core   # Open the coredump.
 178            (gdb) bt   # Print the backtrace. Copy & paste to bug report.
 179            (gdb) quit   # Quit gdb.
 180
 181     Report your bug via email or IRC (see Contact information below).
 182     Don't send core dump files or any executables. If you have a small
 183     example file(s) (total size less than 256 KiB), please include
 184     it/them as an attachment. If you have bigger test files, put them
 185     online somewhere and include a URL to the file(s) in the bug report.
 186
 187     Always include the exact version number of XZ Utils in the bug report.
 188     If you are using a snapshot from the git repository, use "git describe"
 189     to get the exact snapshot version. If you are using XZ Utils shipped
 190     in an operating system distribution, mention the distribution name,
 191     distribution version, and exact xz package version; if you cannot
 192     repeat the bug with the code compiled from unpatched source code,
 193     you probably need to report a bug to your distribution's bug tracking
 194     system.
 195
 196
 197 4. Translations
 198 ---------------
 199
 200     The xz command line tool and all man pages can be translated.
 201     The translations are handled via the Translation Project. If you
 202     wish to help translating xz, please join the Translation Project:
 203
 204         https://translationproject.org/html/translators.html
 205
 206     Below are notes and testing instructions specific to xz
 207     translations.
 208
 209     Testing can be done by installing xz into a temporary directory:
 210
 211         ./configure --disable-shared --prefix=/tmp/xz-test
 212         # <Edit the .po file in the po directory.>
 213         make -C po update-po
 214         make install
 215         bash debug/translation.bash | less
 216         bash debug/translation.bash | less -S  # For --list outputs
 217
 218     Repeat the above as needed (no need to re-run configure though).
 219
 220     Note especially the following:
 221
 222       - The output of --help and --long-help must look nice on
 223         an 80-column terminal. It's OK to add extra lines if needed.
 224
 225       - In contrast, don't add extra lines to error messages and such.
 226         They are often preceded with e.g. a filename on the same line,
 227         so you have no way to predict where to put a \n. Let the terminal
 228         do the wrapping even if it looks ugly. Adding new lines will be
 229         even uglier in the generic case even if it looks nice in a few
 230         limited examples.
 231
 232       - Be careful with column alignment in tables and table-like output
 233         (--list, --list --verbose --verbose, --info-memory, --help, and
 234         --long-help):
 235
 236           * All descriptions of options in --help should start in the
 237             same column (but it doesn't need to be the same column as
 238             in the English messages; just be consistent if you change it).
 239             Check that both --help and --long-help look OK, since they
 240             share several strings.
 241
 242           * --list --verbose and --info-memory print lines that have
 243             the format "Description:   %s". If you need a longer
 244             description, you can put extra space between the colon
 245             and %s. Then you may need to add extra space to other
 246             strings too so that the result as a whole looks good (all
 247             values start at the same column).
 248
 249           * The columns of the actual tables in --list --verbose --verbose
 250             should be aligned properly. Abbreviate if necessary. It might
 251             be good to keep at least 2 or 3 spaces between column headings
 252             and avoid spaces in the headings so that the columns stand out
 253             better, but this is a matter of opinion. Do what you think
 254             looks best.
 255
 256       - Be careful to put a period at the end of a sentence when the
 257         original version has it, and don't put it when the original
 258         doesn't have it. Similarly, be careful with \n characters
 259         at the beginning and end of the strings.
 260
 261       - Read the TRANSLATORS comments that have been extracted from the
 262         source code and included in xz.pot. Some comments suggest
 263         testing with a specific command which needs an .xz file. You
 264         may use e.g. any tests/files/good-*.xz. However, these test
 265         commands are included in translations.bash output, so reading
 266         translations.bash output carefully can be enough.
 267
 268       - If you find language problems in the original English strings,
 269         feel free to suggest improvements. Ask if something is unclear.
 270
 271       - The translated messages should be understandable (sometimes this
 272         may be a problem with the original English messages too). Don't
 273         make a direct word-by-word translation from English especially if
 274         the result doesn't sound good in your language.
 275
 276     Thanks for your help!
 277
 278
 279 5. Other implementations of the .xz format
 280 ------------------------------------------
 281
 282     7-Zip and the p7zip port of 7-Zip support the .xz format starting
 283     from the version 9.00alpha.
 284
 285         https://7-zip.org/
 286         https://p7zip.sourceforge.net/
 287
 288     XZ Embedded is a limited implementation written for use in the Linux
 289     kernel, but it is also suitable for other embedded use.
 290
 291         https://tukaani.org/xz/embedded.html
 292
 293     XZ for Java is a complete implementation written in pure Java.
 294
 295         https://tukaani.org/xz/java.html
 296
 297
 298 6. Contact information
 299 ----------------------
 300
 301     Email: Lasse Collin <lasse.collin@tukaani.org>
 302     IRC: Larhzu on #tukaani on Libera Chat
 303     GitHub: https://github.com/tukaani-project/xz
 304