Updated README regarding the assembler optimizations.
[icculus/xz.git] / README
1
2 LZMA Utils
3 ----------
4
5 Warning
6
7     This is an early alpha version. Don't trust the files produced by
8     this version of the software - not even if the software can
9     uncompress the files properly! This is because the file format
10     isn't completely frozen yet.
11
12     So please test a lot, but don't use for anything serious yet.
13
14
15 Overview
16
17     LZMA is a general purporse compression algorithm designed by
18     Igor Pavlov as part of 7-Zip. It provides high compression ratio
19     while keeping the decompression speed fast.
20
21     LZMA Utils are an attempt to make LZMA compression easy to use
22     on free (as in freedom) operating systems. This is achieved by
23     providing tools and libraries which are similar to use than the
24     equivalents of the most popular existing compression algorithms.
25
26     LZMA Utils consist of a few relatively separate parts:
27       * liblzma is an encoder/decoder library with support for several
28         filters (algorithm implementations). The primary filter is LZMA.
29       * libzfile enables reading from and writing to gzip, bzip2 and
30         LZMA compressed and uncompressed files with an API similar to
31         the standard ANSI-C file I/O.
32         [ NOTE: libzfile is not implemented yet. ]
33       * lzma command line tool has almost identical syntax than gzip
34         and bzip2. It makes LZMA easy for average users, but also
35         provides advanced options to finetune the compression settings.
36       * A few shell scripts make diffing and grepping LZMA compressed
37         files easy. The scripts were adapted from gzip and bzip2.
38
39
40 Supported platforms
41
42     LZMA Utils are developed on GNU+Linux, but they should work at
43     least on *BSDs and Solaris. They probably work on some other
44     POSIX-like operating systems too.
45
46     If you use GCC to compile LZMA Utils, you need at least version
47     3.x.x. GCC version 2.xx.x doesn't support some C99 features used
48     in LZMA Utils source code, thus GCC 2 won't compile LZMA Utils.
49
50     If you have written patches to make LZMA Utils to work on previously
51     unsupported platform, please send the patches to me! I will consider
52     including them to the official version. It's nice to minimize the
53     need of third-party patching.
54
55     One exception: Don't request or send patches to change the whole
56     source package to C89. I find C99 substantially nicer to write and
57     maintain. However, the public library headers must be in C89 to
58     avoid frustrating those who maintain programs, which are strictly
59     in C89 or C++.
60
61
62 configure options
63
64     If you are not familiar with `configure' scripts, read the file
65     INSTALL first.
66
67     In most cases, the default --enable/--disable/--with/--without options
68     are what you want. Don't touch them if you are unsure.
69
70     --disable-encoder
71                 Do not compile the encoder component of liblzma. This
72                 implies --disable-match-finders. If you need only
73                 the decoder, you can decrease the library size
74                 dramatically with this option.
75
76                 The default is to build the encoder.
77
78     --disable-decoder
79                 Do not compile the decoder component of liblzma.
80
81                 The default is to build the decoder.
82
83     --enable-filters=
84                 liblzma supports several filters. See liblzma-intro.txt
85                 for a little more information about these.
86
87                 The default is to build all the filters.
88
89     --enable-match-finders=
90                 liblzma includes two categories of match finders:
91                 hash chains and binary trees. Hash chains (hc3 and hc4)
92                 are quite fast but they don't provide the best compression
93                 ratio. Binary trees (bt2, bt3 and bt4) give excellent
94                 compression ratio, but they are slower and need more
95                 memory than hash chains.
96
97                 You need to enable at least one match finder to build the
98                 LZMA filter encoder. Usually hash chains are used only in
99                 the fast mode, while binary trees are used to when the best
100                 compression ratio is wanted.
101
102                 The default is to build all the match finders.
103
104     --enable-checks=
105                 liblzma support multiple integrity checks. CRC32 is
106                 mandatory, and cannot be omitted. See liblzma-intro.txt
107                 for more information about usage of the integrity checks.
108
109     --disable-assembler
110                 liblzma includes some assembler optimizations. Currently
111                 there is only assembler code for CRC32 and CRC64 for
112                 32-bit x86.
113
114                 All the assembler code in liblzma is position-independent
115                 code, which is suitable for use in shared libraries and
116                 position-independent executables. So far only i386
117                 instructions are used, but the code is optimized for i686
118                 class CPUs. If you are compiling liblzma exclusively for
119                 pre-i686 systems, you may want to disable the assembler
120                 code.
121
122     --enable-small
123                 Omits precomputed tables. This makes liblzma a few KiB
124                 smaller. Startup time increases, because the tables need
125                 to be computed first.
126
127     --enable-debug
128                 This enables the assert() macro and possibly some other
129                 run-time consistency checks. It slows down things somewhat,
130                 so you normally don't want to have this enabled.
131
132     --enable-werror
133                 Makes all compiler warnings an error, that abort the
134                 compilation. This may help catching bugs, and should work
135                 on most systems. This has no effect on the resulting
136                 binaries.
137
138
139 Static vs. dynamic linking of the command line tools
140
141     By default, the command line tools are linked statically against
142     liblzma. There a are a few reasons:
143
144       - The executable(s) can be in /bin while the shared liblzma can still
145         be in /usr/lib (if the distro uses such file system hierachy).
146
147       - It's easier to copy the executables to other systems, since they
148         depend only on libc.
149
150       - It's slightly faster on some architectures like x86.
151
152     If you don't like this, you can get the command line tools linked
153     against the shared liblzma by specifying --disable-static to configure.
154     This disables building static liblzma completely.
155