Mercurial > repos > rliterman > csp2
comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/xz/README @ 68:5028fdace37b
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author | jpayne |
---|---|
date | Tue, 18 Mar 2025 16:23:26 -0400 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
67:0e9998148a16 | 68:5028fdace37b |
---|---|
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 XZ Utils in general: | |
302 - Home page: https://tukaani.org/xz/ | |
303 - Email to maintainer(s): xz@tukaani.org | |
304 - IRC: #tukaani on Libera Chat | |
305 - GitHub: https://github.com/tukaani-project/xz | |
306 | |
307 Lead maintainer: | |
308 - Email: Lasse Collin <lasse.collin@tukaani.org> | |
309 - IRC: Larhzu on Libera Chat | |
310 |