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