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