ext/Compress/Zlib/README

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