README

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