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