README

   1 ================================================================
   2 Copyright (c) 1999-2004 Arnar M. Hrafnkelsson. All rights reserved.
   3 Copyright (c) 2004-2007 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.  In the
 114 future we might consider supporting older libtiff versions.  For
 115 now you can either configure Imager manually (by
 116 setting the IM_MANUAL environment variable to 1, in sh:
 117
 118 $ IM_MANUAL=1 perl Makefile.PL
 119
 120 and simply say no to tiff support when asked if you want it, the same thing
 121 can be used to circumvent problems in gifs to get Imager going.
 122
 123 If it worked just continue with the installation as normally
 124 (with make install).
 125
 126 Freetype 1.x vs Freetype 2.x
 127 ----------------------------
 128
 129 These two libraries have some conflicting include file names, but as
 130 long as you don't put the Freetype 2.x freetype.h directory in the
 131 include path it should all work.
 132
 133 Put the directory containing ft2build.h in the include path, but not
 134 the directory containing the freetype 2.x freetype.h.
 135
 136 If you see compilation errors from font.c you've probably made the
 137 mistake of putting the Freetype 2.x freetype.h directory into the
 138 include path.
 139
 140 To see which directories should be in the include path, try:
 141
 142   freetype-config --cflags
 143
 144 Ideally, freetype-config should be in the PATH when building Imager
 145 with freetype 2.x support.
 146
 147
 148 Macintosh dfont and suitcase font support
 149 -----------------------------------------
 150
 151 Through Freetype 2.1, Imager can use Macintosh DFON (.dfont) fonts and
 152 suitcase font files.
 153
 154 If you want to be able to use more than just the first face in the
 155 font file though, you will need to configure freetype2 with the
 156 --with-old-mac-fonts option:
 157
 158   ./configure --with-old-mac-fonts
 159
 160 You can use the index option to get to the other font faces in the
 161 file:
 162
 163   # get the second face from $file
 164   my $font = Imager::Font->new(file=>$file, index=>1)
 165     or die Imager->errstr;
 166
 167 If you're using a suitcase font, you will also need to force the use
 168 of freetype 2 with the type argument:
 169
 170   my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
 171     or die Imager->errstr;
 172
 173
 174 ========================
 175 3. External dependencies
 176 ========================
 177
 178 Some hints about getting the Imager module to find the libraries it
 179 needs for specific features.  The libraries it uses are:
 180
 181  jpeg: http://www.ijg.org/files/
 182        ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
 183
 184 ftp.uu.net is still linked from many places, including the Independent
 185 JPEG Groups's home page, but it is non-functional.
 186
 187   png: http://www.libpng.org/pub/png/libpng.html
 188
 189   you also need zlib to use png:  http://www.gzip.org/zlib/
 190 We have encountered problems with libpng 1.0.1, which were fixed in 1.0.5
 191 Note: you should probably be using zlib 1.1.4, since 1.1.3 has a
 192 potential security problem.
 193
 194   gif: http://sourceforge.net/projects/libungif
 195
 196 giflib/libungif has come a long way since the buggy versions available
 197 when Imager's gif support code was written.  Preferably you should get
 198 at least version 4.1.4.  If you have a recent Linux distribution you
 199 should be safe with whatever giflib it provides, but if you're
 200 building from source, please try to use the latest version.
 201
 202 libgif 4.1.4 has no problems known to me at this point.
 203
 204  tiff: http://www.libtiff.org/
 205
 206    t1: http://www.ibiblio.org/pub/Linux/libs/graphics/
 207
 208 freetype2 or
 209    tt: http://www.freetype.org/
 210
 211 Precompiled versions of some of the libraries might be found at:
 212
 213 AIX:
 214    http://www.bullfreeware.com/
 215
 216
 217
 218 ========================
 219 4. Logging and debugging
 220 ========================
 221
 222 Logging is compiled in by default - if you should want to get of it
 223 from the binaries you can do so by setting the env IMAGER_NOLOG
 224 to something. If you want to enable malloc debugging to check for leaks
 225 then set IMAGER_DEBUG_MALLOC to something.  Needless to say it is
 226 pretty pointless to have malloc debug enabled with no logging since you
 227 can never see the malloc information that way.
 228
 229
 230 =================
 231 5. Win32 Support
 232 =================
 233
 234 Imager can be installed on Win32 systems.  This was ported and tested
 235 with Microsoft Visual C++ 6.0 with build 623 of ActivePerl.  You can
 236 use all of the features of Imager.  You can also use Win32 GDI fonts
 237 directly by supplying the 'face' parameter to Imager::Font->new(...).
 238
 239 I've tested with both MSVC++ 6.0 and cygwin (perl 5.6.1).
 240
 241 If you see an error under cygwin during testing along the lines of:
 242
 243   C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
 244     same address as parent (0x...) != 0x....
 245
 246 you will need to install the cygwin rebase package and run:
 247
 248   $ rebaseall -v
 249
 250 If you get errors from your make tool, make sure you're using the same
 251 make that was used to build your perl - generally GNU make for cygwin,
 252 nmake for Visual C/C++ and dmake for MinGW.
 253
 254 ============
 255 6. Mac OS X
 256 ============
 257
 258 Building Imager under OS X is generally straightforward.  There are
 259 some exceptions though:
 260
 261 a) you may find to need to ranlib library files in place after you've
 262    installed them, for example:
 263
 264      ranlib /usr/local/lib/libgif.a
 265
 266 b) the version of GCC enabled by default on OS X 10.4 generates
 267    incorrect code for some functions.  To work around this run:
 268
 269      gcc_select 3
 270
 271    before building Imager and:
 272
 273      gcc_select 4
 274
 275    after building Imager.
 276
 277    This problem exhibits itself as test failures in t/t20fill.t
 278
 279    Imager 0.56 includes a workaround for this problem, but I wasn't
 280    able to test it.
 281
 282 c) if you want to build GCC 4.0 from scratch and use that you will
 283    need to adjust the command-line supplied during the link stage, so
 284    that there is some other option before the -bundle option.
 285
 286    For example:
 287
 288      perl Makefile.PL LDDLFLAGS="`perl -MConfig -e 'print "-g $Config{lddlflags}"'`"
 289
 290 =======================
 291 7. General information
 292 =======================
 293
 294 The Imager module homepage is currently at:
 295
 296  http://imager.perl.org/
 297
 298 You can report bugs by pointing your browser at:
 299
 300   https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager
 301
 302 ========================
 303 8. Thanks
 304 ========================
 305
 306 Thanks go to:
 307   Tony Cook           ( TonyC )
 308   Claes Jacobson      ( Claes )
 309   Philip Gwyn         ( Leolo )
 310   Michael Slade       ( Micksa )
 311                       ( Cogent )
 312   Brad Murray         ( HalfJack )
 313   Nicholas Dronen     ( Veblen )
 314   Michael G Schwern   ( Schwern )
 315   Rocco Caputo        ( Dngor )
 316   Graham barr         ( Gbarr )
 317   Mark-Jason Dominus  ( Mjd )
 318   Jerome
 319   Jason Alexander     ( Jalex )
 320   Randal R. Schwartz  ( Merlyn )
 321   Tkil                ( )
 322   Artur Bergman       ( Sky )
 323   Luc St-Louis        ( Lucs )
 324   PerlJam             ( )
 325   Roderick Schertler  ( Roderick )
 326   Nathan Torkington   ( gnat )
 327
 328 (and just to play it safe) all those I forgot to mention.