1*4a711beaSLionel Sambuc 2*4a711beaSLionel SambucThis is the README for bzip2/libzip2. 3*4a711beaSLionel SambucThis version is fully compatible with the previous public releases. 4*4a711beaSLionel Sambuc 5*4a711beaSLionel Sambuc------------------------------------------------------------------ 6*4a711beaSLionel SambucThis file is part of bzip2/libbzip2, a program and library for 7*4a711beaSLionel Sambuclossless, block-sorting data compression. 8*4a711beaSLionel Sambuc 9*4a711beaSLionel Sambucbzip2/libbzip2 version 1.0.6 of 6 September 2010 10*4a711beaSLionel SambucCopyright (C) 1996-2010 Julian Seward <jseward@bzip.org> 11*4a711beaSLionel Sambuc 12*4a711beaSLionel SambucPlease read the WARNING, DISCLAIMER and PATENTS sections in this file. 13*4a711beaSLionel Sambuc 14*4a711beaSLionel SambucThis program is released under the terms of the license contained 15*4a711beaSLionel Sambucin the file LICENSE. 16*4a711beaSLionel Sambuc------------------------------------------------------------------ 17*4a711beaSLionel Sambuc 18*4a711beaSLionel SambucComplete documentation is available in Postscript form (manual.ps), 19*4a711beaSLionel SambucPDF (manual.pdf) or html (manual.html). A plain-text version of the 20*4a711beaSLionel Sambucmanual page is available as bzip2.txt. 21*4a711beaSLionel Sambuc 22*4a711beaSLionel Sambuc 23*4a711beaSLionel SambucHOW TO BUILD -- UNIX 24*4a711beaSLionel Sambuc 25*4a711beaSLionel SambucType 'make'. This builds the library libbz2.a and then the programs 26*4a711beaSLionel Sambucbzip2 and bzip2recover. Six self-tests are run. If the self-tests 27*4a711beaSLionel Sambuccomplete ok, carry on to installation: 28*4a711beaSLionel Sambuc 29*4a711beaSLionel SambucTo install in /usr/local/bin, /usr/local/lib, /usr/local/man and 30*4a711beaSLionel Sambuc/usr/local/include, type 31*4a711beaSLionel Sambuc 32*4a711beaSLionel Sambuc make install 33*4a711beaSLionel Sambuc 34*4a711beaSLionel SambucTo install somewhere else, eg, /xxx/yyy/{bin,lib,man,include}, type 35*4a711beaSLionel Sambuc 36*4a711beaSLionel Sambuc make install PREFIX=/xxx/yyy 37*4a711beaSLionel Sambuc 38*4a711beaSLionel SambucIf you are (justifiably) paranoid and want to see what 'make install' 39*4a711beaSLionel Sambucis going to do, you can first do 40*4a711beaSLionel Sambuc 41*4a711beaSLionel Sambuc make -n install or 42*4a711beaSLionel Sambuc make -n install PREFIX=/xxx/yyy respectively. 43*4a711beaSLionel Sambuc 44*4a711beaSLionel SambucThe -n instructs make to show the commands it would execute, but not 45*4a711beaSLionel Sambucactually execute them. 46*4a711beaSLionel Sambuc 47*4a711beaSLionel Sambuc 48*4a711beaSLionel SambucHOW TO BUILD -- UNIX, shared library libbz2.so. 49*4a711beaSLionel Sambuc 50*4a711beaSLionel SambucDo 'make -f Makefile-libbz2_so'. This Makefile seems to work for 51*4a711beaSLionel SambucLinux-ELF (RedHat 7.2 on an x86 box), with gcc. I make no claims 52*4a711beaSLionel Sambucthat it works for any other platform, though I suspect it probably 53*4a711beaSLionel Sambucwill work for most platforms employing both ELF and gcc. 54*4a711beaSLionel Sambuc 55*4a711beaSLionel Sambucbzip2-shared, a client of the shared library, is also built, but not 56*4a711beaSLionel Sambucself-tested. So I suggest you also build using the normal Makefile, 57*4a711beaSLionel Sambucsince that conducts a self-test. A second reason to prefer the 58*4a711beaSLionel Sambucversion statically linked to the library is that, on x86 platforms, 59*4a711beaSLionel Sambucbuilding shared objects makes a valuable register (%ebx) unavailable 60*4a711beaSLionel Sambucto gcc, resulting in a slowdown of 10%-20%, at least for bzip2. 61*4a711beaSLionel Sambuc 62*4a711beaSLionel SambucImportant note for people upgrading .so's from 0.9.0/0.9.5 to version 63*4a711beaSLionel Sambuc1.0.X. All the functions in the library have been renamed, from (eg) 64*4a711beaSLionel SambucbzCompress to BZ2_bzCompress, to avoid namespace pollution. 65*4a711beaSLionel SambucUnfortunately this means that the libbz2.so created by 66*4a711beaSLionel SambucMakefile-libbz2_so will not work with any program which used an older 67*4a711beaSLionel Sambucversion of the library. I do encourage library clients to make the 68*4a711beaSLionel Sambuceffort to upgrade to use version 1.0, since it is both faster and more 69*4a711beaSLionel Sambucrobust than previous versions. 70*4a711beaSLionel Sambuc 71*4a711beaSLionel Sambuc 72*4a711beaSLionel SambucHOW TO BUILD -- Windows 95, NT, DOS, Mac, etc. 73*4a711beaSLionel Sambuc 74*4a711beaSLionel SambucIt's difficult for me to support compilation on all these platforms. 75*4a711beaSLionel SambucMy approach is to collect binaries for these platforms, and put them 76*4a711beaSLionel Sambucon the master web site (http://www.bzip.org). Look there. However 77*4a711beaSLionel Sambuc(FWIW), bzip2-1.0.X is very standard ANSI C and should compile 78*4a711beaSLionel Sambucunmodified with MS Visual C. If you have difficulties building, you 79*4a711beaSLionel Sambucmight want to read README.COMPILATION.PROBLEMS. 80*4a711beaSLionel Sambuc 81*4a711beaSLionel SambucAt least using MS Visual C++ 6, you can build from the unmodified 82*4a711beaSLionel Sambucsources by issuing, in a command shell: 83*4a711beaSLionel Sambuc 84*4a711beaSLionel Sambuc nmake -f makefile.msc 85*4a711beaSLionel Sambuc 86*4a711beaSLionel Sambuc(you may need to first run the MSVC-provided script VCVARS32.BAT 87*4a711beaSLionel Sambuc so as to set up paths to the MSVC tools correctly). 88*4a711beaSLionel Sambuc 89*4a711beaSLionel Sambuc 90*4a711beaSLionel SambucVALIDATION 91*4a711beaSLionel Sambuc 92*4a711beaSLionel SambucCorrect operation, in the sense that a compressed file can always be 93*4a711beaSLionel Sambucdecompressed to reproduce the original, is obviously of paramount 94*4a711beaSLionel Sambucimportance. To validate bzip2, I used a modified version of Mark 95*4a711beaSLionel SambucNelson's churn program. Churn is an automated test driver which 96*4a711beaSLionel Sambucrecursively traverses a directory structure, using bzip2 to compress 97*4a711beaSLionel Sambucand then decompress each file it encounters, and checking that the 98*4a711beaSLionel Sambucdecompressed data is the same as the original. 99*4a711beaSLionel Sambuc 100*4a711beaSLionel Sambuc 101*4a711beaSLionel Sambuc 102*4a711beaSLionel SambucPlease read and be aware of the following: 103*4a711beaSLionel Sambuc 104*4a711beaSLionel SambucWARNING: 105*4a711beaSLionel Sambuc 106*4a711beaSLionel Sambuc This program and library (attempts to) compress data by 107*4a711beaSLionel Sambuc performing several non-trivial transformations on it. 108*4a711beaSLionel Sambuc Unless you are 100% familiar with *all* the algorithms 109*4a711beaSLionel Sambuc contained herein, and with the consequences of modifying them, 110*4a711beaSLionel Sambuc you should NOT meddle with the compression or decompression 111*4a711beaSLionel Sambuc machinery. Incorrect changes can and very likely *will* 112*4a711beaSLionel Sambuc lead to disastrous loss of data. 113*4a711beaSLionel Sambuc 114*4a711beaSLionel Sambuc 115*4a711beaSLionel SambucDISCLAIMER: 116*4a711beaSLionel Sambuc 117*4a711beaSLionel Sambuc I TAKE NO RESPONSIBILITY FOR ANY LOSS OF DATA ARISING FROM THE 118*4a711beaSLionel Sambuc USE OF THIS PROGRAM/LIBRARY, HOWSOEVER CAUSED. 119*4a711beaSLionel Sambuc 120*4a711beaSLionel Sambuc Every compression of a file implies an assumption that the 121*4a711beaSLionel Sambuc compressed file can be decompressed to reproduce the original. 122*4a711beaSLionel Sambuc Great efforts in design, coding and testing have been made to 123*4a711beaSLionel Sambuc ensure that this program works correctly. However, the complexity 124*4a711beaSLionel Sambuc of the algorithms, and, in particular, the presence of various 125*4a711beaSLionel Sambuc special cases in the code which occur with very low but non-zero 126*4a711beaSLionel Sambuc probability make it impossible to rule out the possibility of bugs 127*4a711beaSLionel Sambuc remaining in the program. DO NOT COMPRESS ANY DATA WITH THIS 128*4a711beaSLionel Sambuc PROGRAM UNLESS YOU ARE PREPARED TO ACCEPT THE POSSIBILITY, HOWEVER 129*4a711beaSLionel Sambuc SMALL, THAT THE DATA WILL NOT BE RECOVERABLE. 130*4a711beaSLionel Sambuc 131*4a711beaSLionel Sambuc That is not to say this program is inherently unreliable. 132*4a711beaSLionel Sambuc Indeed, I very much hope the opposite is true. bzip2/libbzip2 133*4a711beaSLionel Sambuc has been carefully constructed and extensively tested. 134*4a711beaSLionel Sambuc 135*4a711beaSLionel Sambuc 136*4a711beaSLionel SambucPATENTS: 137*4a711beaSLionel Sambuc 138*4a711beaSLionel Sambuc To the best of my knowledge, bzip2/libbzip2 does not use any 139*4a711beaSLionel Sambuc patented algorithms. However, I do not have the resources 140*4a711beaSLionel Sambuc to carry out a patent search. Therefore I cannot give any 141*4a711beaSLionel Sambuc guarantee of the above statement. 142*4a711beaSLionel Sambuc 143*4a711beaSLionel Sambuc 144*4a711beaSLionel Sambuc 145*4a711beaSLionel SambucWHAT'S NEW IN 0.9.0 (as compared to 0.1pl2) ? 146*4a711beaSLionel Sambuc 147*4a711beaSLionel Sambuc * Approx 10% faster compression, 30% faster decompression 148*4a711beaSLionel Sambuc * -t (test mode) is a lot quicker 149*4a711beaSLionel Sambuc * Can decompress concatenated compressed files 150*4a711beaSLionel Sambuc * Programming interface, so programs can directly read/write .bz2 files 151*4a711beaSLionel Sambuc * Less restrictive (BSD-style) licensing 152*4a711beaSLionel Sambuc * Flag handling more compatible with GNU gzip 153*4a711beaSLionel Sambuc * Much more documentation, i.e., a proper user manual 154*4a711beaSLionel Sambuc * Hopefully, improved portability (at least of the library) 155*4a711beaSLionel Sambuc 156*4a711beaSLionel SambucWHAT'S NEW IN 0.9.5 ? 157*4a711beaSLionel Sambuc 158*4a711beaSLionel Sambuc * Compression speed is much less sensitive to the input 159*4a711beaSLionel Sambuc data than in previous versions. Specifically, the very 160*4a711beaSLionel Sambuc slow performance caused by repetitive data is fixed. 161*4a711beaSLionel Sambuc * Many small improvements in file and flag handling. 162*4a711beaSLionel Sambuc * A Y2K statement. 163*4a711beaSLionel Sambuc 164*4a711beaSLionel SambucWHAT'S NEW IN 1.0.0 ? 165*4a711beaSLionel Sambuc 166*4a711beaSLionel Sambuc See the CHANGES file. 167*4a711beaSLionel Sambuc 168*4a711beaSLionel SambucWHAT'S NEW IN 1.0.2 ? 169*4a711beaSLionel Sambuc 170*4a711beaSLionel Sambuc See the CHANGES file. 171*4a711beaSLionel Sambuc 172*4a711beaSLionel SambucWHAT'S NEW IN 1.0.3 ? 173*4a711beaSLionel Sambuc 174*4a711beaSLionel Sambuc See the CHANGES file. 175*4a711beaSLionel Sambuc 176*4a711beaSLionel SambucWHAT'S NEW IN 1.0.4 ? 177*4a711beaSLionel Sambuc 178*4a711beaSLionel Sambuc See the CHANGES file. 179*4a711beaSLionel Sambuc 180*4a711beaSLionel SambucWHAT'S NEW IN 1.0.5 ? 181*4a711beaSLionel Sambuc 182*4a711beaSLionel Sambuc See the CHANGES file. 183*4a711beaSLionel Sambuc 184*4a711beaSLionel SambucWHAT'S NEW IN 1.0.6 ? 185*4a711beaSLionel Sambuc 186*4a711beaSLionel Sambuc See the CHANGES file. 187*4a711beaSLionel Sambuc 188*4a711beaSLionel Sambuc 189*4a711beaSLionel SambucI hope you find bzip2 useful. Feel free to contact me at 190*4a711beaSLionel Sambuc jseward@bzip.org 191*4a711beaSLionel Sambucif you have any suggestions or queries. Many people mailed me with 192*4a711beaSLionel Sambuccomments, suggestions and patches after the releases of bzip-0.15, 193*4a711beaSLionel Sambucbzip-0.21, and bzip2 versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, 194*4a711beaSLionel Sambuc1.0.2 and 1.0.3, and the changes in bzip2 are largely a result of this 195*4a711beaSLionel Sambucfeedback. I thank you for your comments. 196*4a711beaSLionel Sambuc 197*4a711beaSLionel Sambucbzip2's "home" is http://www.bzip.org/ 198*4a711beaSLionel Sambuc 199*4a711beaSLionel SambucJulian Seward 200*4a711beaSLionel Sambucjseward@bzip.org 201*4a711beaSLionel SambucCambridge, UK. 202*4a711beaSLionel Sambuc 203*4a711beaSLionel Sambuc18 July 1996 (version 0.15) 204*4a711beaSLionel Sambuc25 August 1996 (version 0.21) 205*4a711beaSLionel Sambuc 7 August 1997 (bzip2, version 0.1) 206*4a711beaSLionel Sambuc29 August 1997 (bzip2, version 0.1pl2) 207*4a711beaSLionel Sambuc23 August 1998 (bzip2, version 0.9.0) 208*4a711beaSLionel Sambuc 8 June 1999 (bzip2, version 0.9.5) 209*4a711beaSLionel Sambuc 4 Sept 1999 (bzip2, version 0.9.5d) 210*4a711beaSLionel Sambuc 5 May 2000 (bzip2, version 1.0pre8) 211*4a711beaSLionel Sambuc30 December 2001 (bzip2, version 1.0.2pre1) 212*4a711beaSLionel Sambuc15 February 2005 (bzip2, version 1.0.3) 213*4a711beaSLionel Sambuc20 December 2006 (bzip2, version 1.0.4) 214*4a711beaSLionel Sambuc10 December 2007 (bzip2, version 1.0.5) 215*4a711beaSLionel Sambuc 6 Sept 2010 (bzip2, version 1.0.6) 216