1
2This is the README for bzip2, a block-sorting file compressor, version
31.0.3. This version is fully compatible with the previous public
4releases, versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1 and 1.0.2.
5
6bzip2-1.0.3 is distributed under a BSD-style license. For details,
7see the file LICENSE.
8
9Complete documentation is available in Postscript form (manual.ps),
10PDF (manual.pdf) or html (manual.html). A plain-text version of the
11manual page is available as bzip2.txt. A statement about Y2K issues
12is now included in the file Y2K_INFO.
13
14
15HOW TO BUILD -- UNIX
16
17Type `make'. This builds the library libbz2.a and then the
18programs bzip2 and bzip2recover. Six self-tests are run.
19If the self-tests complete ok, carry on to installation:
20
21To install in /usr/bin, /usr/lib, /usr/man and /usr/include, type
22 make install
23To install somewhere else, eg, /xxx/yyy/{bin,lib,man,include}, type
24 make install PREFIX=/xxx/yyy
25If you are (justifiably) paranoid and want to see what 'make install'
26is going to do, you can first do
27 make -n install or
28 make -n install PREFIX=/xxx/yyy respectively.
29The -n instructs make to show the commands it would execute, but
30not actually execute them.
31
32
33HOW TO BUILD -- UNIX, shared library libbz2.so.
34
35Do 'make -f Makefile-libbz2_so'. This Makefile seems to work for
36Linux-ELF (RedHat 7.2 on an x86 box), with gcc. I make no claims
37that it works for any other platform, though I suspect it probably
38will work for most platforms employing both ELF and gcc.
39
40bzip2-shared, a client of the shared library, is also built, but not
41self-tested. So I suggest you also build using the normal Makefile,
42since that conducts a self-test. A second reason to prefer the
43version statically linked to the library is that, on x86 platforms,
44building shared objects makes a valuable register (%ebx) unavailable
45to gcc, resulting in a slowdown of 10%-20%, at least for bzip2.
46
47Important note for people upgrading .so's from 0.9.0/0.9.5 to version
481.0.X. All the functions in the library have been renamed, from (eg)
49bzCompress to BZ2_bzCompress, to avoid namespace pollution.
50Unfortunately this means that the libbz2.so created by
51Makefile-libbz2_so will not work with any program which used an older
52version of the library. Sorry. I do encourage library clients to
53make the effort to upgrade to use version 1.0, since it is both faster
54and more robust than previous versions.
55
56
57HOW TO BUILD -- Windows 95, NT, DOS, Mac, etc.
58
59It's difficult for me to support compilation on all these platforms.
60My approach is to collect binaries for these platforms, and put them
61on the master web page (http://sources.redhat.com/bzip2). Look there.
62However (FWIW), bzip2-1.0.X is very standard ANSI C and should compile
63unmodified with MS Visual C. If you have difficulties building, you
64might want to read README.COMPILATION.PROBLEMS.
65
66At least using MS Visual C++ 6, you can build from the unmodified
67sources by issuing, in a command shell:
68 nmake -f makefile.msc
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).
71
72
73VALIDATION
74
75Correct operation, in the sense that a compressed file can always be
76decompressed to reproduce the original, is obviously of paramount
77importance. To validate bzip2, I used a modified version of Mark
78Nelson's churn program. Churn is an automated test driver which
79recursively traverses a directory structure, using bzip2 to compress
80and then decompress each file it encounters, and checking that the
81decompressed data is the same as the original.
82
83
84
85Please read and be aware of the following:
86
87WARNING:
88
89 This program (attempts to) compress data by performing several
90 non-trivial transformations on it. Unless you are 100% familiar
91 with *all* the algorithms contained herein, and with the
92 consequences of modifying them, you should NOT meddle with the
93 compression or decompression machinery. Incorrect changes can and
94 very likely *will* lead to disastrous loss of data.
95
96
97DISCLAIMER:
98
99 I TAKE NO RESPONSIBILITY FOR ANY LOSS OF DATA ARISING FROM THE
100 USE OF THIS PROGRAM, HOWSOEVER CAUSED.
101
102 Every compression of a file implies an assumption that the
103 compressed file can be decompressed to reproduce the original.
104 Great efforts in design, coding and testing have been made to
105 ensure that this program works correctly. However, the complexity
106 of the algorithms, and, in particular, the presence of various
107 special cases in the code which occur with very low but non-zero
108 probability make it impossible to rule out the possibility of bugs
109 remaining in the program. DO NOT COMPRESS ANY DATA WITH THIS
110 PROGRAM UNLESS YOU ARE PREPARED TO ACCEPT THE POSSIBILITY, HOWEVER
111 SMALL, THAT THE DATA WILL NOT BE RECOVERABLE.
112
113 That is not to say this program is inherently unreliable. Indeed,
114 I very much hope the opposite is true. bzip2 has been carefully
115 constructed and extensively tested.
116
117
118PATENTS:
119
120 To the best of my knowledge, bzip2 does not use any patented
121 algorithms. However, I do not have the resources to carry out
122 a patent search. Therefore I cannot give any guarantee of the
123 above statement.
124
125End of legalities.
126
127
128WHAT'S NEW IN 0.9.0 (as compared to 0.1pl2) ?
129
130 * Approx 10% faster compression, 30% faster decompression
131 * -t (test mode) is a lot quicker
132 * Can decompress concatenated compressed files
133 * Programming interface, so programs can directly read/write .bz2 files
134 * Less restrictive (BSD-style) licensing
135 * Flag handling more compatible with GNU gzip
136 * Much more documentation, i.e., a proper user manual
137 * Hopefully, improved portability (at least of the library)
138
139WHAT'S NEW IN 0.9.5 ?
140
141 * Compression speed is much less sensitive to the input
142 data than in previous versions. Specifically, the very
143 slow performance caused by repetitive data is fixed.
144 * Many small improvements in file and flag handling.
145 * A Y2K statement.
146
147WHAT'S NEW IN 1.0.0 ?
148
149 See the CHANGES file.
150
151WHAT'S NEW IN 1.0.2 ?
152
153 See the CHANGES file.
154
155WHAT'S NEW IN 1.0.3 ?
156
157 See the CHANGES file.
158
159
160I hope you find bzip2 useful. Feel free to contact me at
161 jseward@bzip.org
162if you have any suggestions or queries. Many people mailed me with
163comments, suggestions and patches after the releases of bzip-0.15,
164bzip-0.21, and bzip2 versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1 and
1651.0.2, and the changes in bzip2 are largely a result of this feedback.
166I thank you for your comments.
167
168At least for the time being, bzip2's "home" is (or can be reached via)
169http://www.bzip.org
170
171Julian Seward
172jseward@bzip.org
173
174Cambridge, UK.
175
17618 July 1996 (version 0.15)
17725 August 1996 (version 0.21)
178 7 August 1997 (bzip2, version 0.1)
17929 August 1997 (bzip2, version 0.1pl2)
18023 August 1998 (bzip2, version 0.9.0)
181 8 June 1999 (bzip2, version 0.9.5)
182 4 Sept 1999 (bzip2, version 0.9.5d)
183 5 May 2000 (bzip2, version 1.0pre8)
18430 December 2001 (bzip2, version 1.0.2pre1)
18515 February 2005 (bzip2, version 1.0.3)
186
1
2bzip2-1.0.3 should compile without problems on the vast majority of
3platforms. Using the supplied Makefile, I've built and tested it
4myself for x86-linux and x86_64-linux. With makefile.msc, Visual C++
56.0 and nmake, you can build a native Win32 version too. Large file
6support seems to work correctly on at least alpha-tru64unix and
7x86-cygwin32 (on Windows 2000).
8
9When I say "large file" I mean a file of size 2,147,483,648 (2^31)
10bytes or above. Many older OSs can't handle files above this size,
11but many newer ones can. Large files are pretty huge -- most files
12you'll encounter are not Large Files.
13
14Earlier versions of bzip2 (0.1, 0.9.0, 0.9.5) compiled on a wide
15variety of platforms without difficulty, and I hope this version will
16continue in that tradition. However, in order to support large files,
17I've had to include the define -D_FILE_OFFSET_BITS=64 in the Makefile.
18This can cause problems.
19
20The technique of adding -D_FILE_OFFSET_BITS=64 to get large file
21support is, as far as I know, the Recommended Way to get correct large
22file support. For more details, see the Large File Support
23Specification, published by the Large File Summit, at
24 http://ftp.sas.com/standards/large.file
25
26As a general comment, if you get compilation errors which you think
27are related to large file support, try removing the above define from
28the Makefile, ie, delete the line
29 BIGFILES=-D_FILE_OFFSET_BITS=64
30from the Makefile, and do 'make clean ; make'. This will give you a
31version of bzip2 without large file support, which, for most
32applications, is probably not a problem.
33
34Alternatively, try some of the platform-specific hints listed below.
35
36You can use the spewG.c program to generate huge files to test bzip2's
37large file support, if you are feeling paranoid. Be aware though that
38any compilation problems which affect bzip2 will also affect spewG.c,
39alas.
40