xref: /aosp_15_r20/external/bzip2/README (revision 0ac9a9daea5cce2e775d5da949508593e2ee9206)
1*0ac9a9daSXin Li
2*0ac9a9daSXin LiThis is the README for bzip2/libzip2.
3*0ac9a9daSXin LiThis version is fully compatible with the previous public releases.
4*0ac9a9daSXin Li
5*0ac9a9daSXin Li------------------------------------------------------------------
6*0ac9a9daSXin LiThis file is part of bzip2/libbzip2, a program and library for
7*0ac9a9daSXin Lilossless, block-sorting data compression.
8*0ac9a9daSXin Li
9*0ac9a9daSXin Libzip2/libbzip2 version 1.0.8 of 13 July 2019
10*0ac9a9daSXin LiCopyright (C) 1996-2019 Julian Seward <[email protected]>
11*0ac9a9daSXin Li
12*0ac9a9daSXin LiPlease read the WARNING, DISCLAIMER and PATENTS sections in this file.
13*0ac9a9daSXin Li
14*0ac9a9daSXin LiThis program is released under the terms of the license contained
15*0ac9a9daSXin Liin the file LICENSE.
16*0ac9a9daSXin Li------------------------------------------------------------------
17*0ac9a9daSXin Li
18*0ac9a9daSXin LiComplete documentation is available in Postscript form (manual.ps),
19*0ac9a9daSXin LiPDF (manual.pdf) or html (manual.html).  A plain-text version of the
20*0ac9a9daSXin Limanual page is available as bzip2.txt.
21*0ac9a9daSXin Li
22*0ac9a9daSXin Li
23*0ac9a9daSXin LiHOW TO BUILD -- UNIX
24*0ac9a9daSXin Li
25*0ac9a9daSXin LiType 'make'.  This builds the library libbz2.a and then the programs
26*0ac9a9daSXin Libzip2 and bzip2recover.  Six self-tests are run.  If the self-tests
27*0ac9a9daSXin Licomplete ok, carry on to installation:
28*0ac9a9daSXin Li
29*0ac9a9daSXin LiTo install in /usr/local/bin, /usr/local/lib, /usr/local/man and
30*0ac9a9daSXin Li/usr/local/include, type
31*0ac9a9daSXin Li
32*0ac9a9daSXin Li   make install
33*0ac9a9daSXin Li
34*0ac9a9daSXin LiTo install somewhere else, eg, /xxx/yyy/{bin,lib,man,include}, type
35*0ac9a9daSXin Li
36*0ac9a9daSXin Li   make install PREFIX=/xxx/yyy
37*0ac9a9daSXin Li
38*0ac9a9daSXin LiIf you are (justifiably) paranoid and want to see what 'make install'
39*0ac9a9daSXin Liis going to do, you can first do
40*0ac9a9daSXin Li
41*0ac9a9daSXin Li   make -n install                      or
42*0ac9a9daSXin Li   make -n install PREFIX=/xxx/yyy      respectively.
43*0ac9a9daSXin Li
44*0ac9a9daSXin LiThe -n instructs make to show the commands it would execute, but not
45*0ac9a9daSXin Liactually execute them.
46*0ac9a9daSXin Li
47*0ac9a9daSXin Li
48*0ac9a9daSXin LiHOW TO BUILD -- UNIX, shared library libbz2.so.
49*0ac9a9daSXin Li
50*0ac9a9daSXin LiDo 'make -f Makefile-libbz2_so'.  This Makefile seems to work for
51*0ac9a9daSXin LiLinux-ELF (RedHat 7.2 on an x86 box), with gcc.  I make no claims
52*0ac9a9daSXin Lithat it works for any other platform, though I suspect it probably
53*0ac9a9daSXin Liwill work for most platforms employing both ELF and gcc.
54*0ac9a9daSXin Li
55*0ac9a9daSXin Libzip2-shared, a client of the shared library, is also built, but not
56*0ac9a9daSXin Liself-tested.  So I suggest you also build using the normal Makefile,
57*0ac9a9daSXin Lisince that conducts a self-test.  A second reason to prefer the
58*0ac9a9daSXin Liversion statically linked to the library is that, on x86 platforms,
59*0ac9a9daSXin Libuilding shared objects makes a valuable register (%ebx) unavailable
60*0ac9a9daSXin Lito gcc, resulting in a slowdown of 10%-20%, at least for bzip2.
61*0ac9a9daSXin Li
62*0ac9a9daSXin LiImportant note for people upgrading .so's from 0.9.0/0.9.5 to version
63*0ac9a9daSXin Li1.0.X.  All the functions in the library have been renamed, from (eg)
64*0ac9a9daSXin LibzCompress to BZ2_bzCompress, to avoid namespace pollution.
65*0ac9a9daSXin LiUnfortunately this means that the libbz2.so created by
66*0ac9a9daSXin LiMakefile-libbz2_so will not work with any program which used an older
67*0ac9a9daSXin Liversion of the library.  I do encourage library clients to make the
68*0ac9a9daSXin Lieffort to upgrade to use version 1.0, since it is both faster and more
69*0ac9a9daSXin Lirobust than previous versions.
70*0ac9a9daSXin Li
71*0ac9a9daSXin Li
72*0ac9a9daSXin LiHOW TO BUILD -- Windows 95, NT, DOS, Mac, etc.
73*0ac9a9daSXin Li
74*0ac9a9daSXin LiIt's difficult for me to support compilation on all these platforms.
75*0ac9a9daSXin LiMy approach is to collect binaries for these platforms, and put them
76*0ac9a9daSXin Lion the master web site (https://sourceware.org/bzip2/).  Look there.  However
77*0ac9a9daSXin Li(FWIW), bzip2-1.0.X is very standard ANSI C and should compile
78*0ac9a9daSXin Liunmodified with MS Visual C.  If you have difficulties building, you
79*0ac9a9daSXin Limight want to read README.COMPILATION.PROBLEMS.
80*0ac9a9daSXin Li
81*0ac9a9daSXin LiAt least using MS Visual C++ 6, you can build from the unmodified
82*0ac9a9daSXin Lisources by issuing, in a command shell:
83*0ac9a9daSXin Li
84*0ac9a9daSXin Li   nmake -f makefile.msc
85*0ac9a9daSXin Li
86*0ac9a9daSXin Li(you may need to first run the MSVC-provided script VCVARS32.BAT
87*0ac9a9daSXin Li so as to set up paths to the MSVC tools correctly).
88*0ac9a9daSXin Li
89*0ac9a9daSXin Li
90*0ac9a9daSXin LiVALIDATION
91*0ac9a9daSXin Li
92*0ac9a9daSXin LiCorrect operation, in the sense that a compressed file can always be
93*0ac9a9daSXin Lidecompressed to reproduce the original, is obviously of paramount
94*0ac9a9daSXin Liimportance.  To validate bzip2, I used a modified version of Mark
95*0ac9a9daSXin LiNelson's churn program.  Churn is an automated test driver which
96*0ac9a9daSXin Lirecursively traverses a directory structure, using bzip2 to compress
97*0ac9a9daSXin Liand then decompress each file it encounters, and checking that the
98*0ac9a9daSXin Lidecompressed data is the same as the original.
99*0ac9a9daSXin Li
100*0ac9a9daSXin Li
101*0ac9a9daSXin Li
102*0ac9a9daSXin LiPlease read and be aware of the following:
103*0ac9a9daSXin Li
104*0ac9a9daSXin LiWARNING:
105*0ac9a9daSXin Li
106*0ac9a9daSXin Li   This program and library (attempts to) compress data by
107*0ac9a9daSXin Li   performing several non-trivial transformations on it.
108*0ac9a9daSXin Li   Unless you are 100% familiar with *all* the algorithms
109*0ac9a9daSXin Li   contained herein, and with the consequences of modifying them,
110*0ac9a9daSXin Li   you should NOT meddle with the compression or decompression
111*0ac9a9daSXin Li   machinery.  Incorrect changes can and very likely *will*
112*0ac9a9daSXin Li   lead to disastrous loss of data.
113*0ac9a9daSXin Li
114*0ac9a9daSXin Li
115*0ac9a9daSXin LiDISCLAIMER:
116*0ac9a9daSXin Li
117*0ac9a9daSXin Li   I TAKE NO RESPONSIBILITY FOR ANY LOSS OF DATA ARISING FROM THE
118*0ac9a9daSXin Li   USE OF THIS PROGRAM/LIBRARY, HOWSOEVER CAUSED.
119*0ac9a9daSXin Li
120*0ac9a9daSXin Li   Every compression of a file implies an assumption that the
121*0ac9a9daSXin Li   compressed file can be decompressed to reproduce the original.
122*0ac9a9daSXin Li   Great efforts in design, coding and testing have been made to
123*0ac9a9daSXin Li   ensure that this program works correctly.  However, the complexity
124*0ac9a9daSXin Li   of the algorithms, and, in particular, the presence of various
125*0ac9a9daSXin Li   special cases in the code which occur with very low but non-zero
126*0ac9a9daSXin Li   probability make it impossible to rule out the possibility of bugs
127*0ac9a9daSXin Li   remaining in the program.  DO NOT COMPRESS ANY DATA WITH THIS
128*0ac9a9daSXin Li   PROGRAM UNLESS YOU ARE PREPARED TO ACCEPT THE POSSIBILITY, HOWEVER
129*0ac9a9daSXin Li   SMALL, THAT THE DATA WILL NOT BE RECOVERABLE.
130*0ac9a9daSXin Li
131*0ac9a9daSXin Li   That is not to say this program is inherently unreliable.
132*0ac9a9daSXin Li   Indeed, I very much hope the opposite is true.  bzip2/libbzip2
133*0ac9a9daSXin Li   has been carefully constructed and extensively tested.
134*0ac9a9daSXin Li
135*0ac9a9daSXin Li
136*0ac9a9daSXin LiPATENTS:
137*0ac9a9daSXin Li
138*0ac9a9daSXin Li   To the best of my knowledge, bzip2/libbzip2 does not use any
139*0ac9a9daSXin Li   patented algorithms.  However, I do not have the resources
140*0ac9a9daSXin Li   to carry out a patent search.  Therefore I cannot give any
141*0ac9a9daSXin Li   guarantee of the above statement.
142*0ac9a9daSXin Li
143*0ac9a9daSXin Li
144*0ac9a9daSXin Li
145*0ac9a9daSXin LiWHAT'S NEW IN 0.9.0 (as compared to 0.1pl2) ?
146*0ac9a9daSXin Li
147*0ac9a9daSXin Li   * Approx 10% faster compression, 30% faster decompression
148*0ac9a9daSXin Li   * -t (test mode) is a lot quicker
149*0ac9a9daSXin Li   * Can decompress concatenated compressed files
150*0ac9a9daSXin Li   * Programming interface, so programs can directly read/write .bz2 files
151*0ac9a9daSXin Li   * Less restrictive (BSD-style) licensing
152*0ac9a9daSXin Li   * Flag handling more compatible with GNU gzip
153*0ac9a9daSXin Li   * Much more documentation, i.e., a proper user manual
154*0ac9a9daSXin Li   * Hopefully, improved portability (at least of the library)
155*0ac9a9daSXin Li
156*0ac9a9daSXin LiWHAT'S NEW IN 0.9.5 ?
157*0ac9a9daSXin Li
158*0ac9a9daSXin Li   * Compression speed is much less sensitive to the input
159*0ac9a9daSXin Li     data than in previous versions.  Specifically, the very
160*0ac9a9daSXin Li     slow performance caused by repetitive data is fixed.
161*0ac9a9daSXin Li   * Many small improvements in file and flag handling.
162*0ac9a9daSXin Li   * A Y2K statement.
163*0ac9a9daSXin Li
164*0ac9a9daSXin LiWHAT'S NEW IN 1.0.x ?
165*0ac9a9daSXin Li
166*0ac9a9daSXin Li   See the CHANGES file.
167*0ac9a9daSXin Li
168*0ac9a9daSXin LiI hope you find bzip2 useful.  Feel free to contact the developers at
169*0ac9a9daSXin Li   [email protected]
170*0ac9a9daSXin Liif you have any suggestions or queries.  Many people mailed me with
171*0ac9a9daSXin Licomments, suggestions and patches after the releases of bzip-0.15,
172*0ac9a9daSXin Libzip-0.21, and bzip2 versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1,
173*0ac9a9daSXin Li1.0.2 and 1.0.3, and the changes in bzip2 are largely a result of this
174*0ac9a9daSXin Lifeedback.  I thank you for your comments.
175*0ac9a9daSXin Li
176*0ac9a9daSXin Libzip2's "home" is https://sourceware.org/bzip2/
177*0ac9a9daSXin Li
178*0ac9a9daSXin LiJulian Seward
179*0ac9a9daSXin Li[email protected]
180*0ac9a9daSXin LiCambridge, UK.
181*0ac9a9daSXin Li
182*0ac9a9daSXin Li18     July 1996 (version 0.15)
183*0ac9a9daSXin Li25   August 1996 (version 0.21)
184*0ac9a9daSXin Li 7   August 1997 (bzip2, version 0.1)
185*0ac9a9daSXin Li29   August 1997 (bzip2, version 0.1pl2)
186*0ac9a9daSXin Li23   August 1998 (bzip2, version 0.9.0)
187*0ac9a9daSXin Li 8     June 1999 (bzip2, version 0.9.5)
188*0ac9a9daSXin Li 4     Sept 1999 (bzip2, version 0.9.5d)
189*0ac9a9daSXin Li 5      May 2000 (bzip2, version 1.0pre8)
190*0ac9a9daSXin Li30 December 2001 (bzip2, version 1.0.2pre1)
191*0ac9a9daSXin Li15 February 2005 (bzip2, version 1.0.3)
192*0ac9a9daSXin Li20 December 2006 (bzip2, version 1.0.4)
193*0ac9a9daSXin Li10 December 2007 (bzip2, version 1.0.5)
194*0ac9a9daSXin Li 6     Sept 2010 (bzip2, version 1.0.6)
195*0ac9a9daSXin Li27     June 2019 (bzip2, version 1.0.7)
196*0ac9a9daSXin Li13     July 2019 (bzip2, version 1.0.8)
197