README

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