ext/Compress/Raw/Zlib/README

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