perl-5.16.2/cpan/Compress-Raw-Zlib/README - toolchain/perl - Git at Google


                              Compress-Raw-Zlib

                              Version 2.048

                              29th January 2012

        Copyright (c) 2005-2012 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.5.
                   These files are Copyright(C) 1995-2010
                      Jean-loup Gailly and Mark Adler.
              Full source for the zlib library is available at
                             http://www.zlib.org

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

 This module provides a Perl interface to the zlib compression library.

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

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

     * A C compiler

     * Perl 5.004 or better.

 By default, Compress-Raw-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-Raw-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-Raw-Zlib, run the command below:

     make install

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

 Compress-Raw-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.2.0 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-Raw-Zlib source
   directory. Assuming you have fetched zlib 1.2.5,
   it will create a directory called zlib-1.2.5.

   Now set the variables in the file config.in as follows (if the version
   you have fetched isn't 1.2.5, change the INCLUDE and LIB
   variables appropriately):

       BUILD_ZLIB   = True
       INCLUDE      = ./zlib-1.2.5
       LIB          = ./zlib-1.2.5
       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-Raw-Zlib it will attempt to determine the value that is correct for
 your Operating System. This will then be used by IO::Compress::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-Raw-Zlib. If GZIP_OS_CODE is set to
 AUTO_DETECT, Compress-Raw-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 is
 possible 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-Raw-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-Raw-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::Raw::Zlib: blib/arch/auto/Compress/Raw/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.

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

 I've had a report that when building Compress-Raw-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-Raw-Zlib. To check if a
 newer version of Compress-Raw-Zlib is available run this from the command
 prompt

     C:\> ppm verify -upgrade Compress-Raw-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-Raw-Zlib using the CPAN shell.
 This is because the Compress-Raw-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-Raw-Zlib manually using the
 instructions given at the start of this file.

 FEEDBACK
 --------

 How to report a problem with Compress-Raw-Zlib.

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

  1. The Versions of everything relevant.
     This includes:

      a. 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.

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

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

         If you are  running windows use this

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

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

           $VERSION = "2.048" ;

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

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

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

  2. If you are having problems building Compress-Raw-Zlib, send me a
     complete log of what happened. Start by unpacking the Compress-Raw-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>

	Compress-Raw-Zlib

	Version 2.048

	29th January 2012

	Copyright (c) 2005-2012 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.5.
	These files are Copyright(C) 1995-2010
	Jean-loup Gailly and Mark Adler.
	Full source for the zlib library is available at
	http://www.zlib.org

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

	This module provides a Perl interface to the zlib compression library.

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

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

	* A C compiler

	* Perl 5.004 or better.

	By default, Compress-Raw-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-Raw-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-Raw-Zlib, run the command below:

	make install

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

	Compress-Raw-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.2.0 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-Raw-Zlib source
	directory. Assuming you have fetched zlib 1.2.5,
	it will create a directory called zlib-1.2.5.

	Now set the variables in the file config.in as follows (if the version
	you have fetched isn't 1.2.5, change the INCLUDE and LIB
	variables appropriately):

	BUILD_ZLIB = True
	INCLUDE = ./zlib-1.2.5
	LIB = ./zlib-1.2.5
	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-Raw-Zlib it will attempt to determine the value that is correct for
	your Operating System. This will then be used by IO::Compress::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-Raw-Zlib. If GZIP_OS_CODE is set to
	AUTO_DETECT, Compress-Raw-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 is
	possible 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-Raw-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-Raw-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::Raw::Zlib: blib/arch/auto/Compress/Raw/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.

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

	I've had a report that when building Compress-Raw-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-Raw-Zlib. To check if a
	newer version of Compress-Raw-Zlib is available run this from the command
	prompt

	C:\> ppm verify -upgrade Compress-Raw-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-Raw-Zlib using the CPAN shell.
	This is because the Compress-Raw-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-Raw-Zlib manually using the
	instructions given at the start of this file.

	FEEDBACK
	--------

	How to report a problem with Compress-Raw-Zlib.

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

	1. The Versions of everything relevant.
	This includes:

	a. 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.

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

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

	If you are running windows use this

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

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

	$VERSION = "2.048" ;

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

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

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

	2. If you are having problems building Compress-Raw-Zlib, send me a
	complete log of what happened. Start by unpacking the Compress-Raw-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>