| blob | 24467cd08a2d090e5b3d8392b11675feacce27f1 |
2 XZ Utils
3 ========
5 Important
7 This is a beta version. The .xz file format is now stable though,
8 which means that files created with the beta version will be
9 decompressible with all future XZ Utils versions too (assuming
10 that there are no catastrophic bugs).
12 liblzma API is pretty stable now, although minor tweaks may still
13 be done if really needed. The ABI is not stable yet. The major
14 soname will be bumped right before the first stable release.
15 Probably it will be bumped to something like .so.5.0.0 because
16 some distributions using the alpha versions already had to use
17 other versions than .so.0.0.0.
19 Excluding the Doxygen style docs in liblzma API headers, the
20 documentation in this package (including the rest of this
21 README) is not very up to date, and may contain incorrect or
22 misleading information.
25 Overview
27 LZMA is a general purpose compression algorithm designed by
28 Igor Pavlov as part of 7-Zip. It provides high compression ratio
29 while keeping the decompression speed fast.
31 XZ Utils are an attempt to make LZMA compression easy to use
32 on free (as in freedom) operating systems. This is achieved by
33 providing tools and libraries which are similar to use than the
34 equivalents of the most popular existing compression algorithms.
36 XZ Utils consist of a few relatively separate parts:
37 * liblzma is an encoder/decoder library with support for several
38 filters (algorithm implementations). The primary filter is LZMA.
39 * libzfile (or whatever the name will be) enables reading from and
40 writing to gzip, bzip2 and LZMA compressed and uncompressed files
41 with an API similar to the standard ANSI-C file I/O.
42 [ NOTE: libzfile is not implemented yet. ]
43 * xz command line tool has almost identical syntax than gzip
44 and bzip2. It makes LZMA easy for average users, but also
45 provides advanced options to finetune the compression settings.
46 * A few shell scripts make diffing and grepping LZMA compressed
47 files easy. The scripts were adapted from gzip and bzip2.
50 Supported platforms
52 XZ Utils are developed on GNU+Linux, but they should work at
53 least on *BSDs and Solaris. They probably work on some other
54 POSIX-like operating systems too.
56 If you use GCC to compile XZ Utils, you need at least version
57 3.x.x. GCC version 2.xx.x doesn't support some C99 features used
58 in XZ Utils source code, thus GCC 2 won't compile XZ Utils.
60 If you have written patches to make XZ Utils to work on previously
61 unsupported platform, please send the patches to me! I will consider
62 including them to the official version. It's nice to minimize the
63 need of third-party patching.
65 One exception: Don't request or send patches to change the whole
66 source package to C89. I find C99 substantially nicer to write and
67 maintain. However, the public library headers must be in C89 to
68 avoid frustrating those who maintain programs, which are strictly
69 in C89 or C++.
72 Platform-specific notes
74 On some Tru64 systems using the native C99 compiler, the configure
75 script may reject the compiler as non-C99 compiler. This may happen
76 if there is no stdbool.h available. You can still compile XZ Utils
77 on such a system by passing ac_cv_prog_cc_c99= to configure script.
78 Fixing this bug seems to be non-trivial since if the configure
79 doesn't check for stdbool.h, it runs into problems at least on
80 Solaris.
83 Version numbering
85 The version number of XZ Utils has absolutely nothing to do with
86 the version number of LZMA SDK or 7-Zip. The new version number
87 format of XZ Utils is X.Y.ZS:
89 - X is the major version. When this is incremented, the library
90 API and ABI break.
92 - Y is the minor version. It is incremented when new features are
93 added without breaking existing API or ABI. Even Y indicates
94 stable release and odd Y indicates unstable (alpha or beta
95 version).
97 - Z is the revision. This has different meaning for stable and
98 unstable releases:
99 * Stable: Z is incremented when bugs get fixed without adding
100 any new features.
101 * Unstable: Z is just a counter. API or ABI of features added
102 in earlier unstable releases having the same X.Y may break.
104 - S indicates stability of the release. It is missing from the
105 stable releases where Y is an even number. When Y is odd, S
106 is either "alpha" or "beta" to make it very clear that such
107 versions are not stable releases. The same X.Y.Z combination is
108 not used for more than one stability level i.e. after X.Y.Zalpha,
109 the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta.
112 configure options
114 If you are not familiar with `configure' scripts, read the file
115 INSTALL first.
117 In most cases, the default --enable/--disable/--with/--without options
118 are what you want. Don't touch them if you are unsure.
120 --disable-encoder
121 Do not compile the encoder component of liblzma. This
122 implies --disable-match-finders. If you need only
123 the decoder, you can decrease the library size
124 dramatically with this option.
126 The default is to build the encoder.
128 --disable-decoder
129 Do not compile the decoder component of liblzma.
131 The default is to build the decoder.
133 --enable-filters=
134 liblzma supports several filters. See liblzma-intro.txt
135 for a little more information about these.
137 The default is to build all the filters.
139 --enable-match-finders=
140 liblzma includes two categories of match finders:
141 hash chains and binary trees. Hash chains (hc3 and hc4)
142 are quite fast but they don't provide the best compression
143 ratio. Binary trees (bt2, bt3 and bt4) give excellent
144 compression ratio, but they are slower and need more
145 memory than hash chains.
147 You need to enable at least one match finder to build the
148 LZMA filter encoder. Usually hash chains are used only in
149 the fast mode, while binary trees are used to when the best
150 compression ratio is wanted.
152 The default is to build all the match finders.
154 --enable-checks=
155 liblzma support multiple integrity checks. CRC32 is
156 mandatory, and cannot be omitted. See liblzma-intro.txt
157 for more information about usage of the integrity checks.
159 --disable-assembler
160 liblzma includes some assembler optimizations. Currently
161 there is only assembler code for CRC32 and CRC64 for
162 32-bit x86.
164 All the assembler code in liblzma is position-independent
165 code, which is suitable for use in shared libraries and
166 position-independent executables. So far only i386
167 instructions are used, but the code is optimized for i686
168 class CPUs. If you are compiling liblzma exclusively for
169 pre-i686 systems, you may want to disable the assembler
170 code.
172 --enable-small
173 Omits precomputed tables. This makes liblzma a few KiB
174 smaller. Startup time increases, because the tables need
175 to be computed first.
177 --enable-debug
178 This enables the assert() macro and possibly some other
179 run-time consistency checks. It slows down things somewhat,
180 so you normally don't want to have this enabled.
182 --enable-werror
183 Makes all compiler warnings an error, that abort the
184 compilation. This may help catching bugs, and should work
185 on most systems. This has no effect on the resulting
186 binaries.
189 Static vs. dynamic linking of the command line tools
191 By default, the command line tools are linked statically against
192 liblzma. There a are a few reasons:
194 - The executable(s) can be in /bin while the shared liblzma can still
195 be in /usr/lib (if the distro uses such file system hierarchy).
197 - It's easier to copy the executables to other systems, since they
198 depend only on libc.
200 - It's slightly faster on some architectures like x86.
202 If you don't like this, you can get the command line tools linked
203 against the shared liblzma by specifying --disable-static to configure.
204 This disables building static liblzma completely.