README

   1 ================================================================
   2 Copyright (c) 1999-2004 Arnar M. Hrafnkelsson. All rights reserved.
   3 Copyright (c) 2004 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 If you like or hate Imager, please let us know by sending mail
  10 to imager@imager.perl.org
  11
  12 ================================================================
  13
  14
  15 ========================
  16 1. Patent infringements?
  17 ========================
  18
  19 Imager as such contains no patented algorithms.  The external
  20 libraries (which are not written by me) may or may not contain
  21 patented algorithms.  YOU ARE SOLELY RESPONSIBLE FOR OBTAINING
  22 LICENSE(S) TO USE SUCH LIBRARIES SHOULD YOU NEED ANY.
  23
  24
  25 ========================
  26 2. Compiling and testing
  27 ========================
  28
  29 Some care has been taken to make the installation as smooth as
  30 possible.  This is rather hard due to the difference between operating
  31 systems and site setups.  To get started just type
  32
  33 $ perl Makefile.PL
  34
  35 It should blurb out a list of which libraries were found and which
  36 not.  If you add a library to the machine after installing Imager it
  37 does not automatically become available in Imager.  It only uses the
  38 libraries that are found.  If the list of found libraries is not what
  39 you expected, then the Makefile.PL is either not searching in the
  40 right directories or your box does not have the libraries you think it
  41 does.  For a list of where to get the libraries have a look at
  42 3. External dependencies.  To widen the search path for libraries and
  43 include files set the IM_INCPATH and IM_LIBPATH variables.  The
  44 environment variables that matter when Makefile.PL is run are
  45
  46 IM_INCPATH      colon separated list of paths to extra include files
  47 IM_LIBPATH      colon separated list of paths to extra library files
  48
  49 IM_VERBOSE      turns on verbose mode for the library scanning and such
  50 IM_MANUAL       to manually select which libraries are used and which not
  51 IM_NOLOG        if true logging will not be compiled into the module
  52 IM_DEBUG_MALLOC if true malloc debugging will be compiled into the module
  53                 do not use IM_DEBUG_MALLOC in production - this slows
  54                 everything down
  55
  56 IM_CFLAGS       Extra flags to pass to the compiler
  57 IM_LFLAGS       Extra flags to pass to the linker
  58 IM_DFLAGS       Extra flags to pass to the preprocessor
  59
  60
  61
  62 When finding the libraries has been sorted out it's time for
  63
  64 $ make
  65
  66 and if that works then do
  67
  68 $ make test
  69
  70 If either fails do take a peek at the file errep.perl.  It's creates a
  71 file report.txt.  This is some information which will help me discover
  72 where the problem is so I can try to fix it in future releases.  If
  73 you find running it ok (just remember - no warranty!) please send the
  74 report.txt via email to addi@umich.edu .
  75
  76 Troubleshooting tips:
  77
  78 A common problem is that libgif/libungif are sometimes linked to the X
  79 libraries and then running the tests fails.  In that case something
  80 like:
  81
  82 $ IM_LFLAGS="-L/usr/X11R6/lib -lX11" perl Makefile.PL
  83
  84 Which simply sets the environment variables for the extra libraries
  85 to include the X libraries (which we do not use at all, but must
  86 included since libgif has been linked with it).
  87
  88 Otherwise you could just build giflib without any X11 dependencies:
  89
  90   # must be a clean tree
  91   cd giflib-4.1.3
  92   ./configure --without-x ...
  93
  94 Also note that libgif has a few bugs: You can run something like
  95
  96 $ perl -Iblib/lib -Iblib/arch t/t105gif.t
  97
  98 This way you can see what comments the test script prints out.
  99 t/t105gif.t checks for an bug in libgif and prints out a patch
 100 if that bug is present, note that this bug only affects the more
 101 "advanced" features of libgif.
 102
 103 If for some reason you have libungif-devel package installed but
 104 not libungif on RedHat then you will probably get lots of errors
 105 like undefined symbol: FreeSavedImages when running make test.
 106 Install libungif package to fix it.
 107
 108 Stock libungif 4.1.2 or later seems to fix all of the bugs, if you
 109 have a problem that version of linungif (or later), let us know and
 110 we'll look into it.
 111
 112 Imager needs to have a libtiff version of at least 3.5.5.  In the
 113 future we might consider supporting older libtiff versions.  For
 114 now you can either configure Imager manually (by
 115 setting the IM_MANUAL environment variable to 1, in sh:
 116
 117 $ IM_MANUAL=1 perl Makefile.PL
 118
 119 and simply say no to tiff support when asked if you want it, the same thing
 120 can be used to circumvent problems in gifs to get Imager going.
 121
 122 If it worked just continue with the installation as normally
 123 (with make install).
 124
 125 Freetype 1.x vs Freetype 2.x
 126 ----------------------------
 127
 128 These two libraries have some conflicting include file names, but as
 129 long as you don't put the Freetype 2.x freetype.h directory in the
 130 include path it should all work.
 131
 132 Put the directory containing ft2build.h in the include path, but not
 133 the directory containing the freetype 2.x freetype.h.
 134
 135 If you see compilation errors from font.c you've probably made the
 136 mistake of putting the Freetype 2.x freetype.h directory into the
 137 include path.
 138
 139 To see which directories should be in the include path, try:
 140
 141   freetype-config --cflags
 142
 143 ========================
 144 3. External dependencies
 145 ========================
 146
 147 Some hints about getting the Imager module to find the libraries it
 148 needs for specific features.  The libraries it uses are:
 149
 150  jpeg: http://www.ijg.org/files/
 151        ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
 152
 153 ftp.uu.net is still linked from many places, including the Independent
 154 JPEG Groups's home page, but it is non-functional.
 155
 156   png: http://www.libpng.org/pub/png/libpng.html
 157
 158   you also need zlib to use png:  http://www.gzip.org/zlib/
 159 We have encountered problems with libpng 1.0.1, which were fixed in 1.0.5
 160 Note: you should probably be using zlib 1.1.4, since 1.1.3 has a
 161 potential security problem.
 162
 163   gif: http://sourceforge.net/projects/libungif
 164
 165 giflib/libungif has come a long way since the buggy versions around
 166 when Imager's gif support code was written.  Preferably you should get
 167 at least version 4.1.3.  If you have a recent Linux distribution you
 168 should be safe with whatever giflib it provides, but if you're
 169 building from source, please try to use the latest version.
 170
 171 If you download giflib (as opposed to libungif) 4.1.3 from
 172 sourceforge, make sure you apply the patch referenced at:
 173
 174 https://sourceforge.net/tracker/index.php?func=detail&aid=981255&group_id=102202&atid=631306
 175
 176 libungif 4.1.3 does not need this patch.
 177
 178 At the time of writing you will need to manually select to install the
 179 4.1.2-1 of cygwin's libungif package.
 180
 181  tiff: http://www.libtiff.org/
 182
 183    t1: http://www.ibiblio.org/pub/Linux/libs/graphics/
 184
 185 freetype2 or
 186    tt: http://www.freetype.org/
 187
 188 Precompiled versions of some of the libraries might be found at:
 189
 190 AIX:
 191    http://www.bullfreeware.com/
 192
 193
 194
 195 ========================
 196 4. Logging and debugging
 197 ========================
 198
 199 Logging is compiled in by default - if you should want to get of it
 200 from the binaries you can do so by setting the env IMAGER_NOLOG
 201 to something. If you want to enable malloc debugging to check for leaks
 202 then set IMAGER_DEBUG_MALLOC to something.  Needless to say it is
 203 pretty pointless to have malloc debug enabled with no logging since you
 204 can never see the malloc information that way.
 205
 206
 207 =================
 208 5. Win32 Support
 209 =================
 210
 211 Imager can be installed on Win32 systems.  This was ported and tested
 212 with Microsoft Visual C++ 6.0 with build 623 of ActivePerl.  You can
 213 use all of the features of Imager.  You can also use Win32 GDI fonts
 214 directly by supplying the 'face' parameter to Imager::Font->new(...).
 215
 216 I've tested with both MSVC++ 6.0 and cygwin (perl 5.6.1).
 217
 218 If you see an error under cygwin during testing along the lines of:
 219
 220   C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
 221     same address as parent (0x...) != 0x....
 222
 223 you will need to install the cygwin rebase package and run:
 224
 225   $ rebaseall -v
 226
 227 Under cygwin you will need at least libungif 4.1.2 installed to
 228 prevent lockups in the gif test scripts.  At the time of writing you
 229 need to select libungif-4.1.2-1 manually in the setup.exe installation
 230 tool.
 231
 232 If you have any problems with the Win32 support, please email
 233 tony@develop-help.com (don't forget to use nmake instead of make).
 234
 235 =======================
 236 6. General information
 237 =======================
 238
 239 The Imager module homepage is currently at:
 240
 241  http://imager.perl.org/
 242
 243 The current docs are rather bad as I've been busy adding features
 244 but hopefully they will be updated soon.  Until then you'll just
 245 have to use the source. The test scripts might also be a good idea.
 246 By activating the the #init_log lines in the test script you can get
 247 rather verbose debugging output from the C code.
 248
 249
 250 ========================
 251 7. Thanks
 252 ========================
 253
 254 Thanks go to:
 255   Tony Cook           ( TonyC )
 256   Claes Jacobson      ( Claes )
 257   Philip Gwyn         ( Leolo )
 258   Michael Slade       ( Micksa )
 259                       ( Cogent )
 260   Brad Murray         ( HalfJack )
 261   Nicholas Dronen     ( Veblen )
 262   Michael G Schwern   ( Schwern )
 263   Rocco Caputo        ( Dngor )
 264   Graham barr         ( Gbarr )
 265   Mark-Jason Dominus  ( Mjd )
 266   Jerome
 267   Jason Alexander     ( Jalex )
 268   Randal R. Schwartz  ( Merlyn )
 269   Tkil                ( )
 270   Artur Bergman       ( Sky )
 271   Luc St-Louis        ( Lucs )
 272   PerlJam             ( )
 273   Roderick Schertler  ( Roderick )
 274   Nathan Torkington   ( gnat )
 275
 276 (and just to play it safe) all those I forgot to mention.