Another grammar fix
[icculus/xz.git] / README
1
2 XZ Utils
3 ========
4
5 Important
6
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).
11
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.
18
19     Excluding the Doxygen style docs in libilzma 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.
23
24
25 Overview
26
27     LZMA is a general purporse compression algorithm designed by
28     Igor Pavlov as part of 7-Zip. It provides high compression ratio
29     while keeping the decompression speed fast.
30
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.
35
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.
48
49
50 Supported platforms
51
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.
55
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.
59
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.
64
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++.
70
71
72 Version numbering
73
74     The version number of XZ Utils has absolutely nothing to do with
75     the version number of LZMA SDK or 7-Zip. The new version number
76     format of XZ Utils is X.Y.ZS:
77
78       - X is the major version. When this is incremented, the library
79         API and ABI break.
80
81       - Y is the minor version. It is incremented when new features are
82         added without breaking existing API or ABI. Even Y indicates
83         stable release and odd Y indicates unstable (alpha or beta
84         version).
85
86       - Z is the revision. This has different meaning for stable and
87         unstable releases:
88           * Stable: Z is incremented when bugs get fixed without adding
89             any new features.
90           * Unstable: Z is just a counter. API or ABI of features added
91             in earlier unstable releases having the same X.Y may break.
92
93       - S indicates stability of the release. It is missing from the
94         stable releases where Y is an even number. When Y is odd, S
95         is either "alpha" or "beta" to make it very clear that such
96         versions are not stable releases. The same X.Y.Z combination is
97         not used for more than one stability level i.e. after X.Y.Zalpha,
98         the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta.
99
100
101 configure options
102
103     If you are not familiar with `configure' scripts, read the file
104     INSTALL first.
105
106     In most cases, the default --enable/--disable/--with/--without options
107     are what you want. Don't touch them if you are unsure.
108
109     --disable-encoder
110                 Do not compile the encoder component of liblzma. This
111                 implies --disable-match-finders. If you need only
112                 the decoder, you can decrease the library size
113                 dramatically with this option.
114
115                 The default is to build the encoder.
116
117     --disable-decoder
118                 Do not compile the decoder component of liblzma.
119
120                 The default is to build the decoder.
121
122     --enable-filters=
123                 liblzma supports several filters. See liblzma-intro.txt
124                 for a little more information about these.
125
126                 The default is to build all the filters.
127
128     --enable-match-finders=
129                 liblzma includes two categories of match finders:
130                 hash chains and binary trees. Hash chains (hc3 and hc4)
131                 are quite fast but they don't provide the best compression
132                 ratio. Binary trees (bt2, bt3 and bt4) give excellent
133                 compression ratio, but they are slower and need more
134                 memory than hash chains.
135
136                 You need to enable at least one match finder to build the
137                 LZMA filter encoder. Usually hash chains are used only in
138                 the fast mode, while binary trees are used to when the best
139                 compression ratio is wanted.
140
141                 The default is to build all the match finders.
142
143     --enable-checks=
144                 liblzma support multiple integrity checks. CRC32 is
145                 mandatory, and cannot be omitted. See liblzma-intro.txt
146                 for more information about usage of the integrity checks.
147
148     --disable-assembler
149                 liblzma includes some assembler optimizations. Currently
150                 there is only assembler code for CRC32 and CRC64 for
151                 32-bit x86.
152
153                 All the assembler code in liblzma is position-independent
154                 code, which is suitable for use in shared libraries and
155                 position-independent executables. So far only i386
156                 instructions are used, but the code is optimized for i686
157                 class CPUs. If you are compiling liblzma exclusively for
158                 pre-i686 systems, you may want to disable the assembler
159                 code.
160
161     --enable-small
162                 Omits precomputed tables. This makes liblzma a few KiB
163                 smaller. Startup time increases, because the tables need
164                 to be computed first.
165
166     --enable-debug
167                 This enables the assert() macro and possibly some other
168                 run-time consistency checks. It slows down things somewhat,
169                 so you normally don't want to have this enabled.
170
171     --enable-werror
172                 Makes all compiler warnings an error, that abort the
173                 compilation. This may help catching bugs, and should work
174                 on most systems. This has no effect on the resulting
175                 binaries.
176
177
178 Static vs. dynamic linking of the command line tools
179
180     By default, the command line tools are linked statically against
181     liblzma. There a are a few reasons:
182
183       - The executable(s) can be in /bin while the shared liblzma can still
184         be in /usr/lib (if the distro uses such file system hierachy).
185
186       - It's easier to copy the executables to other systems, since they
187         depend only on libc.
188
189       - It's slightly faster on some architectures like x86.
190
191     If you don't like this, you can get the command line tools linked
192     against the shared liblzma by specifying --disable-static to configure.
193     This disables building static liblzma completely.
194