git.maemo.org Git - dh-make-perl/blob - dev/arm/libcompress-raw-zlib-perl/libcompress-raw-zlib-perl-2.012/README

   1
   2                              Compress-Raw-Zlib
   3
   4                              Version 2.012
   5
   6                               15th July 2008
   7
   8        Copyright (c) 2005-2008 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.3.
  14                   These files are Copyright(C) 1995-2005
  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.3,
 103   it will create a directory called zlib-1.2.3.
 104
 105   Now set the variables in the file config.in as follows (if the version
 106   you have fetched isn't 1.2.3, change the INCLUDE and LIB
 107   variables appropriately):
 108
 109       BUILD_ZLIB   = True
 110       INCLUDE      = ./zlib-1.2.3
 111       LIB          = ./zlib-1.2.3
 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 Solaris build fails with "language optional software package not installed"
 181 ---------------------------------------------------------------------------
 182
 183 If you are trying to build this module under Solaris and you get an
 184 error message like this
 185
 186     /usr/ucb/cc: language optional software package not installed
 187
 188 it means that Perl cannot find the C compiler on your system. The cryptic
 189 message is just Sun's way of telling you that you haven't bought their
 190 C compiler.
 191
 192 When you build a Perl module that needs a C compiler, the Perl build
 193 system tries to use the same C compiler that was used to build perl
 194 itself. In this case your Perl binary was built with a C compiler that
 195 lived in /usr/ucb.
 196
 197 To continue with building this module, you need to get a C compiler,
 198 or tell Perl where your C compiler is, if you already have one.
 199
 200 Assuming you have now got a C compiler, what you do next will be dependent
 201 on what C compiler you have installed. If you have just installed Sun's
 202 C compiler, you shouldn't have to do anything. Just try rebuilding
 203 this module.
 204
 205 If you have installed another C compiler, say gcc, you have to tell perl
 206 how to use it instead of /usr/ucb/cc.
 207
 208 This set of options seems to work if you want to use gcc. Your mileage
 209 may vary.
 210
 211     perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" "
 212     make test
 213
 214 If that doesn't work for you, it's time to make changes to the Makefile
 215 by hand. Good luck!
 216
 217 Solaris build fails with "gcc: unrecognized option `-KPIC'"
 218 -----------------------------------------------------------
 219
 220 You are running Solaris and you get an error like this when you try to
 221 build this Perl module
 222
 223     gcc: unrecognized option `-KPIC'
 224
 225 This symptom usually means that you are using a Perl binary that has been
 226 built with the Sun C compiler, but you are using gcc to build this module.
 227
 228 When Perl builds modules that need a C compiler, it will attempt to use
 229 the same C compiler and command line options that was used to build perl
 230 itself. In this case "-KPIC" is a valid option for the Sun C compiler,
 231 but not for gcc. The equivalent option for gcc is "-fPIC".
 232
 233 The solution is either:
 234
 235     1. Build both Perl and this module with the same C compiler, either
 236        by using the Sun C compiler for both or gcc for both.
 237
 238     2. Try generating the Makefile for this module like this perl
 239
 240            perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc
 241            make test
 242
 243        This second option seems to work when mixing a Perl binary built
 244        with the Sun C compiler and this module built with gcc. Your
 245        mileage may vary.
 246
 247 HP-UX Notes
 248 -----------
 249
 250 I've had a report that when building Compress-Raw-Zlib under HP-UX that it
 251 is necessary to have first built the zlib library with the -fpic
 252 option.
 253
 254 Linux Notes
 255 -----------
 256
 257 Although most Linux distributions already come with zlib, some
 258 people report getting this error when they try to build this module:
 259
 260 $ make
 261 cp Zlib.pm blib/lib/Compress/Zlib.pm
 262 AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib)
 263 /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
 264 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
 265 Zlib.xs:25:19: zlib.h: No such file or directory
 266 make: *** [Zlib.o] Error 1
 267
 268 This usually means that you have not installed the development RPM
 269 for zlib. Check for an RPM that start with "zlib-devel" in your Linux
 270 distribution.
 271
 272 Win32 Notes
 273 -----------
 274
 275 If you are running Activestate Perl (from http://www.activestate.com),
 276 it ships with a pre-compiled version of Compress-Raw-Zlib. To check if a
 277 newer version of Compress-Raw-Zlib is available run this from the command
 278 prompt
 279
 280     C:\> ppm verify -upgrade Compress-Zlib
 281
 282 If you are not running Activestate Perl and you don't have access
 283 to a C compiler, you will not be able to build and install this module.
 284
 285 Win32 & Cygwin Notes
 286 --------------------
 287
 288 It is not possible to install Compress-Raw-Zlib using the CPAN shell.
 289 This is because the Compress-Raw-Zlib DLL is itself used by the CPAN shell
 290 and it is impossible to remove a DLL while it is already loaded under
 291 Windows.
 292
 293 The workaround is to install Compress-Raw-Zlib manually using the
 294 instructions given at the start of this file.
 295
 296 FEEDBACK
 297 --------
 298
 299 How to report a problem with Compress-Raw-Zlib.
 300
 301 To help me help you, I need all of the following information:
 302
 303  1. The Versions of everything relevant.
 304     This includes:
 305
 306      a. The *complete* output from running this
 307
 308             perl -V
 309
 310         Do not edit the output in any way.
 311         Note, I want you to run "perl -V" and NOT "perl -v".
 312
 313         If your perl does not understand the "-V" option it is too
 314         old. This module needs Perl version 5.004 or better.
 315
 316      b. The version of Compress-Raw-Zlib you have.
 317         If you have successfully installed Compress-Raw-Zlib, this one-liner
 318         will tell you:
 319
 320            perl -MCompress::Raw::Zlib -e 'print qq[ver $Compress::Raw::Zlib::VERSION\n]'
 321
 322         If you are  running windows use this
 323
 324            perl -MCompress::Raw::Zlib -e "print qq[ver $Compress::Raw::Zlib::VERSION\n]"
 325
 326         If you haven't installed Compress-Raw-Zlib then search Compress::Raw::Zlib.pm
 327         for a line like this:
 328
 329           $VERSION = "2.012" ;
 330
 331      c. The version of zlib you have used.
 332         If you have successfully installed Compress-Raw-Zlib, this one-liner
 333         will tell you:
 334
 335           perl -MCompress::Raw::Zlib -e "print q[zlib ver ]. Compress::Raw::Zlib::ZLIB_VERSION.qq[\n]"
 336
 337         If not, look at the beginning of the file zlib.h.
 338
 339  2. If you are having problems building Compress-Raw-Zlib, send me a
 340     complete log of what happened. Start by unpacking the Compress-Raw-Zlib
 341     module into a fresh directory and keep a log of all the steps
 342
 343         [edit config.in, if necessary]
 344         perl Makefile.PL
 345         make
 346         make test TEST_VERBOSE=1
 347
 348 Paul Marquess <pmqs@cpan.org>