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