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