Clarified what version of libtiff is required.
[imager.git] / 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 Also note that libgif has a few bugs: You can run something like
88
89 $ perl -Iblib/lib -Iblib/arch t/t105gif.t
90
91 This way you can see what comments the test script prints out.
92 t/t105gif.t checks for an bug in libgif and prints out a patch
93 if that bug is present, note that this bug only affects the more
94 "advanced" features of libgif.
95
96 If for some reason you have libungif-devel package installed but
97 not libungif on RedHat then you will probably get lots of errors
98 like undefined symbol: FreeSavedImages when running make test.
99 Install libungif package to fix it.
100
101
102 Imager needs to have a libtiff version of at least 3.5.5.  In the
103 future we might consider supporting older libtiff versions.  For
104 now you can either configure Imager manually (by
105 setting the IM_MANUAL environment variable to 1, in sh:
106
107 $ IM_MANUAL=1 perl Makefile.PL
108
109 and simply say no to tiff support when asked if you want it, the same thing
110 can be used to circumvent problems in gifs to get Imager going.
111
112
113 If it worked just continue with the installation as normally 
114 (with make install).
115
116 ========================
117 3. External dependencies
118 ========================
119
120 Some hints about getting the Imager module to find the libraries it
121 needs for specific features.  The libraries it uses are:
122
123  jpeg: ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
124
125   png: ftp://ftp.uu.net/graphics/png  
126   you also need zlib to use png:  ftp://ftp.uu.net/pub/archiving/zip/zlib
127   We have encountered problems with libpng 1.0.1, which were fixed in 1.0.5
128
129   gif: http://www.arrakeen.demon.co.uk/giflib/  
130 or at: http://prtr-13.ucsc.edu/~badger/software/libungif/index.shtml
131
132  tiff: http://www.libtiff.org/
133
134    t1: ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/
135 or at: ftp://sunsite.unc.edu/pub/Linux/libs/graphics/
136
137    tt: http://www.freetype.org/
138
139
140 Precompiled versions of some of the libraries might be found at:
141
142 AIX:
143    http://www.bull.de/
144    ftp://ftp.rge.com/pub/systems/aix/bull/
145
146
147
148 ========================
149 4. Logging and debugging
150 ========================
151
152 Logging is compiled in by default - if you should want to get of it
153 from the binaries you can do so by setting the env IMAGER_NOLOG 
154 to something. If you want to enable malloc debugging to check for leaks
155 then set IMAGER_DEBUG_MALLOC to something.  Needless to say it is
156 pretty pointless to have malloc debug enabled with no logging since you 
157 can never see the malloc information that way.
158
159
160 ========================
161 5. Truetype information
162 ========================
163
164 If you enable the truetype part and want it to be TESTED you MUST set
165 the environment variable TTFONTTEST to a complete path to a truetype
166 font.
167
168
169 =================
170 6. Win32 Support
171 =================
172
173 Imager can be installed on Win32 systems.  This was ported and tested
174 with Microsoft Visual C++ 6.0 with build 623 of ActivePerl.  You can
175 use all of the features of Imager.  You can also use Win32 GDI fonts
176 directly by supplying the 'face' parameter to Imager::Font->new(...).
177
178 I've tested with both MSVC++ 6.0 and cygwin (perl 5.6.1).
179
180 If you have any problems with the Win32 support, please email
181 tony@develop-help.com (don't forget to use nmake instead of make).
182
183 =======================
184 7. General information
185 =======================
186
187 The Imager module homepage is currently at:
188
189  http://www.eecs.umich.edu/~addi/perl/Imager/
190
191 The current docs are rather bad as I've been busy adding features
192 but hopefully they will be updated soon.  Until then you'll just
193 have to use the source. The test scripts might also be a good idea.
194 By activating the the #init_log lines in the test script you can get
195 rather verbose debugging output from the C code.
196
197
198 ========================
199 8. Thanks
200 ========================
201
202 Thanks go to:
203   Tony Cook           ( TonyC )
204   Claes Jacobson      ( Claes )
205   Philip Gwyn         ( Leolo )
206   Michael Slade       ( Micksa )
207   Brad Murray         ( HalfJack )
208   Nicholas Dronen     ( Veblen )
209   Michael G Schwern   ( Schwern )
210   Rocco Caputo        ( Dngor )
211   Graham barr         ( Gbarr )
212   Mark-Jason Dominus  ( Mjd )
213   Jerome
214   Jason Alexander     ( Jalex )
215   Randal R. Schwartz  ( Merlyn )
216   Tkil                ( )
217   Artur Bergman       ( Sky )
218   Luc St-Louis        ( Lucs )
219   PerlJam             ( )
220   Roderick Schertler  ( Roderick )
221   Nathan Torkington   ( gnat )
222
223 (and just to play it safe) all those I forgot to mention.