ext/Compress/Raw/Zlib/README

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