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