
                                 Compress::Zlib

                                 Version 2.000_01

                                 21st Aug 2005 

       Copyright (c) 1995-2005 Paul Marquess. All rights reserved.
             This program is free software; you can redistribute it
             and/or modify it under the same terms as Perl itself.


                The directory zlib-src contains a subset of the 
              source files copied directly from zlib version 1.2.3.
                     These files are Copyright(C) 1995-2005
                        Jean-loup Gailly and Mark Adler.
                Full source for the zlib library is available at
                              http://www.zlib.org


                                    WARNING
                               THIS IS BETA CODE.

                         DO NOT use in production code.
                          Please report any problems.

DESCRIPTION
-----------

This module provides a Perl interface to most of the zlib compression
library.  For more details see the pod documentation embedded in the
file Zlib.pm.

If you have downloaded this module in the expectation of manipulating the
contents of .zip files, you will need to fetch and build the Archive::Zip
module below once you have installed this one.

    http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz




PREREQUISITES
-------------

Before you can build Compress::Zlib you need to have the following
installed on your system:

    * A C compiler

    * Perl 5.004 or better. 

By default, Compress::Zlib will build its own private copy of the zlib
library. If you want to use a different version of zlib, follow the
instructions in the section called "Controlling the version of zlib used
by Compress::Zlib" later in this document.


BUILDING THE MODULE
-------------------

Assuming you have met all the prerequisites, the module can now be built
using this sequence of commands:

    perl Makefile.PL
    make
    make test



INSTALLATION
------------

To install Compress::Zlib, run the command below:

    make install

UPDATES
-------
 
The most recent version of Compress::Zlib is always available at
 
    http://www.cpan.org/modules/by-module/Compress/



Controlling the version of zlib used by Compress::Zlib
-----------------------------------------------------

Compress::Zlib interfaces to the zlib compression library. There are
three options available to control which version/instance of the zlib
library is used:

    1. Build a private copy of the zlib library using the zlib library
       source that is included with this module.
       This is the default and recommended option.

    2. Build a private copy of the zlib library using a standard zlib
       source distribution.

    3. Use a pre-built zlib library.

Note that if you intend to use either Option 2 or 3, you need to have
zlib version 1.0.5 or better.


The contents of the file config.in are used to control which of the
three options is actually used. This file is read during the

    perl Makefile.PL 

step of the build, so remember to make any required changes to config.in
before building this module.



  Option 1
  --------
  
  For option 1, edit the file config.in and set the variables in it
  as follows:
  
      BUILD_ZLIB   = True
      INCLUDE      = ./zlib-src
      LIB          = ./zlib-src
      OLD_ZLIB     = False
      GZIP_OS_CODE = AUTO_DETECT
  
  
  Option 2
  --------
  
  For option 2, fetch a copy of the zlib source distribution from
  http://www.zlib.org and unpack it into the Compress::Zlib source
  directory. Assuming you have fetched zlib 1.2.3, it will create a
  directory called zlib-1.2.3. 
  
  Now set the variables in the file config.in as follows (if the version
  you have fetched isn't 1.2.3, change the INCLUDE and LIB variables
  appropriately):
  
      BUILD_ZLIB   = True
      INCLUDE      = ./zlib-1.2.3
      LIB          = ./zlib-1.2.3
      OLD_ZLIB     = False
      GZIP_OS_CODE = AUTO_DETECT
  
  
  Option 3
  --------
  
  For option 3, you need to find out where zlib is stored on your system.
  There are two parts to this.

  First, find the directory where the zlib library is stored (some common
  names for the library are libz.a and libz.so). Set the LIB variable in
  the config.in file to that directory.
  
  Secondly, find the directory where the file zlib.h is stored. Now set
  the INCLUDE variable in the config.in file to that directory.
  
  Next set BUILD_ZLIB to False.
  
  Finally, if you are running zlib 1.0.5 or older, set the OLD_ZLIB
  variable to True. Otherwise set it to False.

  As an example, if the zlib library on your system is in /usr/local/lib,
  zlib.h is in /usr/local/include and zlib is more recent than version
  1.0.5, the variables in config.in should be set as follows:

      BUILD_ZLIB   = False
      INCLUDE      = /usr/local/include
      LIB          = /usr/local/lib
      OLD_ZLIB     = False
      GZIP_OS_CODE = AUTO_DETECT
  

Setting the Gzip OS Code
------------------------

Every gzip stream stores a byte in its header to identify the Operating System
that was used to create the gzip stream. When you build Compress::Zlib it will
attempt to determine the value that is correct for your Operating System. This
will then be used by IO::Gzip as the default value for the OS byte in all gzip
headers it creates. 
 
The variable GZIP_OS_CODE in the config.in file controls the setting of this
value when building Compress::Zlib. If GZIP_OS_CODE is set to AUTO_DETECT,
Compress::Zlib will attempt to determine the correct value for your Operating
System.

Alternatively, you can override auto-detection of the default OS code and
explicitly set it yourself. Set the GZIP_OS_CODE variable in the config.in file
to be a number between 0 and 255. For example
 
    GZIP_OS_CODE = 3

See RFC 1952 for valid OS codes that can be used.

If you are running one of the less popular Operating Systems, it could be that
the default value picked by this module is incorrect or the default value (3)
is used when there is a better value available. When Compress::Zlib cannot
determine what operating system you are running, it will use the default value
3 for the OS code.

If you find you have to change this value, because you think the value auto
detected is incorrect, please take a few moments to contact the author of this
module.


TROUBLESHOOTING
---------------

Undefined Symbol gzsetparams
----------------------------

If you get the error shown below when you run the Compress::Zlib test
harness it probably means you are running a copy of zlib that is version
1.0.5 or older.

t/01version.........Can't load 'blib/arch/auto/Compress/Zlib/Zlib.so' for 
                    module Compress::Zlib: blib/arch/auto/Compress/Zlib/Zlib.so:
                    undefined symbol: gzsetparams at ...

There are two ways to fix this problem:

    1. Upgrade to the latest version of zlib.

    2. Edit config.in and set the OLD_ZLIB variable to True.



Test Harness 01version fails
----------------------------
If the 01version test harness fails, and the problem isn't covered by
the scenario above, it probably means that you have two versions of zlib
installed on your system.

Run the command below to see if this is indeed the case

    make test TEST_VERBOSE=1 TEST_FILES=t/01version.t 

Try removing the one you don't want to use and rebuild.   



Solaris build fails with "language optional software package not installed"
---------------------------------------------------------------------------

If you are trying to build this module under Solaris and you get an
error message like this

    /usr/ucb/cc: language optional software package not installed

it means that Perl cannot find the C compiler on your system. The cryptic
message is just Sun's way of telling you that you haven't bought their
C compiler.

When you build a Perl module that needs a C compiler, the Perl build
system tries to use the same C compiler that was used to build perl
itself. In this case your Perl binary was built with a C compiler that
lived in /usr/ucb.

To continue with building this module, you need to get a C compiler,
or tell Perl where your C compiler is, if you already have one.

Assuming you have now got a C compiler, what you do next will be dependent
on what C compiler you have installed. If you have just installed Sun's
C compiler, you shouldn't have to do anything. Just try rebuilding
this module.

If you have installed another C compiler, say gcc, you have to tell perl
how to use it instead of /usr/ucb/cc.

This set of options seems to work if you want to use gcc. Your mileage
may vary.

    perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" "
    make test

If that doesn't work for you, it's time to make changes to the Makefile
by hand. Good luck!




Solaris build fails with "gcc: unrecognized option `-KPIC'"
-----------------------------------------------------------

You are running Solaris and you get an error like this when you try to
build this Perl module

    gcc: unrecognized option `-KPIC'

This symptom usually means that you are using a Perl binary that has been
built with the Sun C compiler, but you are using gcc to build this module.

When Perl builds modules that need a C compiler, it will attempt to use
the same C compiler and command line options that was used to build perl
itself. In this case "-KPIC" is a valid option for the Sun C compiler,
but not for gcc. The equivalent option for gcc is "-fPIC".

The solution is either:

    1. Build both Perl and this module with the same C compiler, either
       by using the Sun C compiler for both or gcc for both.

    2. Try generating the Makefile for this module like this perl

           perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc
           make test

       This second option seems to work when mixing a Perl binary built
       with the Sun C compiler and this module built with gcc. Your
       mileage may vary.


The t/17isize Test Suite
------------------------

This test suite checks that Compress::Zlib can cope with gzip files
that are larger than 2^32 bytes.

By default these test are NOT run when you do a "make test". If you
really want to run them, you need to execute "make longtest".

Be warned though -- this test suite can take hours to run on a slow box.

Also, due to the way the tests are constructed, some architectures will
run out of memory during these test. This should not be considered a bug
in the Compress::Zlib module.



HP-UX Notes
-----------

I've had a report that when building Compress::Zlib under HP-UX that it
is necessary to have first built the zlib library with the -fpic option.



Linux Notes
-----------

Although most Linux distributions already come with zlib, some people
report getting this error when they try to build this module:

$ make
cp Zlib.pm blib/lib/Compress/Zlib.pm
AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib)
/usr/bin/perl -I/usr/lib/perl5/5.6.1/i386-linux -I/usr/lib/perl5/5.6.1 /usr/lib/perl5/5.6.1/ExtUtils/xsubpp  -typemap /usr/lib/perl5/5.6.1/ExtUtils/typemap -typemap typemap Zlib.xs > Zlib.xsc && mv Zlib.xsc Zlib.c
gcc -c -I/usr/local/include -fno-strict-aliasing -I/usr/local/include -O2 -march=i386 -mcpu=i686   -DVERSION=\"1.16\" -DXS_VERSION=\"1.16\" -fPIC -I/usr/lib/perl5/5.6.1/i386-linux/CORE  Zlib.c
Zlib.xs:25:19: zlib.h: No such file or directory
make: *** [Zlib.o] Error 1

This usually means that you have not installed the development RPM
for zlib. Check for an RPM that start with "zlib-devel" in your Linux
distribution.




Win32 Notes
-----------

If you are running Activestate Perl (from http://www.activestate.com),
it ships with a pre-compiled version of Compress::Zlib. To check if a
newer version of Compress::Zlib is available run this from the command
prompt

    C:\> ppm verify -upgrade Compress-Zlib


If you are not running Activestate Perl and you don't have access
to a C compiler, you will not be able to build and install this module.




Win32 & Cygwin Notes
--------------------

It is not possible to install Compress::Zlib using the CPAN shell.
This is because the Compress::Zlib DLL is itself used by the CPAN shell
and it is impossible to remove a DLL while it is already loaded under
Windows.

The workaround is to install Compress::Zlib manually using the
instructions given at the start of this file.



FEEDBACK
--------

How to report a problem with Compress::Zlib.

To help me help you, I need all of the following information:

 1. The *complete* output from running this
 
        perl -V
 
    Do not edit the output in any way.
    Note, I want you to run "perl -V" and NOT "perl -v".
 
    If your perl does not understand the "-V" option it is too
    old. This module needs Perl version 5.004 or better.     

 2. The version of Compress::Zlib you have. 
    If you have successfully installed Compress::Zlib, this one-liner
    will tell you:

       perl -MCompress::Zlib -e 'print qq[ver $Compress::Zlib::VERSION\n]'

    If you are running windows use this

       perl -MCompress::Zlib -e "print qq[ver $Compress::Zlib::VERSION\n]"

    If you haven't installed Compress::Zlib then search Compress::Zlib.pm
    for a line like this:

      $VERSION = "1.05" ;

 3. The version of zlib you have installed.
    If you have successfully installed Compress::Zlib, this one-liner
    will tell you:

      perl -MCompress::Zlib -e "print q[zlib ver ]. Compress::Zlib::ZLIB_VERSION.qq[\n]" 


    If not, look at the beginning of the file zlib.h. 

 4. If you are having problems building Compress::Zlib, send me a
    complete log of what happened. Start by unpacking the Compress:Zlib
    module into a fresh directory and keep a log of all the steps

        [edit config.in, if necessary]
        perl Makefile.PL
        make
        make test TEST_VERBOSE=1          


Paul Marquess <pmqs@cpan.org>
