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