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