Blame README

Packit d03632
Packit d03632
                            Compress-Raw-Zlib
Packit d03632
Packit d03632
                         Version 2.081
Packit d03632
Packit d03632
                               4 April 2018
Packit d03632
Packit d03632
       Copyright (c) 2005-2018 Paul Marquess. All rights reserved.
Packit d03632
          This program is free software; you can redistribute it
Packit d03632
           and/or modify it under the same terms as Perl itself.
Packit d03632
Packit d03632
              The directory zlib-src contains a subset of the
Packit d03632
             source files copied directly from zlib version 1.2.11.
Packit d03632
                  These files are Copyright(C) 1995-2017
Packit d03632
                     Jean-loup Gailly and Mark Adler.
Packit d03632
             Full source for the zlib library is available at
Packit d03632
                            http://www.zlib.org
Packit d03632
Packit d03632
DESCRIPTION
Packit d03632
-----------
Packit d03632
Packit d03632
This module provides a Perl interface to the zlib compression library. 
Packit d03632
Packit d03632
PREREQUISITES
Packit d03632
-------------
Packit d03632
Packit d03632
Before you can build Compress-Raw-Zlib you need to have the following
Packit d03632
installed on your system:
Packit d03632
Packit d03632
    * A C compiler
Packit d03632
Packit d03632
    * Perl 5.006 or better.
Packit d03632
Packit d03632
By default, Compress-Raw-Zlib will build its own private copy of the
Packit d03632
zlib library. If you want to use a different version of
Packit d03632
zlib, follow the instructions in the section called
Packit d03632
"Controlling the version of zlib used by Compress-Raw-Zlib"
Packit d03632
later in this document.
Packit d03632
Packit d03632
BUILDING THE MODULE
Packit d03632
-------------------
Packit d03632
Packit d03632
Assuming you have met all the prerequisites, the module can now be built
Packit d03632
using this sequence of commands:
Packit d03632
Packit d03632
    perl Makefile.PL
Packit d03632
    make
Packit d03632
    make test
Packit d03632
Packit d03632
INSTALLATION
Packit d03632
------------
Packit d03632
Packit d03632
To install Compress-Raw-Zlib, run the command below:
Packit d03632
Packit d03632
    make install
Packit d03632
Packit d03632
Controlling the version of zlib used by Compress-Raw-Zlib
Packit d03632
----------------------------------------------------------
Packit d03632
Packit d03632
Compress-Raw-Zlib interfaces to the zlib compression library. There
Packit d03632
are three options available to control which version/instance of the
Packit d03632
zlib library is used:
Packit d03632
Packit d03632
    1. Build a private copy of the zlib library using the
Packit d03632
       zlib library source that is included with this module.
Packit d03632
       This is the default and recommended option.
Packit d03632
Packit d03632
    2. Build a private copy of the zlib library using a standard
Packit d03632
       zlib source distribution.
Packit d03632
Packit d03632
    3. Use a pre-built zlib library.
Packit d03632
Packit d03632
Note that if you intend to use either Option 2 or 3, you need to have
Packit d03632
zlib version 1.2.0 or better.
Packit d03632
Packit d03632
The contents of the file config.in are used to control which of the
Packit d03632
three options is actually used. This file is read during the
Packit d03632
Packit d03632
    perl Makefile.PL
Packit d03632
Packit d03632
step of the build, so remember to make any required changes to config.in
Packit d03632
before building this module.
Packit d03632
Packit d03632
  Option 1
Packit d03632
  --------
Packit d03632
 
Packit d03632
  For option 1, edit the file config.in and set the variables in it
Packit d03632
  as follows:
Packit d03632
Packit d03632
      BUILD_ZLIB   = True
Packit d03632
      INCLUDE      = ./zlib-src
Packit d03632
      LIB          = ./zlib-src
Packit d03632
      OLD_ZLIB     = False
Packit d03632
      GZIP_OS_CODE = AUTO_DETECT
Packit d03632
Packit d03632
  Option 2
Packit d03632
  --------
Packit d03632
Packit d03632
  For option 2, fetch a copy of the zlib source distribution from
Packit d03632
  http://www.zlib.org and unpack it into the Compress-Raw-Zlib source
Packit d03632
  directory. Assuming you have fetched zlib 1.2.11,
Packit d03632
  it will create a directory called zlib-1.2.11.
Packit d03632
Packit d03632
  Now set the variables in the file config.in as follows (if the version
Packit d03632
  you have fetched isn't 1.2.11, change the INCLUDE and LIB
Packit d03632
  variables appropriately):
Packit d03632
Packit d03632
      BUILD_ZLIB   = True
Packit d03632
      INCLUDE      = ./zlib-1.2.11
Packit d03632
      LIB          = ./zlib-1.2.11
Packit d03632
      OLD_ZLIB     = False
Packit d03632
      GZIP_OS_CODE = AUTO_DETECT
Packit d03632
Packit d03632
  Option 3
Packit d03632
  --------
Packit d03632
Packit d03632
  For option 3, you need to find out where zlib is stored on your
Packit d03632
  system.  There are two parts to this.
Packit d03632
Packit d03632
  First, find the directory where the zlib library is stored (some
Packit d03632
  common names for the library are libz.a and libz.so). Set the LIB variable
Packit d03632
  in the config.in file to that directory.
Packit d03632
Packit d03632
  Secondly, find the directory where the file zlib.h is stored. Now set
Packit d03632
  the INCLUDE variable in the config.in file to that directory.
Packit d03632
Packit d03632
  Next set BUILD_ZLIB to False.
Packit d03632
Packit d03632
  Finally, if you are running zlib 1.0.5 or older, set the OLD_ZLIB
Packit d03632
  variable to True. Otherwise set it to False.
Packit d03632
Packit d03632
  As an example, if the zlib library on your system is in
Packit d03632
  /usr/local/lib, zlib.h is in /usr/local/include and zlib is more
Packit d03632
  recent than version 1.0.5, the variables in config.in should be set as
Packit d03632
  follows:
Packit d03632
Packit d03632
      BUILD_ZLIB   = False
Packit d03632
      INCLUDE      = /usr/local/include
Packit d03632
      LIB          = /usr/local/lib
Packit d03632
      OLD_ZLIB     = False
Packit d03632
      GZIP_OS_CODE = AUTO_DETECT
Packit d03632
Packit d03632
Setting the Gzip OS Code
Packit d03632
------------------------
Packit d03632
Packit d03632
Every gzip stream stores a byte in its header to identify the Operating
Packit d03632
System that was used to create the gzip stream. When you build Compress-Raw-Zlib it will attempt to determine the value that is correct for
Packit d03632
your Operating System. This will then be used by IO::Compress::Gzip as the
Packit d03632
default value for the OS byte in all gzip headers it creates.
Packit d03632
Packit d03632
The variable GZIP_OS_CODE in the config.in file controls the setting of
Packit d03632
this value when building Compress-Raw-Zlib. If GZIP_OS_CODE is set to
Packit d03632
AUTO_DETECT, Compress-Raw-Zlib will attempt to determine the correct value for
Packit d03632
your Operating System.
Packit d03632
Packit d03632
Alternatively, you can override auto-detection of the default OS code and
Packit d03632
explicitly set it yourself. Set the GZIP_OS_CODE variable in the config.in
Packit d03632
file to be a number between 0 and 255. For example
Packit d03632
Packit d03632
    GZIP_OS_CODE = 3
Packit d03632
Packit d03632
See RFC 1952 for valid OS codes that can be used.
Packit d03632
Packit d03632
If you are running one of the less popular Operating Systems, it is
Packit d03632
possible that the default value picked by this module is incorrect or the
Packit d03632
default value (3) is used when there is a better value available. When
Packit d03632
Compress-Raw-Zlib cannot determine what operating system you are running, it
Packit d03632
will use the default value 3 for the OS code.
Packit d03632
Packit d03632
If you find you have to change this value, because you think the value auto
Packit d03632
detected is incorrect, please take a few moments to contact the author of
Packit d03632
this module.
Packit d03632
Packit d03632
TROUBLESHOOTING
Packit d03632
---------------
Packit d03632
Packit d03632
Undefined Symbol gzsetparams
Packit d03632
----------------------------
Packit d03632
Packit d03632
If you get the error shown below when you run the Compress-Raw-Zlib test
Packit d03632
harness it probably means you are running a copy of zlib that is
Packit d03632
version 1.0.5 or older.
Packit d03632
Packit d03632
t/01version.........Can't load 'blib/arch/auto/Compress/Zlib/Zlib.so' for
Packit d03632
                    module Compress::Raw::Zlib: blib/arch/auto/Compress/Raw/Zlib/Zlib.so:
Packit d03632
                    undefined symbol: gzsetparams at ...
Packit d03632
Packit d03632
There are two ways to fix this problem:
Packit d03632
Packit d03632
    1. Upgrade to the latest version of zlib.
Packit d03632
Packit d03632
    2. Edit config.in and set the OLD_ZLIB variable to True.
Packit d03632
Packit d03632
Test Harness 01version fails
Packit d03632
----------------------------
Packit d03632
If the 01version test harness fails, and the problem isn't covered by the
Packit d03632
scenario above, it probably means that you have two versions of
Packit d03632
zlib installed on your system.
Packit d03632
Packit d03632
Run the command below to see if this is indeed the case
Packit d03632
Packit d03632
    make test TEST_VERBOSE=1 TEST_FILES=t/01version.t
Packit d03632
Packit d03632
Try removing the one you don't want to use and rebuild.
Packit d03632
Packit d03632
Solaris build fails with "language optional software package not installed"
Packit d03632
---------------------------------------------------------------------------
Packit d03632
Packit d03632
If you are trying to build this module under Solaris and you get an
Packit d03632
error message like this
Packit d03632
Packit d03632
    /usr/ucb/cc: language optional software package not installed
Packit d03632
Packit d03632
it means that Perl cannot find the C compiler on your system. The cryptic
Packit d03632
message is just Sun's way of telling you that you haven't bought their
Packit d03632
C compiler.
Packit d03632
Packit d03632
When you build a Perl module that needs a C compiler, the Perl build
Packit d03632
system tries to use the same C compiler that was used to build perl
Packit d03632
itself. In this case your Perl binary was built with a C compiler that
Packit d03632
lived in /usr/ucb.
Packit d03632
Packit d03632
To continue with building this module, you need to get a C compiler,
Packit d03632
or tell Perl where your C compiler is, if you already have one.
Packit d03632
Packit d03632
Assuming you have now got a C compiler, what you do next will be dependent
Packit d03632
on what C compiler you have installed. If you have just installed Sun's
Packit d03632
C compiler, you shouldn't have to do anything. Just try rebuilding
Packit d03632
this module.
Packit d03632
Packit d03632
If you have installed another C compiler, say gcc, you have to tell perl
Packit d03632
how to use it instead of /usr/ucb/cc.
Packit d03632
Packit d03632
This set of options seems to work if you want to use gcc. Your mileage
Packit d03632
may vary.
Packit d03632
Packit d03632
    perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" "
Packit d03632
    make test
Packit d03632
Packit d03632
If that doesn't work for you, it's time to make changes to the Makefile
Packit d03632
by hand. Good luck!
Packit d03632
Packit d03632
Solaris build fails with "gcc: unrecognized option `-KPIC'"
Packit d03632
-----------------------------------------------------------
Packit d03632
Packit d03632
You are running Solaris and you get an error like this when you try to
Packit d03632
build this Perl module
Packit d03632
Packit d03632
    gcc: unrecognized option `-KPIC'
Packit d03632
Packit d03632
This symptom usually means that you are using a Perl binary that has been
Packit d03632
built with the Sun C compiler, but you are using gcc to build this module.
Packit d03632
Packit d03632
When Perl builds modules that need a C compiler, it will attempt to use
Packit d03632
the same C compiler and command line options that was used to build perl
Packit d03632
itself. In this case "-KPIC" is a valid option for the Sun C compiler,
Packit d03632
but not for gcc. The equivalent option for gcc is "-fPIC".
Packit d03632
Packit d03632
The solution is either:
Packit d03632
Packit d03632
    1. Build both Perl and this module with the same C compiler, either
Packit d03632
       by using the Sun C compiler for both or gcc for both.
Packit d03632
Packit d03632
    2. Try generating the Makefile for this module like this perl
Packit d03632
Packit d03632
           perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc
Packit d03632
           make test
Packit d03632
Packit d03632
       This second option seems to work when mixing a Perl binary built
Packit d03632
       with the Sun C compiler and this module built with gcc. Your
Packit d03632
       mileage may vary.
Packit d03632
Packit d03632
HP-UX Notes
Packit d03632
-----------
Packit d03632
Packit d03632
I've had a report that when building Compress-Raw-Zlib under HP-UX that it
Packit d03632
is necessary to have first built the zlib library with the -fpic
Packit d03632
option.
Packit d03632
Packit d03632
Linux Notes
Packit d03632
-----------
Packit d03632
Packit d03632
Although most Linux distributions already come with zlib, some
Packit d03632
people report getting this error when they try to build this module:
Packit d03632
Packit d03632
$ make
Packit d03632
cp Zlib.pm blib/lib/Compress/Zlib.pm
Packit d03632
AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib)
Packit d03632
/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
Packit d03632
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
Packit d03632
Zlib.xs:25:19: zlib.h: No such file or directory
Packit d03632
make: *** [Zlib.o] Error 1
Packit d03632
Packit d03632
This usually means that you have not installed the development RPM
Packit d03632
for zlib. Check for an RPM that start with "zlib-devel" in your Linux
Packit d03632
distribution.
Packit d03632
Packit d03632
Win32 Notes
Packit d03632
-----------
Packit d03632
Packit d03632
If you are running Activestate Perl (from http://www.activestate.com),
Packit d03632
it ships with a pre-compiled version of Compress-Raw-Zlib. To check if a
Packit d03632
newer version of Compress-Raw-Zlib is available run this from the command
Packit d03632
prompt
Packit d03632
Packit d03632
    C:\> ppm verify -upgrade Compress-Raw-Zlib
Packit d03632
Packit d03632
If you are not running Activestate Perl and you don't have access
Packit d03632
to a C compiler, you will not be able to build and install this module.
Packit d03632
Packit d03632
Win32 & Cygwin Notes
Packit d03632
--------------------
Packit d03632
Packit d03632
It is not possible to install Compress-Raw-Zlib using the CPAN shell.
Packit d03632
This is because the Compress-Raw-Zlib DLL is itself used by the CPAN shell
Packit d03632
and it is impossible to remove a DLL while it is already loaded under
Packit d03632
Windows.
Packit d03632
Packit d03632
The workaround is to install Compress-Raw-Zlib manually using the
Packit d03632
instructions given at the start of this file.
Packit d03632
Packit d03632
FEEDBACK
Packit d03632
--------
Packit d03632
Packit d03632
How to report a problem with Compress-Raw-Zlib.
Packit d03632
Packit d03632
To help me help you, I need all of the following information:
Packit d03632
Packit d03632
 1. The Versions of everything relevant.
Packit d03632
    This includes:
Packit d03632
Packit d03632
     a. The *complete* output from running this
Packit d03632
 
Packit d03632
            perl -V
Packit d03632
 
Packit d03632
        Do not edit the output in any way.
Packit d03632
        Note, I want you to run "perl -V" and NOT "perl -v".
Packit d03632
 
Packit d03632
        If your perl does not understand the "-V" option it is too
Packit d03632
        old. This module needs Perl version 5.004 or better.
Packit d03632
Packit d03632
     b. The version of Compress-Raw-Zlib you have.
Packit d03632
        If you have successfully installed Compress-Raw-Zlib, this one-liner
Packit d03632
        will tell you:
Packit d03632
Packit d03632
           perl -MCompress::Raw::Zlib -e 'print qq[ver $Compress::Raw::Zlib::VERSION\n]'
Packit d03632
Packit d03632
        If you are  running windows use this
Packit d03632
Packit d03632
           perl -MCompress::Raw::Zlib -e "print qq[ver $Compress::Raw::Zlib::VERSION\n]"
Packit d03632
Packit d03632
        If you haven't installed Compress-Raw-Zlib then search Compress::Raw::Zlib.pm
Packit d03632
        for a line like this:
Packit d03632
Packit d03632
          $VERSION = "2.081" ;
Packit d03632
Packit d03632
     c. The version of zlib you have used.
Packit d03632
        If you have successfully installed Compress-Raw-Zlib, this one-liner
Packit d03632
        will tell you:
Packit d03632
Packit d03632
          perl -MCompress::Raw::Zlib -e "print q[zlib ver ]. Compress::Raw::Zlib::ZLIB_VERSION.qq[\n]"
Packit d03632
Packit d03632
        If not, look at the beginning of the file zlib.h.
Packit d03632
Packit d03632
 2. If you are having problems building Compress-Raw-Zlib, send me a
Packit d03632
    complete log of what happened. Start by unpacking the Compress-Raw-Zlib
Packit d03632
    module into a fresh directory and keep a log of all the steps
Packit d03632
Packit d03632
        [edit config.in, if necessary]
Packit d03632
        perl Makefile.PL
Packit d03632
        make
Packit d03632
        make test TEST_VERBOSE=1
Packit d03632
Packit d03632
Paul Marquess <pmqs@cpan.org>