Commit | Line | Data |
f4c6fd49 |
1 | Compress::Zlib |
2 | |
3 | Version 1.34 |
4 | |
5 | 30 January 2005 |
6 | |
7 | Copyright (c) 1995-2005 Paul Marquess. All rights reserved. |
8 | This program is free software; you can redistribute it and/or |
9 | modify it under the same terms as Perl itself. |
10 | |
11 | The directory zlib-src contains a subset of the source files copied |
12 | directly from zlib version 1.2.2. These files are Copyright(C) |
13 | 1995-2004 Jean-loup Gailly and Mark Adler. |
14 | Full source for the zlib library is available at |
15 | http://www.zlib.org |
16 | |
17 | |
18 | DESCRIPTION |
19 | ----------- |
20 | |
21 | This module provides a Perl interface to most of the zlib compression |
22 | library. For more details see the pod documentation embedded in the |
23 | file Zlib.pm. |
24 | |
25 | If you have downloaded this module in the expectation of manipulating the |
26 | contents of .zip files, you will need to fetch and build the Archive::Zip |
27 | module below once you have installed this one. |
28 | |
29 | http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz |
30 | |
31 | |
32 | PREREQUISITES |
33 | ------------- |
34 | |
35 | Before you can build Compress::Zlib you need to have the following |
36 | installed on your system: |
37 | |
38 | * A C compiler |
39 | |
40 | * Perl 5.004 or better. |
41 | |
42 | By default, Compress::Zlib will build its own private copy of the zlib |
43 | library. If you want to use a different version of zlib, follow the |
44 | instructions in the section called "Controlling the version of zlib used |
45 | by Compress::Zlib" later in this document. |
46 | |
47 | |
48 | BUILDING THE MODULE |
49 | ------------------- |
50 | |
51 | Assuming you have met all the prerequisites, the module can now be built |
52 | using this sequence of commands: |
53 | |
54 | perl Makefile.PL |
55 | make |
56 | make test |
57 | |
58 | |
59 | |
60 | INSTALLATION |
61 | ------------ |
62 | |
63 | To install Compress::Zlib, run the command below: |
64 | |
65 | make install |
66 | |
67 | UPDATES |
68 | ------- |
69 | |
70 | The most recent version of Compress::Zlib is always available at |
71 | |
72 | http://www.cpan.org/modules/by-module/Compress/ |
73 | |
74 | |
75 | |
76 | Controlling the version of zlib used by Compress::Zlib |
77 | ----------------------------------------------------- |
78 | |
79 | Compress::Zlib interfaces to the zlib compression library. There are |
80 | three options available to control which version/instance of the zlib |
81 | library is used: |
82 | |
83 | 1. Build a private copy of the zlib library using the zlib library |
84 | source that is included with this module. |
85 | This is the default and recommended option. |
86 | |
87 | 2. Build a private copy of the zlib library using a standard zlib |
88 | source distribution. |
89 | |
90 | 3. Use a pre-buiild zlib library. |
91 | |
92 | Note that if you intend to use either Option 2 or 3, you need to have |
93 | zlib version 1.0.6 or better. Although this module can build with old |
94 | versions of zlib, it is strongly recommended that you use the most recent |
95 | version of zlib available. |
96 | |
97 | |
98 | The contents of the file config.in are used to control which of the |
99 | three options is actually used. This file is used during the |
100 | |
101 | perl Makefile.PL |
102 | |
103 | step of the build, so remember to make any required changes to config.in |
104 | before building this module. |
105 | |
106 | |
107 | |
108 | Option 1 |
109 | -------- |
110 | |
111 | For option 1, edit the file config.in and set the variables in it |
112 | as follows: |
113 | |
114 | BUILD_ZLIB = True |
115 | INCLUDE = ./zlib-src |
116 | LIB = ./zlib-src |
117 | OLD_ZLIB = False |
118 | |
119 | |
120 | Option 2 |
121 | -------- |
122 | |
123 | For option 2, fetch a copy of the zlib source distribution from |
124 | http://www.zlib.org and unpack it into the Compress::Zlib source |
125 | directory. Assuming you have fetched zlib 1.1.4, it will create a |
126 | directory called zlib-1.1.4. |
127 | |
128 | Now set the variables in the file config.in as follows (if the version |
129 | you have fetched isn't 1.1.4, change the INCLUDE and LIB variables |
130 | appropriately): |
131 | |
132 | BUILD_ZLIB = True |
133 | INCLUDE = ./zlib-1.1.4 |
134 | LIB = ./zlib-1.1.4 |
135 | OLD_ZLIB = False |
136 | |
137 | |
138 | Option 3 |
139 | -------- |
140 | |
141 | For option 3, you need to find out where zlib is stored on your system. |
142 | There are two parts to this. |
143 | |
144 | First, find the directory where the zlib library is stored (some common |
145 | names for the library are libz.a and libz.so). Set the LIB variable in |
146 | the config.in file to that directory. |
147 | |
148 | Secondly, find the directory where the file zlib.h is stored. Now set |
149 | the INCLUDE variable in the config.in file to that directory. |
150 | |
151 | Next set BUILD_ZLIB to False |
152 | |
153 | Finally, if you are running zlib 1.0.5 or older, set the OLD_ZLIB |
154 | variable to True. Otherwise set it to False. |
155 | |
156 | As an example, if the zlib library on your system is in /usr/local/lib, |
157 | zlib.h is in /usr/local/include and zlib is more older than version |
158 | 1.0.5, the variables in config.in should be set as follows: |
159 | |
160 | BUILD_ZLIB = False |
161 | INCLUDE = /usr/local/include |
162 | LIB = /usr/local/lib |
163 | OLD_ZLIB = True |
164 | |
165 | |
166 | |
167 | |
168 | TROUBLESHOOTING |
169 | --------------- |
170 | |
171 | Undefined Symbol gzsetparams |
172 | ---------------------------- |
173 | |
174 | If you get the error shown below when you run the Compress::Zlib test |
175 | harness it probably means you are running a copy of zlib that is version |
176 | 1.0.5 or older. |
177 | |
178 | t/01version.........Can't load 'blib/arch/auto/Compress/Zlib/Zlib.so' for |
179 | module Compress::Zlib: blib/arch/auto/Compress/Zlib/Zlib.so: |
180 | undefined symbol: gzsetparams at ... |
181 | |
182 | There are two ways to fix this problem: |
183 | |
184 | 1. Upgrade to the latest version of zlib. |
185 | |
186 | 2. Edit config.in and set the OLD_ZLIB variable to True. |
187 | |
188 | |
189 | |
190 | Test Harness 01version fails |
191 | ---------------------------- |
192 | If the 01version test harness fails, and the problem isn't covered by |
193 | the scenario above, it probably means that you have two versions of zlib |
194 | installed on your system. |
195 | |
196 | Run the command below to see if this is indeed the case |
197 | |
198 | make test TEST_VERBOSE=1 TEST_FILES=t/01version.t |
199 | |
200 | Try removing the one you don't want to use and rebuild. |
201 | |
202 | |
203 | |
204 | |
205 | Solaris build fails with "language optional software package not installed" |
206 | --------------------------------------------------------------------------- |
207 | |
208 | If you are trying to build this module under Solaris and you get an |
209 | error message like this |
210 | |
211 | /usr/ucb/cc: language optional software package not installed |
212 | |
213 | it means that Perl cannot find the C compiler on your system. The cryptic |
214 | message is just Sun's way of telling you that you haven't bought their |
215 | C compiler. |
216 | |
217 | When you build a Perl module that needs a C compiler, the Perl build |
218 | system tries to use the same C compiler that was used to build perl |
219 | itself. In this case your Perl binary was built with a C compiler that |
220 | lived in /usr/ucb. |
221 | |
222 | To continue with building this module, you need to get a C compiler, |
223 | or tell Perl where your C compiler is, if you already have one. |
224 | |
225 | Assuming you have now got a C compiler, what you do next will be dependant |
226 | on what C compiler you have installed. If you have just installed Sun's |
227 | C compiler, you shouldn't have to do anything. Just try rebuilding |
228 | this module. |
229 | |
230 | If you have installed another C compiler, say gcc, you have to tell perl |
231 | how to use it instead of /usr/ucb/cc. |
232 | |
233 | This set of options seems to work if you want to use gcc. Your mileage |
234 | may vary. |
235 | |
236 | perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " |
237 | make test |
238 | |
239 | If that doesn't work for you, it's time to make changes to the Makefile |
240 | by hand. Good luck! |
241 | |
242 | |
243 | |
244 | |
245 | Solaris build fails with "gcc: unrecognized option `-KPIC'" |
246 | ----------------------------------------------------------- |
247 | |
248 | You are running Solaris and you get an error like this when you try to |
249 | build this Perl module |
250 | |
251 | gcc: unrecognized option `-KPIC' |
252 | |
253 | This symptom usually means that you are using a Perl binary that has been |
254 | built with the Sun C compiler, but you are using gcc to build this module. |
255 | |
256 | When Perl builds modules that need a C compiler, it will attempt to use |
257 | the same C compiler and command line options that was used to build perl |
258 | itself. In this case "-KPIC" is a valid option for the Sun C compiler, |
259 | but not for gcc. The equivalent option for gcc is "-fPIC". |
260 | |
261 | The solution is either: |
262 | |
263 | 1. Build both Perl and this module with the same C compiler, either |
264 | by using the Sun C compiler for both or gcc for both. |
265 | |
266 | 2. Try generating the Makefile for this module like this perl |
267 | |
268 | perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc |
269 | make test |
270 | |
271 | This second option seems to work when mixing a Perl binary built |
272 | with the Sun C compiler and this module built with gcc. Your |
273 | mileage may vary. |
274 | |
275 | |
276 | |
277 | HP-UX Notes |
278 | ----------- |
279 | |
280 | I've had a report that when building Compress::Zlib under HP-UX that it |
281 | is necessary to have first built the zlib library with the -fpic option. |
282 | |
283 | |
284 | |
285 | Linux Notes |
286 | ----------- |
287 | |
288 | Although most Linux distributions already come with zlib, some people |
289 | report getting this error when they try to build this module: |
290 | |
291 | $ make |
292 | cp Zlib.pm blib/lib/Compress/Zlib.pm |
293 | AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib) |
294 | /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 |
295 | 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 |
296 | Zlib.xs:25:19: zlib.h: No such file or directory |
297 | make: *** [Zlib.o] Error 1 |
298 | |
299 | This usually means that you have not installed the development RPM |
300 | for zlib. Check for an RPM that start with "zlib-devel" in your Linux |
301 | distribution. |
302 | |
303 | |
304 | |
305 | |
306 | Win32 Notes |
307 | ----------- |
308 | |
309 | If you are running Activestate Perl (from http://www.activestate.com), |
310 | it ships with a pre-compiled version of Compress::Zlib. To check if a |
311 | newer version of Compress::Zlib is available run this from the command |
312 | prompt |
313 | |
314 | C:\> ppm verify -upgrade Compress-Zlib |
315 | |
316 | |
317 | If you are not running Activestate Perl and you don't have access |
318 | to a C compiler, you will not be able to build and install this module. |
319 | |
320 | |
321 | |
322 | |
323 | Win32 & Cygwin Notes |
324 | -------------------- |
325 | |
326 | It is not possible to install Compress::Zlib using the CPAN shell. |
327 | This is because the Compress::Zlib DLL is itself used by the CPAN shell |
328 | and it is impossible to remove a DLL while it is already loaded under |
329 | Windows. |
330 | |
331 | The workaround is to install Compress::Zlib manually using the |
332 | instructions given at the start of this file. |
333 | |
334 | |
335 | |
336 | Mac OX X Notes |
337 | -------------- |
338 | |
339 | Some versions of Mac OS X are failing a number of the tests in the |
340 | 06gzdopen.t test harness. |
341 | |
342 | The functionality being exercised in these tests is checking that it is |
343 | possible to call gzopen with an existing Perl filenhandle instead of a |
344 | filename. For some reason it does not seem possible to extract a |
345 | numeric file descriptor (using fileno) from a FILE* and then make use |
346 | of it. |
347 | |
348 | If you happen to now how to fix for this, I would like to hear from you. |
349 | |
350 | In the meantime, a workaround that has been reported to me is to use fink, |
351 | available at http://fink.sourceforge.net |
352 | |
353 | |
354 | |
355 | FEEDBACK |
356 | -------- |
357 | |
358 | How to report a problem with Compress::Zlib. |
359 | |
360 | To help me help you, I need all of the following information: |
361 | |
362 | 1. The *complete* output from running this |
363 | |
364 | perl -V |
365 | |
366 | Do not edit the output in any way. |
367 | Note, I want you to run "perl -V" and NOT "perl -v". |
368 | |
369 | If your perl does not understand the "-V" option it is too |
370 | old. This module needs Perl version 5.004 or better. |
371 | |
372 | 2. The version of Compress::Zlib you have. |
373 | If you have successfully installed Compress::Zlib, this one-liner |
374 | will tell you: |
375 | |
376 | perl -MCompress::Zlib -e 'print qq[ver $Compress::Zlib::VERSION\n]' |
377 | |
378 | If you are running windows use this |
379 | |
380 | perl -MCompress::Zlib -e "print qq[ver $Compress::Zlib::VERSION\n]" |
381 | |
382 | If you haven't installed Compress::Zlib then search Compress::Zlib.pm |
383 | for a line like this: |
384 | |
385 | $VERSION = "1.05" ; |
386 | |
387 | 3. The version of zlib you have installed. |
388 | If you have successfully installed Compress::Zlib, this one-liner |
389 | will tell you: |
390 | |
391 | perl -MCompress::Zlib -e "print q[zlib ver ]. Compress::Zlib::ZLIB_VERSION.qq[\n]" |
392 | |
393 | |
394 | If not, look at the beginning of the file zlib.h. |
395 | |
396 | 4. If you are having problems building Compress::Zlib, send me a |
397 | complete log of what happened. Start by unpacking the Compress:Zlib |
398 | module into a fresh directory and keep a log of all the steps |
399 | |
400 | [edit config.in, if necessary] |
401 | perl Makefile.PL |
402 | make |
403 | make test TEST_VERBOSE=1 |
404 | |
405 | |
406 | Paul Marquess <pmqs@cpan.org> |