cpan/Compress-Raw-Zlib/README

   1
   2                              Compress-Raw-Zlib
   3
   4                              Version 2.037
   5
   6                               22nd June 2011
   7
   8        Copyright (c) 2005-2011 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.5.
  14                   These files are Copyright(C) 1995-2010
  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.5,
 103   it will create a directory called zlib-1.2.5.
 104
 105   Now set the variables in the file config.in as follows (if the version
 106   you have fetched isn't 1.2.5, change the INCLUDE and LIB
 107   variables appropriately):
 108
 109       BUILD_ZLIB   = True
 110       INCLUDE      = ./zlib-1.2.5
 111       LIB          = ./zlib-1.2.5
 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.037" ;
 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>