Chris@4: Chris@4: This is the README for bzip2/libzip2. Chris@4: This version is fully compatible with the previous public releases. Chris@4: Chris@4: ------------------------------------------------------------------ Chris@4: This file is part of bzip2/libbzip2, a program and library for Chris@4: lossless, block-sorting data compression. Chris@4: Chris@4: bzip2/libbzip2 version 1.0.6 of 6 September 2010 Chris@4: Copyright (C) 1996-2010 Julian Seward Chris@4: Chris@4: Please read the WARNING, DISCLAIMER and PATENTS sections in this file. Chris@4: Chris@4: This program is released under the terms of the license contained Chris@4: in the file LICENSE. Chris@4: ------------------------------------------------------------------ Chris@4: Chris@4: Complete documentation is available in Postscript form (manual.ps), Chris@4: PDF (manual.pdf) or html (manual.html). A plain-text version of the Chris@4: manual page is available as bzip2.txt. Chris@4: Chris@4: Chris@4: HOW TO BUILD -- UNIX Chris@4: Chris@4: Type 'make'. This builds the library libbz2.a and then the programs Chris@4: bzip2 and bzip2recover. Six self-tests are run. If the self-tests Chris@4: complete ok, carry on to installation: Chris@4: Chris@4: To install in /usr/local/bin, /usr/local/lib, /usr/local/man and Chris@4: /usr/local/include, type Chris@4: Chris@4: make install Chris@4: Chris@4: To install somewhere else, eg, /xxx/yyy/{bin,lib,man,include}, type Chris@4: Chris@4: make install PREFIX=/xxx/yyy Chris@4: Chris@4: If you are (justifiably) paranoid and want to see what 'make install' Chris@4: is going to do, you can first do Chris@4: Chris@4: make -n install or Chris@4: make -n install PREFIX=/xxx/yyy respectively. Chris@4: Chris@4: The -n instructs make to show the commands it would execute, but not Chris@4: actually execute them. Chris@4: Chris@4: Chris@4: HOW TO BUILD -- UNIX, shared library libbz2.so. Chris@4: Chris@4: Do 'make -f Makefile-libbz2_so'. This Makefile seems to work for Chris@4: Linux-ELF (RedHat 7.2 on an x86 box), with gcc. I make no claims Chris@4: that it works for any other platform, though I suspect it probably Chris@4: will work for most platforms employing both ELF and gcc. Chris@4: Chris@4: bzip2-shared, a client of the shared library, is also built, but not Chris@4: self-tested. So I suggest you also build using the normal Makefile, Chris@4: since that conducts a self-test. A second reason to prefer the Chris@4: version statically linked to the library is that, on x86 platforms, Chris@4: building shared objects makes a valuable register (%ebx) unavailable Chris@4: to gcc, resulting in a slowdown of 10%-20%, at least for bzip2. Chris@4: Chris@4: Important note for people upgrading .so's from 0.9.0/0.9.5 to version Chris@4: 1.0.X. All the functions in the library have been renamed, from (eg) Chris@4: bzCompress to BZ2_bzCompress, to avoid namespace pollution. Chris@4: Unfortunately this means that the libbz2.so created by Chris@4: Makefile-libbz2_so will not work with any program which used an older Chris@4: version of the library. I do encourage library clients to make the Chris@4: effort to upgrade to use version 1.0, since it is both faster and more Chris@4: robust than previous versions. Chris@4: Chris@4: Chris@4: HOW TO BUILD -- Windows 95, NT, DOS, Mac, etc. Chris@4: Chris@4: It's difficult for me to support compilation on all these platforms. Chris@4: My approach is to collect binaries for these platforms, and put them Chris@4: on the master web site (http://www.bzip.org). Look there. However Chris@4: (FWIW), bzip2-1.0.X is very standard ANSI C and should compile Chris@4: unmodified with MS Visual C. If you have difficulties building, you Chris@4: might want to read README.COMPILATION.PROBLEMS. Chris@4: Chris@4: At least using MS Visual C++ 6, you can build from the unmodified Chris@4: sources by issuing, in a command shell: Chris@4: Chris@4: nmake -f makefile.msc Chris@4: Chris@4: (you may need to first run the MSVC-provided script VCVARS32.BAT Chris@4: so as to set up paths to the MSVC tools correctly). Chris@4: Chris@4: Chris@4: VALIDATION Chris@4: Chris@4: Correct operation, in the sense that a compressed file can always be Chris@4: decompressed to reproduce the original, is obviously of paramount Chris@4: importance. To validate bzip2, I used a modified version of Mark Chris@4: Nelson's churn program. Churn is an automated test driver which Chris@4: recursively traverses a directory structure, using bzip2 to compress Chris@4: and then decompress each file it encounters, and checking that the Chris@4: decompressed data is the same as the original. Chris@4: Chris@4: Chris@4: Chris@4: Please read and be aware of the following: Chris@4: Chris@4: WARNING: Chris@4: Chris@4: This program and library (attempts to) compress data by Chris@4: performing several non-trivial transformations on it. Chris@4: Unless you are 100% familiar with *all* the algorithms Chris@4: contained herein, and with the consequences of modifying them, Chris@4: you should NOT meddle with the compression or decompression Chris@4: machinery. Incorrect changes can and very likely *will* Chris@4: lead to disastrous loss of data. Chris@4: Chris@4: Chris@4: DISCLAIMER: Chris@4: Chris@4: I TAKE NO RESPONSIBILITY FOR ANY LOSS OF DATA ARISING FROM THE Chris@4: USE OF THIS PROGRAM/LIBRARY, HOWSOEVER CAUSED. Chris@4: Chris@4: Every compression of a file implies an assumption that the Chris@4: compressed file can be decompressed to reproduce the original. Chris@4: Great efforts in design, coding and testing have been made to Chris@4: ensure that this program works correctly. However, the complexity Chris@4: of the algorithms, and, in particular, the presence of various Chris@4: special cases in the code which occur with very low but non-zero Chris@4: probability make it impossible to rule out the possibility of bugs Chris@4: remaining in the program. DO NOT COMPRESS ANY DATA WITH THIS Chris@4: PROGRAM UNLESS YOU ARE PREPARED TO ACCEPT THE POSSIBILITY, HOWEVER Chris@4: SMALL, THAT THE DATA WILL NOT BE RECOVERABLE. Chris@4: Chris@4: That is not to say this program is inherently unreliable. Chris@4: Indeed, I very much hope the opposite is true. bzip2/libbzip2 Chris@4: has been carefully constructed and extensively tested. Chris@4: Chris@4: Chris@4: PATENTS: Chris@4: Chris@4: To the best of my knowledge, bzip2/libbzip2 does not use any Chris@4: patented algorithms. However, I do not have the resources Chris@4: to carry out a patent search. Therefore I cannot give any Chris@4: guarantee of the above statement. Chris@4: Chris@4: Chris@4: Chris@4: WHAT'S NEW IN 0.9.0 (as compared to 0.1pl2) ? Chris@4: Chris@4: * Approx 10% faster compression, 30% faster decompression Chris@4: * -t (test mode) is a lot quicker Chris@4: * Can decompress concatenated compressed files Chris@4: * Programming interface, so programs can directly read/write .bz2 files Chris@4: * Less restrictive (BSD-style) licensing Chris@4: * Flag handling more compatible with GNU gzip Chris@4: * Much more documentation, i.e., a proper user manual Chris@4: * Hopefully, improved portability (at least of the library) Chris@4: Chris@4: WHAT'S NEW IN 0.9.5 ? Chris@4: Chris@4: * Compression speed is much less sensitive to the input Chris@4: data than in previous versions. Specifically, the very Chris@4: slow performance caused by repetitive data is fixed. Chris@4: * Many small improvements in file and flag handling. Chris@4: * A Y2K statement. Chris@4: Chris@4: WHAT'S NEW IN 1.0.0 ? Chris@4: Chris@4: See the CHANGES file. Chris@4: Chris@4: WHAT'S NEW IN 1.0.2 ? Chris@4: Chris@4: See the CHANGES file. Chris@4: Chris@4: WHAT'S NEW IN 1.0.3 ? Chris@4: Chris@4: See the CHANGES file. Chris@4: Chris@4: WHAT'S NEW IN 1.0.4 ? Chris@4: Chris@4: See the CHANGES file. Chris@4: Chris@4: WHAT'S NEW IN 1.0.5 ? Chris@4: Chris@4: See the CHANGES file. Chris@4: Chris@4: WHAT'S NEW IN 1.0.6 ? Chris@4: Chris@4: See the CHANGES file. Chris@4: Chris@4: Chris@4: I hope you find bzip2 useful. Feel free to contact me at Chris@4: jseward@bzip.org Chris@4: if you have any suggestions or queries. Many people mailed me with Chris@4: comments, suggestions and patches after the releases of bzip-0.15, Chris@4: bzip-0.21, and bzip2 versions 0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, Chris@4: 1.0.2 and 1.0.3, and the changes in bzip2 are largely a result of this Chris@4: feedback. I thank you for your comments. Chris@4: Chris@4: bzip2's "home" is http://www.bzip.org/ Chris@4: Chris@4: Julian Seward Chris@4: jseward@bzip.org Chris@4: Cambridge, UK. Chris@4: Chris@4: 18 July 1996 (version 0.15) Chris@4: 25 August 1996 (version 0.21) Chris@4: 7 August 1997 (bzip2, version 0.1) Chris@4: 29 August 1997 (bzip2, version 0.1pl2) Chris@4: 23 August 1998 (bzip2, version 0.9.0) Chris@4: 8 June 1999 (bzip2, version 0.9.5) Chris@4: 4 Sept 1999 (bzip2, version 0.9.5d) Chris@4: 5 May 2000 (bzip2, version 1.0pre8) Chris@4: 30 December 2001 (bzip2, version 1.0.2pre1) Chris@4: 15 February 2005 (bzip2, version 1.0.3) Chris@4: 20 December 2006 (bzip2, version 1.0.4) Chris@4: 10 December 2007 (bzip2, version 1.0.5) Chris@4: 6 Sept 2010 (bzip2, version 1.0.6)