178556Sobrien 2167974SdelphijThis is the README for bzip2/libzip2. 3167974SdelphijThis version is fully compatible with the previous public releases. 478556Sobrien 5167974Sdelphij------------------------------------------------------------------ 6167974SdelphijThis file is part of bzip2/libbzip2, a program and library for 7167974Sdelphijlossless, block-sorting data compression. 878556Sobrien 9215041Sobrienbzip2/libbzip2 version 1.0.6 of 6 September 2010 10215041SobrienCopyright (C) 1996-2010 Julian Seward <jseward@bzip.org> 11167974Sdelphij 12167974SdelphijPlease read the WARNING, DISCLAIMER and PATENTS sections in this file. 13167974Sdelphij 14167974SdelphijThis program is released under the terms of the license contained 15167974Sdelphijin the file LICENSE. 16167974Sdelphij------------------------------------------------------------------ 17167974Sdelphij 1890067SsobomaxComplete documentation is available in Postscript form (manual.ps), 19146293SobrienPDF (manual.pdf) or html (manual.html). A plain-text version of the 20167974Sdelphijmanual page is available as bzip2.txt. 2178556Sobrien 2278556Sobrien 2378556SobrienHOW TO BUILD -- UNIX 2478556Sobrien 25167974SdelphijType 'make'. This builds the library libbz2.a and then the programs 26167974Sdelphijbzip2 and bzip2recover. Six self-tests are run. If the self-tests 27167974Sdelphijcomplete ok, carry on to installation: 2878556Sobrien 29167974SdelphijTo install in /usr/local/bin, /usr/local/lib, /usr/local/man and 30167974Sdelphij/usr/local/include, type 31167974Sdelphij 3278556Sobrien make install 33167974Sdelphij 34167974SdelphijTo install somewhere else, eg, /xxx/yyy/{bin,lib,man,include}, type 35167974Sdelphij 3678556Sobrien make install PREFIX=/xxx/yyy 37167974Sdelphij 3878556SobrienIf you are (justifiably) paranoid and want to see what 'make install' 3978556Sobrienis going to do, you can first do 40167974Sdelphij 4178556Sobrien make -n install or 4278556Sobrien make -n install PREFIX=/xxx/yyy respectively. 4378556Sobrien 44167974SdelphijThe -n instructs make to show the commands it would execute, but not 45167974Sdelphijactually execute them. 4678556Sobrien 47167974Sdelphij 4878556SobrienHOW TO BUILD -- UNIX, shared library libbz2.so. 4978556Sobrien 5078556SobrienDo 'make -f Makefile-libbz2_so'. This Makefile seems to work for 5190067SsobomaxLinux-ELF (RedHat 7.2 on an x86 box), with gcc. I make no claims 5278556Sobrienthat it works for any other platform, though I suspect it probably 5378556Sobrienwill work for most platforms employing both ELF and gcc. 5478556Sobrien 5590067Ssobomaxbzip2-shared, a client of the shared library, is also built, but not 5690067Ssobomaxself-tested. So I suggest you also build using the normal Makefile, 5790067Ssobomaxsince that conducts a self-test. A second reason to prefer the 5890067Ssobomaxversion statically linked to the library is that, on x86 platforms, 5990067Ssobomaxbuilding shared objects makes a valuable register (%ebx) unavailable 6090067Ssobomaxto gcc, resulting in a slowdown of 10%-20%, at least for bzip2. 6178556Sobrien 6290067SsobomaxImportant note for people upgrading .so's from 0.9.0/0.9.5 to version 6390067Ssobomax1.0.X. All the functions in the library have been renamed, from (eg) 6490067SsobomaxbzCompress to BZ2_bzCompress, to avoid namespace pollution. 6578556SobrienUnfortunately this means that the libbz2.so created by 6690067SsobomaxMakefile-libbz2_so will not work with any program which used an older 67167974Sdelphijversion of the library. I do encourage library clients to make the 68167974Sdelphijeffort to upgrade to use version 1.0, since it is both faster and more 69167974Sdelphijrobust than previous versions. 7078556Sobrien 7178556Sobrien 7278556SobrienHOW TO BUILD -- Windows 95, NT, DOS, Mac, etc. 7378556Sobrien 7478556SobrienIt's difficult for me to support compilation on all these platforms. 7578556SobrienMy approach is to collect binaries for these platforms, and put them 76167974Sdelphijon the master web site (http://www.bzip.org). Look there. However 77167974Sdelphij(FWIW), bzip2-1.0.X is very standard ANSI C and should compile 7890067Ssobomaxunmodified with MS Visual C. If you have difficulties building, you 7990067Ssobomaxmight want to read README.COMPILATION.PROBLEMS. 8078556Sobrien 8190067SsobomaxAt least using MS Visual C++ 6, you can build from the unmodified 8290067Ssobomaxsources by issuing, in a command shell: 83167974Sdelphij 8490067Ssobomax nmake -f makefile.msc 85167974Sdelphij 8690067Ssobomax(you may need to first run the MSVC-provided script VCVARS32.BAT 8790067Ssobomax so as to set up paths to the MSVC tools correctly). 8878556Sobrien 8990067Ssobomax 9078556SobrienVALIDATION 9178556Sobrien 9278556SobrienCorrect operation, in the sense that a compressed file can always be 9378556Sobriendecompressed to reproduce the original, is obviously of paramount 9478556Sobrienimportance. To validate bzip2, I used a modified version of Mark 9578556SobrienNelson's churn program. Churn is an automated test driver which 9678556Sobrienrecursively traverses a directory structure, using bzip2 to compress 9778556Sobrienand then decompress each file it encounters, and checking that the 98146293Sobriendecompressed data is the same as the original. 9978556Sobrien 10078556Sobrien 10178556Sobrien 10278556SobrienPlease read and be aware of the following: 10378556Sobrien 10478556SobrienWARNING: 10578556Sobrien 106167974Sdelphij This program and library (attempts to) compress data by 107167974Sdelphij performing several non-trivial transformations on it. 108167974Sdelphij Unless you are 100% familiar with *all* the algorithms 109167974Sdelphij contained herein, and with the consequences of modifying them, 110167974Sdelphij you should NOT meddle with the compression or decompression 111167974Sdelphij machinery. Incorrect changes can and very likely *will* 112167974Sdelphij lead to disastrous loss of data. 11378556Sobrien 11478556Sobrien 11578556SobrienDISCLAIMER: 11678556Sobrien 11778556Sobrien I TAKE NO RESPONSIBILITY FOR ANY LOSS OF DATA ARISING FROM THE 118167974Sdelphij USE OF THIS PROGRAM/LIBRARY, HOWSOEVER CAUSED. 11978556Sobrien 12078556Sobrien Every compression of a file implies an assumption that the 12178556Sobrien compressed file can be decompressed to reproduce the original. 12278556Sobrien Great efforts in design, coding and testing have been made to 12378556Sobrien ensure that this program works correctly. However, the complexity 12478556Sobrien of the algorithms, and, in particular, the presence of various 12578556Sobrien special cases in the code which occur with very low but non-zero 12678556Sobrien probability make it impossible to rule out the possibility of bugs 12778556Sobrien remaining in the program. DO NOT COMPRESS ANY DATA WITH THIS 12878556Sobrien PROGRAM UNLESS YOU ARE PREPARED TO ACCEPT THE POSSIBILITY, HOWEVER 12978556Sobrien SMALL, THAT THE DATA WILL NOT BE RECOVERABLE. 13078556Sobrien 131167974Sdelphij That is not to say this program is inherently unreliable. 132167974Sdelphij Indeed, I very much hope the opposite is true. bzip2/libbzip2 133167974Sdelphij has been carefully constructed and extensively tested. 13478556Sobrien 13578556Sobrien 13678556SobrienPATENTS: 13778556Sobrien 138167974Sdelphij To the best of my knowledge, bzip2/libbzip2 does not use any 139167974Sdelphij patented algorithms. However, I do not have the resources 140167974Sdelphij to carry out a patent search. Therefore I cannot give any 141167974Sdelphij guarantee of the above statement. 14278556Sobrien 14378556Sobrien 14478556Sobrien 14578556SobrienWHAT'S NEW IN 0.9.0 (as compared to 0.1pl2) ? 14678556Sobrien 14778556Sobrien * Approx 10% faster compression, 30% faster decompression 14878556Sobrien * -t (test mode) is a lot quicker 14978556Sobrien * Can decompress concatenated compressed files 15078556Sobrien * Programming interface, so programs can directly read/write .bz2 files 15178556Sobrien * Less restrictive (BSD-style) licensing 15278556Sobrien * Flag handling more compatible with GNU gzip 15378556Sobrien * Much more documentation, i.e., a proper user manual 15478556Sobrien * Hopefully, improved portability (at least of the library) 15578556Sobrien 15678556SobrienWHAT'S NEW IN 0.9.5 ? 15778556Sobrien 15878556Sobrien * Compression speed is much less sensitive to the input 15978556Sobrien data than in previous versions. Specifically, the very 16078556Sobrien slow performance caused by repetitive data is fixed. 16178556Sobrien * Many small improvements in file and flag handling. 16278556Sobrien * A Y2K statement. 16378556Sobrien 16490067SsobomaxWHAT'S NEW IN 1.0.0 ? 16578556Sobrien 16678556Sobrien See the CHANGES file. 16778556Sobrien 16890067SsobomaxWHAT'S NEW IN 1.0.2 ? 16990067Ssobomax 17090067Ssobomax See the CHANGES file. 17190067Ssobomax 172146293SobrienWHAT'S NEW IN 1.0.3 ? 17390067Ssobomax 174146293Sobrien See the CHANGES file. 175146293Sobrien 176167974SdelphijWHAT'S NEW IN 1.0.4 ? 177146293Sobrien 178167974Sdelphij See the CHANGES file. 179167974Sdelphij 180177420SdelphijWHAT'S NEW IN 1.0.5 ? 181167974Sdelphij 182177420Sdelphij See the CHANGES file. 183177420Sdelphij 184215041SobrienWHAT'S NEW IN 1.0.6 ? 185177420Sdelphij 186215041Sobrien See the CHANGES file. 187215041Sobrien 188215041Sobrien 18978556SobrienI hope you find bzip2 useful. Feel free to contact me at 190146293Sobrien jseward@bzip.org 19178556Sobrienif you have any suggestions or queries. Many people mailed me with 19278556Sobriencomments, suggestions and patches after the releases of bzip-0.15, 193167974Sdelphijbzip-0.21, and bzip2 versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, 194167974Sdelphij1.0.2 and 1.0.3, and the changes in bzip2 are largely a result of this 195167974Sdelphijfeedback. I thank you for your comments. 19678556Sobrien 197167974Sdelphijbzip2's "home" is http://www.bzip.org/ 19878556Sobrien 19978556SobrienJulian Seward 200146293Sobrienjseward@bzip.org 201146293SobrienCambridge, UK. 20290067Ssobomax 20390067Ssobomax18 July 1996 (version 0.15) 20490067Ssobomax25 August 1996 (version 0.21) 20590067Ssobomax 7 August 1997 (bzip2, version 0.1) 20690067Ssobomax29 August 1997 (bzip2, version 0.1pl2) 20790067Ssobomax23 August 1998 (bzip2, version 0.9.0) 20890067Ssobomax 8 June 1999 (bzip2, version 0.9.5) 20990067Ssobomax 4 Sept 1999 (bzip2, version 0.9.5d) 21090067Ssobomax 5 May 2000 (bzip2, version 1.0pre8) 211146293Sobrien30 December 2001 (bzip2, version 1.0.2pre1) 212146293Sobrien15 February 2005 (bzip2, version 1.0.3) 213167974Sdelphij20 December 2006 (bzip2, version 1.0.4) 214177420Sdelphij10 December 2007 (bzip2, version 1.0.5) 215215041Sobrien 6 Sept 2010 (bzip2, version 1.0.6) 216