ext/Compress/Raw/Zlib/README

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