home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-Update.iso / NEXTSTEP / unix / archiver / bzip2-0.1pl2.README < prev    next >
Encoding:
Text File  |  1998-02-21  |  10.1 KB  |  263 lines
  1. ###
  2. ### This is bzip2-0.1pl2 compiled quad-fat for NEXTSTEP 3.x
  3. ### by Gregor Hoffleit <flight@mathi.uni-heidelberg.de>.
  4. ###
  5. ### The binary was compiled using the patch included in
  6. ### /usr/local/src/bzip2-0.1pl2-nx1.
  7. ###
  8. ### Below follows the original README for bzip2-0.1pl2.
  9. ###
  10.  
  11. GREETINGS!
  12.  
  13.    This is the README for bzip2, my block-sorting file compressor,
  14.    version 0.1.  
  15.  
  16.    bzip2 is distributed under the GNU General Public License version 2;
  17.    for details, see the file LICENSE.  Pointers to the algorithms used
  18.    are in ALGORITHMS.  Instructions for use are in bzip2.1.preformatted.
  19.  
  20.    Please read all of this file carefully.
  21.  
  22.  
  23.  
  24. HOW TO BUILD
  25.  
  26.    -- for UNIX:
  27.  
  28.         Type `make'.     (tough, huh? :-)
  29.  
  30.         This creates binaries "bzip2", and "bunzip2",
  31.         which is a symbolic link to "bzip2".
  32.  
  33.         It also runs four compress-decompress tests to make sure
  34.         things are working properly.  If all goes well, you should be up &
  35.         running.  Please be sure to read the output from `make'
  36.         just to be sure that the tests went ok.
  37.  
  38.         To install bzip2 properly:
  39.  
  40.            -- Copy the binary "bzip2" to a publically visible place,
  41.               possibly /usr/bin, /usr/common/bin or /usr/local/bin.
  42.  
  43.            -- In that directory, make "bunzip2" be a symbolic link
  44.               to "bzip2".
  45.  
  46.            -- Copy the manual page, bzip2.1, to the relevant place.
  47.               Probably the right place is /usr/man/man1/.
  48.    
  49.    -- for Windows 95 and NT: 
  50.  
  51.         For a start, do you *really* want to recompile bzip2?  
  52.         The standard distribution includes a pre-compiled version
  53.         for Windows 95 and NT, `bzip2.exe'.
  54.  
  55.         This executable was created with Jacob Navia's excellent
  56.         port to Win32 of Chris Fraser & David Hanson's excellent
  57.         ANSI C compiler, "lcc".  You can get to it at the pages
  58.         of the CS department of Princeton University, 
  59.         www.cs.princeton.edu.  
  60.         I have not tried to compile this version of bzip2 with
  61.         a commercial C compiler such as MS Visual C, as I don't
  62.         have one available.
  63.  
  64.         Note that lcc is designed primarily to be portable and
  65.         fast.  Code quality is a secondary aim, so bzip2.exe
  66.         runs perhaps 40% slower than it could if compiled with
  67.         a good optimising compiler.
  68.  
  69.         I compiled a previous version of bzip (0.21) with Borland
  70.         C 5.0, which worked fine, and with MS VC++ 2.0, which
  71.         didn't.  Here is an comment from the README for bzip-0.21.
  72.  
  73.            MS VC++ 2.0's optimising compiler has a bug which, at 
  74.            maximum optimisation, gives an executable which produces 
  75.            garbage compressed files.  Proceed with caution. 
  76.            I do not know whether or not this happens with later 
  77.            versions of VC++.
  78.  
  79.            Edit the defines starting at line 86 of bzip.c to 
  80.            select your platform/compiler combination, and then compile.
  81.            Then check that the resulting executable (assumed to be 
  82.            called bzip.exe) works correctly, using the SELFTEST.BAT file.  
  83.            Bearing in mind the previous paragraph, the self-test is
  84.            important.
  85.  
  86.         Note that the defines which bzip-0.21 had, to support 
  87.         compilation with VC 2.0 and BC 5.0, are gone.  Windows
  88.         is not my preferred operating system, and I am, for the
  89.         moment, content with the modestly fast executable created
  90.         by lcc-win32.
  91.  
  92.    A manual page is supplied, unformatted (bzip2.1),
  93.    preformatted (bzip2.1.preformatted), and preformatted
  94.    and sanitised for MS-DOS (bzip2.txt).
  95.  
  96.    
  97.  
  98. COMPILATION NOTES
  99.  
  100.    bzip2 should work on any 32 or 64-bit machine.  It is known to work
  101.    [meaning: it has compiled and passed self-tests] on the 
  102.    following platform-os combinations:
  103.  
  104.       Intel i386/i486        running Linux 2.0.21
  105.       Sun Sparcs (various)   running SunOS 4.1.4 and Solaris 2.5
  106.       Intel i386/i486        running Windows 95 and NT
  107.       DEC Alpha              running Digital Unix 4.0
  108.  
  109.    Following the release of bzip-0.21, many people mailed me
  110.    from around the world to say they had made it work on all sorts
  111.    of weird and wonderful machines.  Chances are, if you have
  112.    a reasonable ANSI C compiler and a 32-bit machine, you can
  113.    get it to work.
  114.  
  115.    The #defines starting at around line 82 of bzip2.c supply some
  116.    degree of platform-independance.  If you configure bzip2 for some
  117.    new far-out platform which is not covered by the existing definitions,
  118.    please send me the relevant definitions.
  119.  
  120.    I recommend GNU C for compilation.  The code is standard ANSI C,
  121.    except for the Unix-specific file handling, so any ANSI C compiler
  122.    should work.  Note however that the many routines marked INLINE
  123.    should be inlined by your compiler, else performance will be very
  124.    poor.  Asking your compiler to unroll loops gives some
  125.    small improvement too; for gcc, the relevant flag is
  126.    -funroll-loops.
  127.  
  128.    On a 386/486 machines, I'd recommend giving gcc the
  129.    -fomit-frame-pointer flag; this liberates another register for
  130.    allocation, which measurably improves performance.
  131.  
  132.    I used the abovementioned lcc compiler to develop bzip2.
  133.    I would highly recommend this compiler for day-to-day development;
  134.    it is fast, reliable, lightweight, has an excellent profiler,
  135.    and is generally excellent.  And it's fun to retarget, if you're
  136.    into that kind of thing.
  137.  
  138.    If you compile bzip2 on a new platform or with a new compiler,
  139.    please be sure to run the four compress-decompress tests, either
  140.    using the Makefile, or with the test.bat (MSDOS) or test.cmd (OS/2)
  141.    files.  Some compilers have been seen to introduce subtle bugs
  142.    when optimising, so this check is important.  Ideally you should
  143.    then go on to test bzip2 on a file several megabytes or even
  144.    tens of megabytes long, just to be 110% sure.  ``Professional
  145.    programmers are paranoid programmers.'' (anon).
  146.  
  147.  
  148.  
  149. VALIDATION
  150.  
  151.    Correct operation, in the sense that a compressed file can always be
  152.    decompressed to reproduce the original, is obviously of paramount
  153.    importance.  To validate bzip2, I used a modified version of 
  154.    Mark Nelson's churn program.  Churn is an automated test driver
  155.    which recursively traverses a directory structure, using bzip2 to
  156.    compress and then decompress each file it encounters, and checking
  157.    that the decompressed data is the same as the original.  As test 
  158.    material, I used several runs over several filesystems of differing
  159.    sizes.
  160.  
  161.    One set of tests was done on my base Linux filesystem,
  162.    410 megabytes in 23,000 files.  There were several runs over
  163.    this filesystem, in various configurations designed to break bzip2.
  164.    That filesystem also contained some specially constructed test
  165.    files designed to exercise boundary cases in the code.
  166.    This included files of zero length, various long, highly repetitive 
  167.    files, and some files which generate blocks with all values the same.
  168.  
  169.    The other set of tests was done just with the "normal" configuration,
  170.    but on a much larger quantity of data.
  171.  
  172.       Tests are:
  173.  
  174.          Linux FS, 410M, 23000 files
  175.  
  176.          As above, with --repetitive-fast
  177.  
  178.          As above, with -1
  179.  
  180.          Low level disk image of a disk containing
  181.             Windows NT4.0; 420M in a single huge file
  182.  
  183.          Linux distribution, incl Slackware, 
  184.             all GNU sources.   1900M in 2300 files.
  185.  
  186.          Approx ~100M compiler sources and related
  187.             programming tools, running under Purify.
  188.  
  189.          About 500M of data in 120 files of around
  190.             4 M each.  This is raw data from a 
  191.             biomagnetometer (SQUID-based thing).
  192.  
  193.       Overall, total volume of test data is about
  194.          3300 megabytes in 25000 files.
  195.  
  196.    The distribution does four tests after building bzip.  These tests
  197.    include test decompressions of pre-supplied compressed files, so
  198.    they not only test that bzip works correctly on the machine it was
  199.    built on, but can also decompress files compressed on a different
  200.    machine.  This guards against unforseen interoperability problems.
  201.  
  202.  
  203. Please read and be aware of the following:
  204.  
  205. WARNING:
  206.  
  207.    This program (attempts to) compress data by performing several
  208.    non-trivial transformations on it.  Unless you are 100% familiar
  209.    with *all* the algorithms contained herein, and with the
  210.    consequences of modifying them, you should NOT meddle with the
  211.    compression or decompression machinery.  Incorrect changes can and
  212.    very likely *will* lead to disastrous loss of data.
  213.  
  214.  
  215. DISCLAIMER:
  216.  
  217.    I TAKE NO RESPONSIBILITY FOR ANY LOSS OF DATA ARISING FROM THE
  218.    USE OF THIS PROGRAM, HOWSOEVER CAUSED.
  219.  
  220.    Every compression of a file implies an assumption that the
  221.    compressed file can be decompressed to reproduce the original.
  222.    Great efforts in design, coding and testing have been made to
  223.    ensure that this program works correctly.  However, the complexity
  224.    of the algorithms, and, in particular, the presence of various
  225.    special cases in the code which occur with very low but non-zero
  226.    probability make it impossible to rule out the possibility of bugs
  227.    remaining in the program.  DO NOT COMPRESS ANY DATA WITH THIS
  228.    PROGRAM UNLESS YOU ARE PREPARED TO ACCEPT THE POSSIBILITY, HOWEVER
  229.    SMALL, THAT THE DATA WILL NOT BE RECOVERABLE.
  230.  
  231.    That is not to say this program is inherently unreliable.  Indeed,
  232.    I very much hope the opposite is true.  bzip2 has been carefully
  233.    constructed and extensively tested.
  234.  
  235.  
  236. PATENTS:
  237.  
  238.    To the best of my knowledge, bzip2 does not use any patented
  239.    algorithms.  However, I do not have the resources available to
  240.    carry out a full patent search.  Therefore I cannot give any
  241.    guarantee of the above statement.
  242.  
  243. End of legalities.
  244.  
  245.  
  246. I hope you find bzip2 useful.  Feel free to contact me at
  247.    jseward@acm.org
  248. if you have any suggestions or queries.  Many people mailed me with
  249. comments, suggestions and patches after the releases of 0.15 and 0.21, 
  250. and the changes in bzip2 are largely a result of this feedback.
  251. I thank you for your comments.
  252.  
  253. Julian Seward
  254.  
  255. Manchester, UK
  256. 18 July 1996 (version 0.15)
  257. 25 August 1996 (version 0.21)
  258.  
  259. Guildford, Surrey, UK
  260. 7 August 1997 (bzip2, version 0.1)
  261. 29 August 1997 (bzip2, version 0.1pl2)
  262.  
  263.