2 This is the README for bzip2, a block-sorting file compressor, version
3 1.0.2. This version is fully compatible with the previous public
4 releases, versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0 and 1.0.1.
6 bzip2-1.0.2 is distributed under a BSD-style license. For details,
9 Complete documentation is available in Postscript form (manual.ps),
10 PDF (manual.pdf, amazingly enough) or html (manual_toc.html). A
11 plain-text version of the manual page is available as bzip2.txt.
12 A statement about Y2K issues is now included in the file Y2K_INFO.
17 Type `make'. This builds the library libbz2.a and then the
18 programs bzip2 and bzip2recover. Six self-tests are run.
19 If the self-tests complete ok, carry on to installation:
21 To install in /usr/bin, /usr/lib, /usr/man and /usr/include, type
23 To install somewhere else, eg, /xxx/yyy/{bin,lib,man,include}, type
24 make install PREFIX=/xxx/yyy
25 If you are (justifiably) paranoid and want to see what 'make install'
26 is going to do, you can first do
28 make -n install PREFIX=/xxx/yyy respectively.
29 The -n instructs make to show the commands it would execute, but
30 not actually execute them.
33 HOW TO BUILD -- UNIX, shared library libbz2.so.
35 Do 'make -f Makefile-libbz2_so'. This Makefile seems to work for
36 Linux-ELF (RedHat 7.2 on an x86 box), with gcc. I make no claims
37 that it works for any other platform, though I suspect it probably
38 will work for most platforms employing both ELF and gcc.
40 bzip2-shared, a client of the shared library, is also built, but not
41 self-tested. So I suggest you also build using the normal Makefile,
42 since that conducts a self-test. A second reason to prefer the
43 version statically linked to the library is that, on x86 platforms,
44 building shared objects makes a valuable register (%ebx) unavailable
45 to gcc, resulting in a slowdown of 10%-20%, at least for bzip2.
47 Important note for people upgrading .so's from 0.9.0/0.9.5 to version
48 1.0.X. All the functions in the library have been renamed, from (eg)
49 bzCompress to BZ2_bzCompress, to avoid namespace pollution.
50 Unfortunately this means that the libbz2.so created by
51 Makefile-libbz2_so will not work with any program which used an older
52 version of the library. Sorry. I do encourage library clients to
53 make the effort to upgrade to use version 1.0, since it is both faster
54 and more robust than previous versions.
57 HOW TO BUILD -- Windows 95, NT, DOS, Mac, etc.
59 It's difficult for me to support compilation on all these platforms.
60 My approach is to collect binaries for these platforms, and put them
61 on the master web page (http://sources.redhat.com/bzip2). Look there.
62 However (FWIW), bzip2-1.0.X is very standard ANSI C and should compile
63 unmodified with MS Visual C. If you have difficulties building, you
64 might want to read README.COMPILATION.PROBLEMS.
66 At least using MS Visual C++ 6, you can build from the unmodified
67 sources by issuing, in a command shell:
69 (you may need to first run the MSVC-provided script VCVARS32.BAT
70 so as to set up paths to the MSVC tools correctly).
75 Correct operation, in the sense that a compressed file can always be
76 decompressed to reproduce the original, is obviously of paramount
77 importance. To validate bzip2, I used a modified version of Mark
78 Nelson's churn program. Churn is an automated test driver which
79 recursively traverses a directory structure, using bzip2 to compress
80 and then decompress each file it encounters, and checking that the
81 decompressed data is the same as the original. There are more details
82 in Section 4 of the user guide.
86 Please read and be aware of the following:
90 This program (attempts to) compress data by performing several
91 non-trivial transformations on it. Unless you are 100% familiar
92 with *all* the algorithms contained herein, and with the
93 consequences of modifying them, you should NOT meddle with the
94 compression or decompression machinery. Incorrect changes can and
95 very likely *will* lead to disastrous loss of data.
100 I TAKE NO RESPONSIBILITY FOR ANY LOSS OF DATA ARISING FROM THE
101 USE OF THIS PROGRAM, HOWSOEVER CAUSED.
103 Every compression of a file implies an assumption that the
104 compressed file can be decompressed to reproduce the original.
105 Great efforts in design, coding and testing have been made to
106 ensure that this program works correctly. However, the complexity
107 of the algorithms, and, in particular, the presence of various
108 special cases in the code which occur with very low but non-zero
109 probability make it impossible to rule out the possibility of bugs
110 remaining in the program. DO NOT COMPRESS ANY DATA WITH THIS
111 PROGRAM UNLESS YOU ARE PREPARED TO ACCEPT THE POSSIBILITY, HOWEVER
112 SMALL, THAT THE DATA WILL NOT BE RECOVERABLE.
114 That is not to say this program is inherently unreliable. Indeed,
115 I very much hope the opposite is true. bzip2 has been carefully
116 constructed and extensively tested.
121 To the best of my knowledge, bzip2 does not use any patented
122 algorithms. However, I do not have the resources available to
123 carry out a full patent search. Therefore I cannot give any
124 guarantee of the above statement.
129 WHAT'S NEW IN 0.9.0 (as compared to 0.1pl2) ?
131 * Approx 10% faster compression, 30% faster decompression
132 * -t (test mode) is a lot quicker
133 * Can decompress concatenated compressed files
134 * Programming interface, so programs can directly read/write .bz2 files
135 * Less restrictive (BSD-style) licensing
136 * Flag handling more compatible with GNU gzip
137 * Much more documentation, i.e., a proper user manual
138 * Hopefully, improved portability (at least of the library)
140 WHAT'S NEW IN 0.9.5 ?
142 * Compression speed is much less sensitive to the input
143 data than in previous versions. Specifically, the very
144 slow performance caused by repetitive data is fixed.
145 * Many small improvements in file and flag handling.
148 WHAT'S NEW IN 1.0.0 ?
150 See the CHANGES file.
152 WHAT'S NEW IN 1.0.2 ?
154 See the CHANGES file.
157 I hope you find bzip2 useful. Feel free to contact me at
159 if you have any suggestions or queries. Many people mailed me with
160 comments, suggestions and patches after the releases of bzip-0.15,
161 bzip-0.21, and bzip2 versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0 and 1.0.1,
162 and the changes in bzip2 are largely a result of this feedback.
163 I thank you for your comments.
165 At least for the time being, bzip2's "home" is (or can be reached via)
166 http://sources.redhat.com/bzip2.
171 Cambridge, UK (and what a great town this is!)
173 18 July 1996 (version 0.15)
174 25 August 1996 (version 0.21)
175 7 August 1997 (bzip2, version 0.1)
176 29 August 1997 (bzip2, version 0.1pl2)
177 23 August 1998 (bzip2, version 0.9.0)
178 8 June 1999 (bzip2, version 0.9.5)
179 4 Sept 1999 (bzip2, version 0.9.5d)
180 5 May 2000 (bzip2, version 1.0pre8)
181 30 December 2001 (bzip2, version 1.0.2pre1)