ext/Compress/Zlib/README

   1                                  Compress::Zlib
   2
   3                                   Version 1.35
   4
   5                                   18 July 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>