README

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