9 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
10 This program is free software; you can redistribute it
11 and/or modify it under the same terms as Perl itself.
14 The directory zlib-src contains a subset of the
15 source files copied directly from zlib version 1.2.3.
16 These files are Copyright(C) 1995-2005
17 Jean-loup Gailly and Mark Adler.
18 Full source for the zlib library is available at
26 DO NOT use in production code.
27 Please report any problems.
33 This module provides a Perl interface to the zlib compression library.
42 Before you can build Compress::Raw::Zlib you need to have the following
43 installed on your system:
48 * Perl 5.004 or better.
52 By default, Compress::Raw::Zlib will build its own private copy of the
53 zlib library. If you want to use a different version of
54 zlib, follow the instructions in the section called
55 "Controlling the version of zlib used by Compress::Raw::Zlib"
56 later in this document.
63 Assuming you have met all the prerequisites, the module can now be built
64 using this sequence of commands:
75 To install Compress::Raw::Zlib, run the command below:
82 Controlling the version of zlib used by Compress::Raw::Zlib
83 ----------------------------------------------------------
85 Compress::Raw::Zlib interfaces to the zlib compression library. There
86 are three options available to control which version/instance of the
89 1. Build a private copy of the zlib library using the
90 zlib library source that is included with this module.
91 This is the default and recommended option.
93 2. Build a private copy of the zlib library using a standard
94 zlib source distribution.
96 3. Use a pre-built zlib library.
98 Note that if you intend to use either Option 2 or 3, you need to have
99 zlib version 1.0.5 or better.
102 The contents of the file config.in are used to control which of the
103 three options is actually used. This file is read during the
107 step of the build, so remember to make any required changes to config.in
108 before building this module.
115 For option 1, edit the file config.in and set the variables in it
122 GZIP_OS_CODE = AUTO_DETECT
128 For option 2, fetch a copy of the zlib source distribution from
129 http://www.zlib.org and unpack it into the Compress::Raw::Zlib source
130 directory. Assuming you have fetched zlib 1.2.3,
131 it will create a directory called zlib-1.2.3.
133 Now set the variables in the file config.in as follows (if the version
134 you have fetched isn't 1.2.3, change the INCLUDE and LIB
135 variables appropriately):
138 INCLUDE = ./zlib-1.2.3
141 GZIP_OS_CODE = AUTO_DETECT
147 For option 3, you need to find out where zlib is stored on your
148 system. There are two parts to this.
150 First, find the directory where the zlib library is stored (some
151 common names for the library are libz.a and libz.so). Set the LIB variable
152 in the config.in file to that directory.
154 Secondly, find the directory where the file zlib.h is stored. Now set
155 the INCLUDE variable in the config.in file to that directory.
157 Next set BUILD_ZLIB to False.
159 Finally, if you are running zlib 1.0.5 or older, set the OLD_ZLIB
160 variable to True. Otherwise set it to False.
162 As an example, if the zlib library on your system is in
163 /usr/local/lib, zlib.h is in /usr/local/include and zlib is more
164 recent than version 1.0.5, the variables in config.in should be set as
168 INCLUDE = /usr/local/include
171 GZIP_OS_CODE = AUTO_DETECT
174 Setting the Gzip OS Code
175 ------------------------
177 Every gzip stream stores a byte in its header to identify the Operating
178 System that was used to create the gzip stream. When you build
179 Compress::Raw::Zlib it will attempt to determine the value that is correct for
180 your Operating System. This will then be used by IO::Gzip as the default
181 value for the OS byte in all gzip headers it creates.
183 The variable GZIP_OS_CODE in the config.in file controls the setting of
184 this value when building Compress::Raw::Zlib. If GZIP_OS_CODE is set to
185 AUTO_DETECT, Compress::Raw::Zlib will attempt to determine the correct value for
186 your Operating System.
188 Alternatively, you can override auto-detection of the default OS code and
189 explicitly set it yourself. Set the GZIP_OS_CODE variable in the config.in
190 file to be a number between 0 and 255. For example
194 See RFC 1952 for valid OS codes that can be used.
196 If you are running one of the less popular Operating Systems, it is
197 possible that the default value picked by this module is incorrect or the
198 default value (3) is used when there is a better value available. When
199 Compress::Raw::Zlib cannot determine what operating system you are running, it
200 will use the default value 3 for the OS code.
202 If you find you have to change this value, because you think the value auto
203 detected is incorrect, please take a few moments to contact the author of
217 Solaris build fails with "language optional software package not installed"
218 ---------------------------------------------------------------------------
220 If you are trying to build this module under Solaris and you get an
221 error message like this
223 /usr/ucb/cc: language optional software package not installed
225 it means that Perl cannot find the C compiler on your system. The cryptic
226 message is just Sun's way of telling you that you haven't bought their
229 When you build a Perl module that needs a C compiler, the Perl build
230 system tries to use the same C compiler that was used to build perl
231 itself. In this case your Perl binary was built with a C compiler that
234 To continue with building this module, you need to get a C compiler,
235 or tell Perl where your C compiler is, if you already have one.
237 Assuming you have now got a C compiler, what you do next will be dependent
238 on what C compiler you have installed. If you have just installed Sun's
239 C compiler, you shouldn't have to do anything. Just try rebuilding
242 If you have installed another C compiler, say gcc, you have to tell perl
243 how to use it instead of /usr/ucb/cc.
245 This set of options seems to work if you want to use gcc. Your mileage
248 perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" "
251 If that doesn't work for you, it's time to make changes to the Makefile
257 Solaris build fails with "gcc: unrecognized option `-KPIC'"
258 -----------------------------------------------------------
260 You are running Solaris and you get an error like this when you try to
261 build this Perl module
263 gcc: unrecognized option `-KPIC'
265 This symptom usually means that you are using a Perl binary that has been
266 built with the Sun C compiler, but you are using gcc to build this module.
268 When Perl builds modules that need a C compiler, it will attempt to use
269 the same C compiler and command line options that was used to build perl
270 itself. In this case "-KPIC" is a valid option for the Sun C compiler,
271 but not for gcc. The equivalent option for gcc is "-fPIC".
273 The solution is either:
275 1. Build both Perl and this module with the same C compiler, either
276 by using the Sun C compiler for both or gcc for both.
278 2. Try generating the Makefile for this module like this perl
280 perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc
283 This second option seems to work when mixing a Perl binary built
284 with the Sun C compiler and this module built with gcc. Your
290 I've had a report that when building Compress::Raw::Zlib under HP-UX that it
291 is necessary to have first built the zlib library with the -fpic
301 Although most Linux distributions already come with zlib, some
302 people report getting this error when they try to build this module:
305 cp Zlib.pm blib/lib/Compress/Zlib.pm
306 AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib)
307 /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
308 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
309 Zlib.xs:25:19: zlib.h: No such file or directory
310 make: *** [Zlib.o] Error 1
312 This usually means that you have not installed the development RPM
313 for zlib. Check for an RPM that start with "zlib-devel" in your Linux
322 If you are running Activestate Perl (from http://www.activestate.com),
323 it ships with a pre-compiled version of Compress::Raw::Zlib. To check if a
324 newer version of Compress::Raw::Zlib is available run this from the command
327 C:\> ppm verify -upgrade Compress-Zlib
330 If you are not running Activestate Perl and you don't have access
331 to a C compiler, you will not be able to build and install this module.
339 It is not possible to install Compress::Raw::Zlib using the CPAN shell.
340 This is because the Compress::Raw::Zlib DLL is itself used by the CPAN shell
341 and it is impossible to remove a DLL while it is already loaded under
344 The workaround is to install Compress::Raw::Zlib manually using the
345 instructions given at the start of this file.
351 How to report a problem with Compress::Raw::Zlib.
353 To help me help you, I need all of the following information:
355 1. The Versions of everything relevant.
358 a. The *complete* output from running this
362 Do not edit the output in any way.
363 Note, I want you to run "perl -V" and NOT "perl -v".
365 If your perl does not understand the "-V" option it is too
366 old. This module needs Perl version 5.004 or better.
368 b. The version of Compress::Raw::Zlib you have.
369 If you have successfully installed Compress::Raw::Zlib, this one-liner
372 perl -MCompress::Raw::Zlib -e 'print qq[ver $Compress::Raw::Zlib::VERSION\n]'
374 If you areplete* output from running this
378 Do not edit the output in any way.
379 Note, I want you to run "perl -V" and NOT "perl -v".
381 If your perl does not understand the "-V" option it is too
382 old. This module needs Perl version 5.004 or better.
384 b. The version of Compress::Raw::Zlib you have.
385 If you have successfully installed Compress::Raw::Zlib, this one-liner
388 perl -MCompress::Raw::Zlib -e 'print qq[ver $Compress::Raw::Zlib::VERSION\n]'
390 If you are running windows use this
392 perl -MCompress::Raw::Zlib -e "print qq[ver $Compress::Raw::Zlib::VERSION\n]"
394 If you haven't installed Compress::Raw::Zlib then search Compress::Raw::Zlib.pm
395 for a line like this:
400 c. The version of zlib you have installed.
401 If you have successfully installed Compress::Raw::Zlib, this one-liner
404 perl -MCompress::Raw::Zlib -e "print q[zlib ver ]. Compress::Raw::Zlib::ZLIB_VERSION.qq[\n]"
407 If not, look at the beginning of the file zlib.h.
410 2. If you are having problems building Compress::Raw::Zlib, send me a
411 complete log of what happened. Start by unpacking the Compress::Raw::Zlib
412 module into a fresh directory and keep a log of all the steps
414 [edit config.in, if necessary]
417 make test TEST_VERBOSE=1
420 Paul Marquess <pmqs@cpan.org>