README

   1 ================================================================
   2 Copyright (c) 1999-2004 Arnar M. Hrafnkelsson. All rights reserved.
   3 Copyright (c) 2004-2009 Anthony Cook.
   4 This program is free software; you can redistribute it and/or
   5 modify it under the same terms as Perl itself.
   6 ================================================================
   7
   8 >> THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY WHATSOEVER <<
   9
  10 If you like or hate Imager, please let me know by sending mail
  11 to imager@imager.perl.org - I love feedback.
  12
  13 ================================================================
  14
  15
  16 ========================
  17 1. Patent infringements?
  18 ========================
  19
  20 Imager as such contains no patented algorithms.  The external
  21 libraries (which are not written by me) may or may not contain
  22 patented algorithms.  YOU ARE SOLELY RESPONSIBLE FOR OBTAINING
  23 LICENSE(S) TO USE SUCH LIBRARIES SHOULD YOU NEED ANY.
  24
  25
  26 ========================
  27 2. Compiling and testing
  28 ========================
  29
  30 Some care has been taken to make the installation as smooth as
  31 possible.  This is rather hard due to the difference between operating
  32 systems and site setups.  To get started just type
  33
  34 $ perl Makefile.PL
  35
  36 It should blurb out a list of which libraries were found and which
  37 not.  If you add a library to the machine after installing Imager it
  38 does not automatically become available in Imager.  It only uses the
  39 libraries that are found.  If the list of found libraries is not what
  40 you expected, then the Makefile.PL is either not searching in the
  41 right directories or your box does not have the libraries you think it
  42 does.  For a list of where to get the libraries have a look at
  43 3. External dependencies.  To widen the search path for libraries and
  44 include files set the IM_INCPATH and IM_LIBPATH variables.  The
  45 environment variables that matter when Makefile.PL is run are
  46
  47 IM_INCPATH      colon separated list of paths to extra include files
  48 IM_LIBPATH      colon separated list of paths to extra library files
  49
  50 IM_VERBOSE      turns on verbose mode for the library scanning and such
  51 IM_MANUAL       to manually select which libraries are used and which not
  52 IM_NOLOG        if true logging will not be compiled into the module
  53 IM_DEBUG_MALLOC if true malloc debugging will be compiled into the module
  54                 do not use IM_DEBUG_MALLOC in production - this slows
  55                 everything down
  56
  57 IM_CFLAGS       Extra flags to pass to the compiler
  58 IM_LFLAGS       Extra flags to pass to the linker
  59 IM_DFLAGS       Extra flags to pass to the preprocessor
  60
  61
  62
  63 When finding the libraries has been sorted out it's time for
  64
  65 $ make
  66
  67 and if that works then do
  68
  69 $ make test
  70
  71 If either fails do take a peek at the file errep.perl.  It's creates a
  72 file report.txt.  This is some information which will help me discover
  73 where the problem is so I can try to fix it in future releases.  If
  74 you find running it ok (just remember - no warranty!) please send the
  75 report.txt via email to imager@imager.perl.org.
  76
  77 Troubleshooting tips:
  78
  79 A common problem is that libgif/libungif are sometimes linked to the X
  80 libraries and then running the tests fails.  In that case something
  81 like:
  82
  83 $ IM_LFLAGS="-L/usr/X11R6/lib -lX11" perl Makefile.PL
  84
  85 Which simply sets the environment variables for the extra libraries
  86 to include the X libraries (which we do not use at all, but must
  87 included since libgif has been linked with it).
  88
  89 Otherwise you could just build giflib without any X11 dependencies:
  90
  91   # must be a clean tree
  92   cd giflib-4.1.4
  93   ./configure --without-x ...
  94
  95 Also note that libgif has a few bugs: You can run something like
  96
  97 $ perl -Iblib/lib -Iblib/arch t/t105gif.t
  98
  99 This way you can see what comments the test script prints out.
 100 t/t105gif.t checks for an bug in libgif and prints out a patch
 101 if that bug is present, note that this bug only affects the more
 102 "advanced" features of libgif.
 103
 104 If for some reason you have libungif-devel package installed but
 105 not libungif on RedHat then you will probably get lots of errors
 106 like undefined symbol: FreeSavedImages when running make test.
 107 Install libungif package to fix it.
 108
 109 Stock libungif 4.1.4 or later seems to fix all of the bugs, if you
 110 have a problem that version of linungif (or later), let us know and
 111 we'll look into it.
 112
 113 Imager needs to have a libtiff version of at least 3.5.5, but you
 114 should use a later version since some noticable bugs have been fixed.
 115
 116 For now you can either configure Imager manually (by setting the
 117 IM_MANUAL environment variable to 1, in sh:
 118
 119 $ IM_MANUAL=1 perl Makefile.PL
 120
 121 and simply say no to tiff support when asked if you want it, the same thing
 122 can be used to circumvent problems in gifs to get Imager going.
 123
 124 If it worked just continue with the installation as normally
 125 (with make install).
 126
 127 Freetype 1.x vs Freetype 2.x
 128 ----------------------------
 129
 130 These two libraries have some conflicting include file names, but as
 131 long as you don't put the Freetype 2.x freetype.h directory in the
 132 include path it should all work.
 133
 134 Put the directory containing ft2build.h in the include path, but not
 135 the directory containing the freetype 2.x freetype.h.
 136
 137 If you see compilation errors from font.c you've probably made the
 138 mistake of putting the Freetype 2.x freetype.h directory into the
 139 include path.
 140
 141 To see which directories should be in the include path, try:
 142
 143   freetype-config --cflags
 144
 145 Ideally, freetype-config should be in the PATH when building Imager
 146 with freetype 2.x support.
 147
 148
 149 Macintosh dfont and suitcase font support
 150 -----------------------------------------
 151
 152 Through Freetype 2.1, Imager can use Macintosh DFON (.dfont) fonts and
 153 suitcase font files.
 154
 155 If you want to be able to use more than just the first face in the
 156 font file though, you will need to configure freetype2 with the
 157 --with-old-mac-fonts option:
 158
 159   ./configure --with-old-mac-fonts
 160
 161 You can use the index option to get to the other font faces in the
 162 file:
 163
 164   # get the second face from $file
 165   my $font = Imager::Font->new(file=>$file, index=>1)
 166     or die Imager->errstr;
 167
 168 If you're using a suitcase font, you will also need to force the use
 169 of freetype 2 with the type argument:
 170
 171   my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
 172     or die Imager->errstr;
 173
 174
 175 ========================
 176 3. External dependencies
 177 ========================
 178
 179 Some hints about getting the Imager module to find the libraries it
 180 needs for specific features.
 181
 182 Most Linux distributions pre-package these.  For each library I've
 183 listed the Debian and Redhat package names.
 184
 185 For Debian or Debian based system, such as Ubuntu, you would run:
 186
 187   aptitude install package-name
 188
 189 or:
 190
 191   apt-get install package-name
 192
 193 at a root shell (or via sudo).
 194
 195 eg.
 196
 197   apt-get install libjpeg62-dev
 198
 199 For a Redhat based system such as CentOS or Fedora you would run:
 200
 201   yum install package-name
 202
 203 at a root shell.
 204
 205 eg.
 206
 207   yum install libjpeg-devel
 208
 209 I strongly recommend using your distribution's packages if possible,
 210 this will mean any security updates to those packages will be applied
 211 when you install security updates.
 212
 213 3.1 libjpeg
 214 -----------
 215
 216   http://www.ijg.org/files/
 217   ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
 218
 219 Provides read and write access to JPEG images.
 220
 221 Make sure you run:
 222
 223   make install-lib
 224
 225 to install the development headers and libraries before attempting to
 226 build Imager.
 227
 228 Debian: libjpeg62-dev
 229 Redhat: libjpeg-devel
 230
 231 3.2 libpng
 232 ----------
 233
 234   http://www.libpng.org/pub/png/libpng.html
 235
 236 Provides read and write access to PNG images.
 237
 238 You also need zlib to use png: http://www.gzip.org/zlib/ We have
 239 encountered problems with libpng 1.0.1, which were fixed in 1.0.5
 240 Note: you should probably be using zlib 1.1.4, since 1.1.3 has a
 241 potential security problem.
 242
 243 Debian: libpng12-dev
 244 Redhat: libpng-devel
 245
 246 3.3 giflib
 247 ----------
 248
 249   http://sourceforge.net/projects/giflib/
 250
 251 Provides read and write access to GIF images.
 252
 253 giflib/libungif has come a long way since the buggy versions available
 254 when Imager's gif support code was written.  Preferably you should get
 255 at least version 4.1.4.  If you have a recent Linux distribution you
 256 should be safe with whatever giflib it provides, but if you're
 257 building from source, please try to use the latest version.
 258
 259 With the expiration of the LZW patent there's no reason to use
 260 libungif.
 261
 262 libgif 4.1.4 has no problems known to me at this point.
 263
 264 Debian: libgif-dev
 265 Redhat: giflib-devel
 266
 267 3.4 libtiff
 268 -----------
 269
 270  http://www.remotesensing.org/libtiff/
 271
 272 Provides read and write access to TIFF images.
 273
 274 Note: libtiff 3.9.0 shouldn't be used due to a bug in
 275 TIFFWriteDirectory().
 276
 277 Debian: libtiff4-dev
 278 Redhat: libtiff-devel
 279
 280 3.5 T1Lib
 281 ---------
 282
 283   http://www.t1lib.org/
 284   ftp://sunsite.unc.edu/pub/Linux/libs/graphics/
 285
 286 Support for text drawing with Type 1 Postscript fonts.
 287
 288 Debian: libt1-dev
 289 Redhat: t1lib-devel
 290
 291 3.6 Freetype 2.x (libfreetype)
 292 ------------------------------
 293
 294   http://www.freetype.org/
 295
 296 Support for text drawing with a large number of font formats,
 297 including Truetype, Type 1, Opentype and some bitmap formats.
 298
 299 Debian: libfreetype6-dev
 300 Redhat: freetype-devel
 301
 302 3.7 Freetype 1.x (libttf)
 303 -------------------------
 304
 305   http://www.freetype.org/
 306
 307 Support for text drawing with Truetype fonts.
 308
 309 This library has been superceded by Freetype 2, and some Linux
 310 distributions are phasing it out.
 311
 312 Debian: libttf-dev
 313 Redhat: freetype1-devel
 314
 315 3.8 Binaries
 316 ------------
 317
 318 Precompiled versions of some of the libraries might be found at:
 319
 320 AIX:
 321
 322   http://www.bullfreeware.com/
 323
 324 Solaris:
 325
 326   http://www.sunfreeware.com/
 327
 328 ========================
 329 4. Logging and debugging
 330 ========================
 331
 332 Logging is compiled in by default - if you should want to get of it
 333 from the binaries you can do so by setting the env IMAGER_NOLOG
 334 to something. If you want to enable malloc debugging to check for leaks
 335 then set IMAGER_DEBUG_MALLOC to something.  Needless to say it is
 336 pretty pointless to have malloc debug enabled with no logging since you
 337 can never see the malloc information that way.
 338
 339
 340 =================
 341 5. Win32 Support
 342 =================
 343
 344 Imager can be installed on Win32 systems.  This was ported and tested
 345 with Microsoft Visual C++ 6.0 with build 623 of ActivePerl.  You can
 346 use all of the features of Imager.  You can also use Win32 GDI fonts
 347 directly by supplying the 'face' parameter to Imager::Font->new(...).
 348
 349 I've tested with MSVC++ 6.0, cygwin (perl 5.6.1) and gcc (MinGW).
 350
 351 If you see an error under cygwin during testing along the lines of:
 352
 353   C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
 354     same address as parent (0x...) != 0x....
 355
 356 you will need to install the cygwin rebase package and run:
 357
 358   $ rebaseall -v
 359
 360 If you get errors from your make tool, make sure you're using the same
 361 make that was used to build your perl - generally GNU make for cygwin,
 362 nmake for Visual C/C++ and dmake for MinGW.
 363
 364 Imager and all of the libraries it requires are supplied with
 365 Strawberry Perl.
 366
 367 ============
 368 6. Mac OS X
 369 ============
 370
 371 Building Imager under OS X is generally straightforward.  There are
 372 some exceptions though:
 373
 374 a) you may find to need to ranlib library files in place after you've
 375    installed them, for example:
 376
 377      ranlib /usr/local/lib/libgif.a
 378
 379 b) the version of GCC enabled by default on OS X 10.4 generates
 380    incorrect code for some functions.  To work around this run:
 381
 382      gcc_select 3
 383
 384    before building Imager and:
 385
 386      gcc_select 4
 387
 388    after building Imager.
 389
 390    This problem exhibits itself as test failures in t/t20fill.t
 391
 392    Imager 0.56 includes a workaround for this problem, but I wasn't
 393    able to test it.
 394
 395 c) if you want to build GCC 4.0 from scratch and use that you will
 396    need to adjust the command-line supplied during the link stage, so
 397    that there is some other option before the -bundle option.
 398
 399    For example:
 400
 401      perl Makefile.PL LDDLFLAGS="`perl -MConfig -e 'print "-g $Config{lddlflags}"'`"
 402
 403 =======================
 404 7. General information
 405 =======================
 406
 407 The Imager module homepage is currently at:
 408
 409  http://imager.perl.org/
 410
 411 You can report bugs by pointing your browser at:
 412
 413   https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager
 414
 415 ========================
 416 8. Thanks
 417 ========================
 418
 419 Thanks go to:
 420   Tony Cook           ( TonyC )
 421   Claes Jacobson      ( Claes )
 422   Philip Gwyn         ( Leolo )
 423   Michael Slade       ( Micksa )
 424                       ( Cogent )
 425   Brad Murray         ( HalfJack )
 426   Nicholas Dronen     ( Veblen )
 427   Michael G Schwern   ( Schwern )
 428   Rocco Caputo        ( Dngor )
 429   Graham barr         ( Gbarr )
 430   Mark-Jason Dominus  ( Mjd )
 431   Jerome
 432   Jason Alexander     ( Jalex )
 433   Randal R. Schwartz  ( Merlyn )
 434   Tkil                ( )
 435   Artur Bergman       ( Sky )
 436   Luc St-Louis        ( Lucs )
 437   PerlJam             ( )
 438   Roderick Schertler  ( Roderick )
 439   Nathan Torkington   ( gnat )
 440   Gabriel Vasseur
 441
 442 (and just to play it safe) all those I forgot to mention.