Commit | Line | Data |
25f0751f |
1 | |
2 | Compress::Raw::Zlib |
3 | |
63ad731d |
4 | Version 2.001 |
25f0751f |
5 | |
63ad731d |
6 | 1st November 2006 |
25f0751f |
7 | |
8 | |
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. |
12 | |
13 | |
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 |
19 | http://www.zlib.org |
20 | |
21 | |
22 | |
25f0751f |
23 | DESCRIPTION |
24 | ----------- |
25 | |
26 | |
27 | This module provides a Perl interface to the zlib compression library. |
28 | |
29 | |
30 | |
31 | |
32 | |
33 | PREREQUISITES |
34 | ------------- |
35 | |
36 | Before you can build Compress::Raw::Zlib you need to have the following |
37 | installed on your system: |
38 | |
39 | |
40 | * A C compiler |
41 | |
42 | * Perl 5.004 or better. |
43 | |
44 | |
45 | |
46 | By default, Compress::Raw::Zlib will build its own private copy of the |
47 | zlib library. If you want to use a different version of |
48 | zlib, follow the instructions in the section called |
49 | "Controlling the version of zlib used by Compress::Raw::Zlib" |
50 | later in this document. |
51 | |
52 | |
53 | |
54 | BUILDING THE MODULE |
55 | ------------------- |
56 | |
57 | Assuming you have met all the prerequisites, the module can now be built |
58 | using this sequence of commands: |
59 | |
60 | perl Makefile.PL |
61 | make |
62 | make test |
63 | |
64 | |
65 | |
66 | INSTALLATION |
67 | ------------ |
68 | |
69 | To install Compress::Raw::Zlib, run the command below: |
70 | |
71 | make install |
72 | |
73 | |
74 | |
75 | |
25f0751f |
76 | Controlling the version of zlib used by Compress::Raw::Zlib |
77 | ---------------------------------------------------------- |
78 | |
79 | Compress::Raw::Zlib interfaces to the zlib compression library. There |
80 | are three options available to control which version/instance of the |
81 | zlib library is used: |
82 | |
83 | 1. Build a private copy of the zlib library using the |
84 | zlib library 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 |
88 | zlib source distribution. |
89 | |
90 | 3. Use a pre-built 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.5 or better. |
94 | |
95 | |
96 | The contents of the file config.in are used to control which of the |
97 | three options is actually used. This file is read during the |
98 | |
99 | perl Makefile.PL |
100 | |
101 | step of the build, so remember to make any required changes to config.in |
102 | before building this module. |
103 | |
104 | |
105 | |
106 | Option 1 |
107 | -------- |
108 | |
109 | For option 1, edit the file config.in and set the variables in it |
110 | as follows: |
111 | |
112 | BUILD_ZLIB = True |
113 | INCLUDE = ./zlib-src |
114 | LIB = ./zlib-src |
115 | OLD_ZLIB = False |
116 | GZIP_OS_CODE = AUTO_DETECT |
117 | |
118 | |
119 | Option 2 |
120 | -------- |
121 | |
122 | For option 2, fetch a copy of the zlib source distribution from |
123 | http://www.zlib.org and unpack it into the Compress::Raw::Zlib source |
124 | directory. Assuming you have fetched zlib 1.2.3, |
125 | it will create a directory called zlib-1.2.3. |
126 | |
127 | Now set the variables in the file config.in as follows (if the version |
128 | you have fetched isn't 1.2.3, change the INCLUDE and LIB |
129 | variables appropriately): |
130 | |
131 | BUILD_ZLIB = True |
132 | INCLUDE = ./zlib-1.2.3 |
133 | LIB = ./zlib-1.2.3 |
134 | OLD_ZLIB = False |
135 | GZIP_OS_CODE = AUTO_DETECT |
136 | |
137 | |
138 | Option 3 |
139 | -------- |
140 | |
141 | For option 3, you need to find out where zlib is stored on your |
142 | system. There are two parts to this. |
143 | |
144 | First, find the directory where the zlib library is stored (some |
145 | common names for the library are libz.a and libz.so). Set the LIB variable |
146 | in 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 |
157 | /usr/local/lib, zlib.h is in /usr/local/include and zlib is more |
158 | recent than version 1.0.5, the variables in config.in should be set as |
159 | follows: |
160 | |
161 | BUILD_ZLIB = False |
162 | INCLUDE = /usr/local/include |
163 | LIB = /usr/local/lib |
164 | OLD_ZLIB = False |
165 | GZIP_OS_CODE = AUTO_DETECT |
166 | |
167 | |
168 | Setting the Gzip OS Code |
169 | ------------------------ |
170 | |
171 | Every gzip stream stores a byte in its header to identify the Operating |
172 | System that was used to create the gzip stream. When you build |
173 | Compress::Raw::Zlib it will attempt to determine the value that is correct for |
174 | your Operating System. This will then be used by IO::Gzip as the default |
175 | value for the OS byte in all gzip headers it creates. |
176 | |
177 | The variable GZIP_OS_CODE in the config.in file controls the setting of |
178 | this value when building Compress::Raw::Zlib. If GZIP_OS_CODE is set to |
179 | AUTO_DETECT, Compress::Raw::Zlib will attempt to determine the correct value for |
180 | your Operating System. |
181 | |
182 | Alternatively, you can override auto-detection of the default OS code and |
183 | explicitly set it yourself. Set the GZIP_OS_CODE variable in the config.in |
184 | file to be a number between 0 and 255. For example |
185 | |
186 | GZIP_OS_CODE = 3 |
187 | |
188 | See RFC 1952 for valid OS codes that can be used. |
189 | |
190 | If you are running one of the less popular Operating Systems, it is |
191 | possible that the default value picked by this module is incorrect or the |
192 | default value (3) is used when there is a better value available. When |
193 | Compress::Raw::Zlib cannot determine what operating system you are running, it |
194 | will use the default value 3 for the OS code. |
195 | |
196 | If you find you have to change this value, because you think the value auto |
197 | detected is incorrect, please take a few moments to contact the author of |
198 | this module. |
199 | |
200 | |
201 | |
202 | TROUBLESHOOTING |
203 | --------------- |
204 | |
205 | |
206 | |
207 | |
208 | |
209 | |
210 | |
211 | Solaris build fails with "language optional software package not installed" |
212 | --------------------------------------------------------------------------- |
213 | |
214 | If you are trying to build this module under Solaris and you get an |
215 | error message like this |
216 | |
217 | /usr/ucb/cc: language optional software package not installed |
218 | |
219 | it means that Perl cannot find the C compiler on your system. The cryptic |
220 | message is just Sun's way of telling you that you haven't bought their |
221 | C compiler. |
222 | |
223 | When you build a Perl module that needs a C compiler, the Perl build |
224 | system tries to use the same C compiler that was used to build perl |
225 | itself. In this case your Perl binary was built with a C compiler that |
226 | lived in /usr/ucb. |
227 | |
228 | To continue with building this module, you need to get a C compiler, |
229 | or tell Perl where your C compiler is, if you already have one. |
230 | |
231 | Assuming you have now got a C compiler, what you do next will be dependent |
232 | on what C compiler you have installed. If you have just installed Sun's |
233 | C compiler, you shouldn't have to do anything. Just try rebuilding |
234 | this module. |
235 | |
236 | If you have installed another C compiler, say gcc, you have to tell perl |
237 | how to use it instead of /usr/ucb/cc. |
238 | |
239 | This set of options seems to work if you want to use gcc. Your mileage |
240 | may vary. |
241 | |
242 | perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " |
243 | make test |
244 | |
245 | If that doesn't work for you, it's time to make changes to the Makefile |
246 | by hand. Good luck! |
247 | |
248 | |
249 | |
250 | |
251 | Solaris build fails with "gcc: unrecognized option `-KPIC'" |
252 | ----------------------------------------------------------- |
253 | |
254 | You are running Solaris and you get an error like this when you try to |
255 | build this Perl module |
256 | |
257 | gcc: unrecognized option `-KPIC' |
258 | |
259 | This symptom usually means that you are using a Perl binary that has been |
260 | built with the Sun C compiler, but you are using gcc to build this module. |
261 | |
262 | When Perl builds modules that need a C compiler, it will attempt to use |
263 | the same C compiler and command line options that was used to build perl |
264 | itself. In this case "-KPIC" is a valid option for the Sun C compiler, |
265 | but not for gcc. The equivalent option for gcc is "-fPIC". |
266 | |
267 | The solution is either: |
268 | |
269 | 1. Build both Perl and this module with the same C compiler, either |
270 | by using the Sun C compiler for both or gcc for both. |
271 | |
272 | 2. Try generating the Makefile for this module like this perl |
273 | |
274 | perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc |
275 | make test |
276 | |
277 | This second option seems to work when mixing a Perl binary built |
278 | with the Sun C compiler and this module built with gcc. Your |
279 | mileage may vary. |
280 | |
281 | HP-UX Notes |
282 | ----------- |
283 | |
284 | I've had a report that when building Compress::Raw::Zlib under HP-UX that it |
285 | is necessary to have first built the zlib library with the -fpic |
286 | option. |
287 | |
288 | |
289 | |
290 | |
291 | |
292 | Linux Notes |
293 | ----------- |
294 | |
295 | Although most Linux distributions already come with zlib, some |
296 | people report getting this error when they try to build this module: |
297 | |
298 | $ make |
299 | cp Zlib.pm blib/lib/Compress/Zlib.pm |
300 | AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib) |
301 | /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 |
302 | 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 |
303 | Zlib.xs:25:19: zlib.h: No such file or directory |
304 | make: *** [Zlib.o] Error 1 |
305 | |
306 | This usually means that you have not installed the development RPM |
307 | for zlib. Check for an RPM that start with "zlib-devel" in your Linux |
308 | distribution. |
309 | |
310 | |
311 | |
312 | |
313 | Win32 Notes |
314 | ----------- |
315 | |
316 | If you are running Activestate Perl (from http://www.activestate.com), |
317 | it ships with a pre-compiled version of Compress::Raw::Zlib. To check if a |
318 | newer version of Compress::Raw::Zlib is available run this from the command |
319 | prompt |
320 | |
321 | C:\> ppm verify -upgrade Compress-Zlib |
322 | |
323 | |
324 | If you are not running Activestate Perl and you don't have access |
325 | to a C compiler, you will not be able to build and install this module. |
326 | |
327 | |
328 | |
329 | |
330 | Win32 & Cygwin Notes |
331 | -------------------- |
332 | |
333 | It is not possible to install Compress::Raw::Zlib using the CPAN shell. |
334 | This is because the Compress::Raw::Zlib DLL is itself used by the CPAN shell |
335 | and it is impossible to remove a DLL while it is already loaded under |
336 | Windows. |
337 | |
338 | The workaround is to install Compress::Raw::Zlib manually using the |
339 | instructions given at the start of this file. |
340 | |
341 | |
342 | FEEDBACK |
343 | -------- |
344 | |
345 | How to report a problem with Compress::Raw::Zlib. |
346 | |
347 | To help me help you, I need all of the following information: |
348 | |
349 | 1. The Versions of everything relevant. |
350 | This includes: |
351 | |
352 | a. The *complete* output from running this |
353 | |
354 | perl -V |
355 | |
356 | Do not edit the output in any way. |
357 | Note, I want you to run "perl -V" and NOT "perl -v". |
358 | |
359 | If your perl does not understand the "-V" option it is too |
360 | old. This module needs Perl version 5.004 or better. |
361 | |
362 | b. The version of Compress::Raw::Zlib you have. |
363 | If you have successfully installed Compress::Raw::Zlib, this one-liner |
364 | will tell you: |
365 | |
366 | perl -MCompress::Raw::Zlib -e 'print qq[ver $Compress::Raw::Zlib::VERSION\n]' |
367 | |
368 | If you areplete* output from running this |
369 | |
370 | perl -V |
371 | |
372 | Do not edit the output in any way. |
373 | Note, I want you to run "perl -V" and NOT "perl -v". |
374 | |
375 | If your perl does not understand the "-V" option it is too |
376 | old. This module needs Perl version 5.004 or better. |
377 | |
378 | b. The version of Compress::Raw::Zlib you have. |
379 | If you have successfully installed Compress::Raw::Zlib, this one-liner |
380 | will tell you: |
381 | |
382 | perl -MCompress::Raw::Zlib -e 'print qq[ver $Compress::Raw::Zlib::VERSION\n]' |
383 | |
384 | If you are running windows use this |
385 | |
386 | perl -MCompress::Raw::Zlib -e "print qq[ver $Compress::Raw::Zlib::VERSION\n]" |
387 | |
388 | If you haven't installed Compress::Raw::Zlib then search Compress::Raw::Zlib.pm |
389 | for a line like this: |
390 | |
391 | $VERSION = "1.05" ; |
392 | |
393 | |
394 | c. The version of zlib you have installed. |
395 | If you have successfully installed Compress::Raw::Zlib, this one-liner |
396 | will tell you: |
397 | |
398 | perl -MCompress::Raw::Zlib -e "print q[zlib ver ]. Compress::Raw::Zlib::ZLIB_VERSION.qq[\n]" |
399 | |
400 | |
401 | If not, look at the beginning of the file zlib.h. |
402 | |
403 | |
404 | 2. If you are having problems building Compress::Raw::Zlib, send me a |
405 | complete log of what happened. Start by unpacking the Compress::Raw::Zlib |
406 | module into a fresh directory and keep a log of all the steps |
407 | |
408 | [edit config.in, if necessary] |
409 | perl Makefile.PL |
410 | make |
411 | make test TEST_VERBOSE=1 |
412 | |
413 | |
414 | Paul Marquess <pmqs@cpan.org> |