8 Copyright (c) 1995-2005 Paul Marquess. All rights reserved.
9 This program is free software; you can redistribute it
10 and/or modify it under the same terms as Perl itself.
13 The directory zlib-src contains a subset of the
14 source files copied directly from zlib version 1.2.3.
15 These files are Copyright(C) 1995-2005
16 Jean-loup Gailly and Mark Adler.
17 Full source for the zlib library is available at
24 DO NOT use in production code.
25 Please report any problems.
30 This module provides a Perl interface to most of the zlib compression
31 library. For more details see the pod documentation embedded in the
34 If you have downloaded this module in the expectation of manipulating the
35 contents of .zip files, you will need to fetch and build the Archive::Zip
36 module below once you have installed this one.
38 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
46 Before you can build Compress::Zlib you need to have the following
47 installed on your system:
51 * Perl 5.004 or better.
53 By default, Compress::Zlib will build its own private copy of the zlib
54 library. If you want to use a different version of zlib, follow the
55 instructions in the section called "Controlling the version of zlib used
56 by Compress::Zlib" later in this document.
62 Assuming you have met all the prerequisites, the module can now be built
63 using this sequence of commands:
74 To install Compress::Zlib, run the command below:
81 The most recent version of Compress::Zlib is always available at
83 http://www.cpan.org/modules/by-module/Compress/
87 Controlling the version of zlib used by Compress::Zlib
88 -----------------------------------------------------
90 Compress::Zlib interfaces to the zlib compression library. There are
91 three options available to control which version/instance of the zlib
94 1. Build a private copy of the zlib library using the zlib library
95 source that is included with this module.
96 This is the default and recommended option.
98 2. Build a private copy of the zlib library using a standard zlib
101 3. Use a pre-built zlib library.
103 Note that if you intend to use either Option 2 or 3, you need to have
104 zlib version 1.0.5 or better.
107 The contents of the file config.in are used to control which of the
108 three options is actually used. This file is read during the
112 step of the build, so remember to make any required changes to config.in
113 before building this module.
120 For option 1, edit the file config.in and set the variables in it
127 GZIP_OS_CODE = AUTO_DETECT
133 For option 2, fetch a copy of the zlib source distribution from
134 http://www.zlib.org and unpack it into the Compress::Zlib source
135 directory. Assuming you have fetched zlib 1.2.3, it will create a
136 directory called zlib-1.2.3.
138 Now set the variables in the file config.in as follows (if the version
139 you have fetched isn't 1.2.3, change the INCLUDE and LIB variables
143 INCLUDE = ./zlib-1.2.3
146 GZIP_OS_CODE = AUTO_DETECT
152 For option 3, you need to find out where zlib is stored on your system.
153 There are two parts to this.
155 First, find the directory where the zlib library is stored (some common
156 names for the library are libz.a and libz.so). Set the LIB variable in
157 the config.in file to that directory.
159 Secondly, find the directory where the file zlib.h is stored. Now set
160 the INCLUDE variable in the config.in file to that directory.
162 Next set BUILD_ZLIB to False.
164 Finally, if you are running zlib 1.0.5 or older, set the OLD_ZLIB
165 variable to True. Otherwise set it to False.
167 As an example, if the zlib library on your system is in /usr/local/lib,
168 zlib.h is in /usr/local/include and zlib is more recent than version
169 1.0.5, the variables in config.in should be set as follows:
172 INCLUDE = /usr/local/include
175 GZIP_OS_CODE = AUTO_DETECT
178 Setting the Gzip OS Code
179 ------------------------
181 Every gzip stream stores a byte in its header to identify the Operating System
182 that was used to create the gzip stream. When you build Compress::Zlib it will
183 attempt to determine the value that is correct for your Operating System. This
184 will then be used by IO::Gzip as the default value for the OS byte in all gzip
187 The variable GZIP_OS_CODE in the config.in file controls the setting of this
188 value when building Compress::Zlib. If GZIP_OS_CODE is set to AUTO_DETECT,
189 Compress::Zlib will attempt to determine the correct value for your Operating
192 Alternatively, you can override auto-detection of the default OS code and
193 explicitly set it yourself. Set the GZIP_OS_CODE variable in the config.in file
194 to be a number between 0 and 255. For example
198 See RFC 1952 for valid OS codes that can be used.
200 If you are running one of the less popular Operating Systems, it could be that
201 the default value picked by this module is incorrect or the default value (3)
202 is used when there is a better value available. When Compress::Zlib cannot
203 determine what operating system you are running, it will use the default value
206 If you find you have to change this value, because you think the value auto
207 detected is incorrect, please take a few moments to contact the author of this
214 Undefined Symbol gzsetparams
215 ----------------------------
217 If you get the error shown below when you run the Compress::Zlib test
218 harness it probably means you are running a copy of zlib that is version
221 t/01version.........Can't load 'blib/arch/auto/Compress/Zlib/Zlib.so' for
222 module Compress::Zlib: blib/arch/auto/Compress/Zlib/Zlib.so:
223 undefined symbol: gzsetparams at ...
225 There are two ways to fix this problem:
227 1. Upgrade to the latest version of zlib.
229 2. Edit config.in and set the OLD_ZLIB variable to True.
233 Test Harness 01version fails
234 ----------------------------
235 If the 01version test harness fails, and the problem isn't covered by
236 the scenario above, it probably means that you have two versions of zlib
237 installed on your system.
239 Run the command below to see if this is indeed the case
241 make test TEST_VERBOSE=1 TEST_FILES=t/01version.t
243 Try removing the one you don't want to use and rebuild.
247 Solaris build fails with "language optional software package not installed"
248 ---------------------------------------------------------------------------
250 If you are trying to build this module under Solaris and you get an
251 error message like this
253 /usr/ucb/cc: language optional software package not installed
255 it means that Perl cannot find the C compiler on your system. The cryptic
256 message is just Sun's way of telling you that you haven't bought their
259 When you build a Perl module that needs a C compiler, the Perl build
260 system tries to use the same C compiler that was used to build perl
261 itself. In this case your Perl binary was built with a C compiler that
264 To continue with building this module, you need to get a C compiler,
265 or tell Perl where your C compiler is, if you already have one.
267 Assuming you have now got a C compiler, what you do next will be dependent
268 on what C compiler you have installed. If you have just installed Sun's
269 C compiler, you shouldn't have to do anything. Just try rebuilding
272 If you have installed another C compiler, say gcc, you have to tell perl
273 how to use it instead of /usr/ucb/cc.
275 This set of options seems to work if you want to use gcc. Your mileage
278 perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" "
281 If that doesn't work for you, it's time to make changes to the Makefile
287 Solaris build fails with "gcc: unrecognized option `-KPIC'"
288 -----------------------------------------------------------
290 You are running Solaris and you get an error like this when you try to
291 build this Perl module
293 gcc: unrecognized option `-KPIC'
295 This symptom usually means that you are using a Perl binary that has been
296 built with the Sun C compiler, but you are using gcc to build this module.
298 When Perl builds modules that need a C compiler, it will attempt to use
299 the same C compiler and command line options that was used to build perl
300 itself. In this case "-KPIC" is a valid option for the Sun C compiler,
301 but not for gcc. The equivalent option for gcc is "-fPIC".
303 The solution is either:
305 1. Build both Perl and this module with the same C compiler, either
306 by using the Sun C compiler for both or gcc for both.
308 2. Try generating the Makefile for this module like this perl
310 perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc
313 This second option seems to work when mixing a Perl binary built
314 with the Sun C compiler and this module built with gcc. Your
318 The t/17isize Test Suite
319 ------------------------
321 This test suite checks that Compress::Zlib can cope with gzip files
322 that are larger than 2^32 bytes.
324 By default these test are NOT run when you do a "make test". If you
325 really want to run them, you need to execute "make longtest".
327 Be warned though -- this test suite can take hours to run on a slow box.
329 Also, due to the way the tests are constructed, some architectures will
330 run out of memory during these test. This should not be considered a bug
331 in the Compress::Zlib module.
338 I've had a report that when building Compress::Zlib under HP-UX that it
339 is necessary to have first built the zlib library with the -fpic option.
346 Although most Linux distributions already come with zlib, some people
347 report getting this error when they try to build this module:
350 cp Zlib.pm blib/lib/Compress/Zlib.pm
351 AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib)
352 /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
353 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
354 Zlib.xs:25:19: zlib.h: No such file or directory
355 make: *** [Zlib.o] Error 1
357 This usually means that you have not installed the development RPM
358 for zlib. Check for an RPM that start with "zlib-devel" in your Linux
367 If you are running Activestate Perl (from http://www.activestate.com),
368 it ships with a pre-compiled version of Compress::Zlib. To check if a
369 newer version of Compress::Zlib is available run this from the command
372 C:\> ppm verify -upgrade Compress-Zlib
375 If you are not running Activestate Perl and you don't have access
376 to a C compiler, you will not be able to build and install this module.
384 It is not possible to install Compress::Zlib using the CPAN shell.
385 This is because the Compress::Zlib DLL is itself used by the CPAN shell
386 and it is impossible to remove a DLL while it is already loaded under
389 The workaround is to install Compress::Zlib manually using the
390 instructions given at the start of this file.
397 How to report a problem with Compress::Zlib.
399 To help me help you, I need all of the following information:
401 1. The *complete* output from running this
405 Do not edit the output in any way.
406 Note, I want you to run "perl -V" and NOT "perl -v".
408 If your perl does not understand the "-V" option it is too
409 old. This module needs Perl version 5.004 or better.
411 2. The version of Compress::Zlib you have.
412 If you have successfully installed Compress::Zlib, this one-liner
415 perl -MCompress::Zlib -e 'print qq[ver $Compress::Zlib::VERSION\n]'
417 If you are running windows use this
419 perl -MCompress::Zlib -e "print qq[ver $Compress::Zlib::VERSION\n]"
421 If you haven't installed Compress::Zlib then search Compress::Zlib.pm
422 for a line like this:
426 3. The version of zlib you have installed.
427 If you have successfully installed Compress::Zlib, this one-liner
430 perl -MCompress::Zlib -e "print q[zlib ver ]. Compress::Zlib::ZLIB_VERSION.qq[\n]"
433 If not, look at the beginning of the file zlib.h.
435 4. If you are having problems building Compress::Zlib, send me a
436 complete log of what happened. Start by unpacking the Compress:Zlib
437 module into a fresh directory and keep a log of all the steps
439 [edit config.in, if necessary]
442 make test TEST_VERBOSE=1
445 Paul Marquess <pmqs@cpan.org>