Fixed i_transform2() so malloc(0) doesn't happen. Also corrected pod errors and
[imager.git] / README
CommitLineData
02d1d628 1================================================================
7ad895ee 2Copyright (c) 1999-2001 Arnar M. Hrafnkelsson. All rights reserved.
02d1d628
AMH
3This program is free software; you can redistribute it and/or
4modify it under the same terms as Perl itself.
5================================================================
6
7>> THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY WHATSOEVER <<
b8c2033e
AMH
8If you like or hate Imager, please let us know by sending mail
9to imager@imager.perl.org
02d1d628
AMH
10
11================================================================
12
13
14========================
151. Patent infringements?
16========================
17
18Imager as such contains no patented algorithms. The external
19libraries (which are not written by me) may or may not contain
20patented algorithms. YOU ARE SOLELY RESPONSIBLE FOR OBTAINING
21LICENSE(S) TO USE SUCH LIBRARIES SHOULD YOU NEED ANY.
22
23
24========================
252. Compiling and testing
26========================
27
28Some care has been taken to make the installation as smooth as
29possible. This is rather hard due to the difference between operating
30systems and site setups. To get started just type
31
32$ perl Makefile.PL
33
34It should blurb out a list of which libraries were found and which
35not. If you add a library to the machine after installing Imager it
36does not automatically become available in Imager. It only uses the
37libraries that are found. If the list of found libraries is not what
38you expected, then the Makefile.PL is either not searching in the
39right directories or your box does not have the libraries you think it
40does. For a list of where to get the libraries have a look at
413. External dependencies. To widen the search path for libraries and
42include files set the IM_INCPATH and IM_LIBPATH variables. The
43environment variables that matter when Makefile.PL is run are
44
45IM_INCPATH colon separated list of paths to extra include files
46IM_LIBPATH colon separated list of paths to extra library files
47
48IM_VERBOSE turns on verbose mode for the library scanning and such
49IM_MANUAL to manually select which libraries are used and which not
50IM_NOLOG if true logging will not be compiled into the module
51IM_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
55IM_CFLAGS Extra flags to pass to the compiler
56IM_LFLAGS Extra flags to pass to the linker
57IM_DFLAGS Extra flags to pass to the preprocessor
58
59
60
61When finding the libraries has been sorted out it's time for
62
63$ make
64
65and if that works then do
66
67$ make test
68
69If either fails do take a peek at the file errep.perl. It's creates a
70file report.txt. This is some information which will help me discover
71where the problem is so I can try to fix it in future releases. If
72you find running it ok (just remember - no warranty!) please send the
73report.txt via email to addi@umich.edu .
74
75Troubleshooting tips:
76
77A common problem is that libgif/libungif are sometimes linked to the X
78libraries and then running the tests fails. In that case something
79like:
80
81$ IM_LFLAGS="-L/usr/X11R6/lib -lX11" perl Makefile.PL
82
83Which simply sets the environment variables for the extra libraries
84to include the X libraries (which we do not use at all, but must
85included since libgif has been linked with it).
86
87Also note that libgif has a few bugs: You can run something like
88
e3ddf807 89$ perl -Iblib/lib -Iblib/arch t/t105gif.t
02d1d628
AMH
90
91This way you can see what comments the test script prints out.
e3ddf807 92t/t105gif.t checks for an bug in libgif and prints out a patch
02d1d628
AMH
93if that bug is present, note that this bug only affects the more
94"advanced" features of libgif.
95
48412c20
AMH
96If for some reason you have libungif-devel package installed but
97not libungif on RedHat then you will probably get lots of errors
98like undefined symbol: FreeSavedImages when running make test.
99Install libungif package to fix it.
100
101
02d1d628
AMH
102Imager needs to have a fairly recent libtiff installed (we know it
103it runs fine with 3.5.5). In the future we might consider supporting older
104libtiff versions. For now you can either configure Imager manually (by
105setting the IM_MANUAL environment variable to 1, in sh:
106
107$ IM_MANUAL=1 perl Makefile.PL
108
109and simply say no to tiff support when asked if you want it, the same thing
110can be used to circumvent problems in gifs to get Imager going.
111
112
113If it worked just continue with the installation as normally
114(with make install).
115
116========================
1173. External dependencies
118========================
119
120Some hints about getting the Imager module to find the libraries it
121needs 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
ae448e5a 127 We have encountered problems with libpng 1.0.1, which were fixed in 1.0.5
02d1d628
AMH
128
129 gif: http://www.arrakeen.demon.co.uk/giflib/
130or 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/
135or at: ftp://sunsite.unc.edu/pub/Linux/libs/graphics/
136
137 tt: http://www.freetype.org/
138
139
140Precompiled versions of some of the libraries might be found at:
141
142AIX:
143 http://www.bull.de/
144 ftp://ftp.rge.com/pub/systems/aix/bull/
145
146
147
148========================
1494. Logging and debugging
150========================
151
152Logging is compiled in by default - if you should want to get of it
153from the binaries you can do so by setting the env IMAGER_NOLOG
154to something. If you want to enable malloc debugging to check for leaks
155then set IMAGER_DEBUG_MALLOC to something. Needless to say it is
156pretty pointless to have malloc debug enabled with no logging since you
157can never see the malloc information that way.
158
159
160========================
1615. Truetype information
162========================
163
164If you enable the truetype part and want it to be TESTED you MUST set
165the environment variable TTFONTTEST to a complete path to a truetype
166font.
167
168
169=================
1706. Win32 Support
171=================
172
173Imager can be installed on Win32 systems. This was ported and tested
faa9b3e7
TC
174with Microsoft Visual C++ 6.0 with build 623 of ActivePerl. You can
175use all of the features of Imager. You can also use Win32 GDI fonts
176directly by supplying the 'face' parameter to Imager::Font->new(...).
177
178I've tested with both MSVC++ 6.0 and cygwin (perl 5.6.1).
02d1d628
AMH
179
180If you have any problems with the Win32 support, please email
181tony@develop-help.com (don't forget to use nmake instead of make).
182
183=======================
1847. General information
185=======================
186
187The Imager module homepage is currently at:
188
189 http://www.eecs.umich.edu/~addi/perl/Imager/
190
191The current docs are rather bad as I've been busy adding features
192but hopefully they will be updated soon. Until then you'll just
193have to use the source. The test scripts might also be a good idea.
194By activating the the #init_log lines in the test script you can get
195rather verbose debugging output from the C code.
196
197
198========================
1998. Thanks
200========================
201
202Thanks go to:
203 Tony Cook ( TonyC )
204 Claes Jacobson ( Claes )
205 Philip Gwyn ( Leolo )
df917a00 206 Michael Slade ( Micksa )
02d1d628
AMH
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.