README

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