- eliminate many -Wall warnings
[imager.git] / README
CommitLineData
02d1d628 1================================================================
2a7024e9 2Copyright (c) 1999-2004 Arnar M. Hrafnkelsson. All rights reserved.
8f22b8d8 3Copyright (c) 2004 Anthony Cook.
02d1d628
AMH
4This program is free software; you can redistribute it and/or
5modify it under the same terms as Perl itself.
6================================================================
7
8>> THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY WHATSOEVER <<
b8c2033e
AMH
9If you like or hate Imager, please let us know by sending mail
10to imager@imager.perl.org
02d1d628
AMH
11
12================================================================
13
14
15========================
161. Patent infringements?
17========================
18
19Imager as such contains no patented algorithms. The external
20libraries (which are not written by me) may or may not contain
21patented algorithms. YOU ARE SOLELY RESPONSIBLE FOR OBTAINING
22LICENSE(S) TO USE SUCH LIBRARIES SHOULD YOU NEED ANY.
23
24
25========================
262. Compiling and testing
27========================
28
29Some care has been taken to make the installation as smooth as
30possible. This is rather hard due to the difference between operating
31systems and site setups. To get started just type
32
33$ perl Makefile.PL
34
35It should blurb out a list of which libraries were found and which
36not. If you add a library to the machine after installing Imager it
37does not automatically become available in Imager. It only uses the
38libraries that are found. If the list of found libraries is not what
39you expected, then the Makefile.PL is either not searching in the
40right directories or your box does not have the libraries you think it
41does. For a list of where to get the libraries have a look at
423. External dependencies. To widen the search path for libraries and
43include files set the IM_INCPATH and IM_LIBPATH variables. The
44environment variables that matter when Makefile.PL is run are
45
46IM_INCPATH colon separated list of paths to extra include files
47IM_LIBPATH colon separated list of paths to extra library files
48
49IM_VERBOSE turns on verbose mode for the library scanning and such
50IM_MANUAL to manually select which libraries are used and which not
51IM_NOLOG if true logging will not be compiled into the module
52IM_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
56IM_CFLAGS Extra flags to pass to the compiler
57IM_LFLAGS Extra flags to pass to the linker
58IM_DFLAGS Extra flags to pass to the preprocessor
59
60
61
62When finding the libraries has been sorted out it's time for
63
64$ make
65
66and if that works then do
67
68$ make test
69
70If either fails do take a peek at the file errep.perl. It's creates a
71file report.txt. This is some information which will help me discover
72where the problem is so I can try to fix it in future releases. If
73you find running it ok (just remember - no warranty!) please send the
e8910022 74report.txt via email to imager@imager.perl.org.
02d1d628
AMH
75
76Troubleshooting tips:
77
78A common problem is that libgif/libungif are sometimes linked to the X
79libraries and then running the tests fails. In that case something
80like:
81
82$ IM_LFLAGS="-L/usr/X11R6/lib -lX11" perl Makefile.PL
83
84Which simply sets the environment variables for the extra libraries
85to include the X libraries (which we do not use at all, but must
86included since libgif has been linked with it).
87
feba68a3
TC
88Otherwise you could just build giflib without any X11 dependencies:
89
90 # must be a clean tree
2a7024e9 91 cd giflib-4.1.3
feba68a3
TC
92 ./configure --without-x ...
93
02d1d628
AMH
94Also note that libgif has a few bugs: You can run something like
95
e3ddf807 96$ perl -Iblib/lib -Iblib/arch t/t105gif.t
02d1d628
AMH
97
98This way you can see what comments the test script prints out.
e3ddf807 99t/t105gif.t checks for an bug in libgif and prints out a patch
02d1d628
AMH
100if that bug is present, note that this bug only affects the more
101"advanced" features of libgif.
102
48412c20
AMH
103If for some reason you have libungif-devel package installed but
104not libungif on RedHat then you will probably get lots of errors
105like undefined symbol: FreeSavedImages when running make test.
106Install libungif package to fix it.
107
0b836ff8
TC
108Stock libungif 4.1.2 or later seems to fix all of the bugs, if you
109have a problem that version of linungif (or later), let us know and
110we'll look into it.
48412c20 111
4f337d03
AMH
112Imager needs to have a libtiff version of at least 3.5.5. In the
113future we might consider supporting older libtiff versions. For
114now you can either configure Imager manually (by
02d1d628
AMH
115setting the IM_MANUAL environment variable to 1, in sh:
116
117$ IM_MANUAL=1 perl Makefile.PL
118
119and simply say no to tiff support when asked if you want it, the same thing
120can be used to circumvent problems in gifs to get Imager going.
121
02d1d628
AMH
122If it worked just continue with the installation as normally
123(with make install).
124
2a7024e9
TC
125Freetype 1.x vs Freetype 2.x
126----------------------------
127
128These two libraries have some conflicting include file names, but as
129long as you don't put the Freetype 2.x freetype.h directory in the
130include path it should all work.
131
132Put the directory containing ft2build.h in the include path, but not
133the directory containing the freetype 2.x freetype.h.
134
135If you see compilation errors from font.c you've probably made the
136mistake of putting the Freetype 2.x freetype.h directory into the
137include path.
138
139To see which directories should be in the include path, try:
140
141 freetype-config --cflags
142
321d94d4
TC
143
144Macintosh dfont and suitcase font support
145-----------------------------------------
146
147Through Freetype 2.1, Imager can use Macintosh DFON (.dfont) fonts and
148suitcase font files.
149
150If you want to be able to use more than just the first face in the
151font file though, you will need to configure freetype2 with the
152--with-old-mac-fonts option:
153
154 ./configure --with-old-mac-fonts
155
156You can use the index option to get to the other font faces in the
157file:
158
159 # get the second face from $file
160 my $font = Imager::Font->new(file=>$file, index=>1)
161 or die Imager->errstr;
162
163If you're using a suitcase font, you will also need to force the use
164of freetype 2 with the type argument:
165
166 my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
167 or die Imager->errstr;
168
169
02d1d628
AMH
170========================
1713. External dependencies
172========================
173
174Some hints about getting the Imager module to find the libraries it
175needs for specific features. The libraries it uses are:
176
31c01e81
TC
177 jpeg: http://www.ijg.org/files/
178 ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
179
180ftp.uu.net is still linked from many places, including the Independent
181JPEG Groups's home page, but it is non-functional.
182
183 png: http://www.libpng.org/pub/png/libpng.html
02d1d628 184
ee0083bf 185 you also need zlib to use png: http://www.gzip.org/zlib/
31c01e81
TC
186We have encountered problems with libpng 1.0.1, which were fixed in 1.0.5
187Note: you should probably be using zlib 1.1.4, since 1.1.3 has a
188potential security problem.
02d1d628 189
31c01e81 190 gif: http://sourceforge.net/projects/libungif
02d1d628 191
31c01e81
TC
192giflib/libungif has come a long way since the buggy versions around
193when Imager's gif support code was written. Preferably you should get
f1967c11 194at least version 4.1.3. If you have a recent Linux distribution you
31c01e81
TC
195should be safe with whatever giflib it provides, but if you're
196building from source, please try to use the latest version.
feba68a3 197
f1967c11
TC
198If you download giflib (as opposed to libungif) 4.1.3 from
199sourceforge, make sure you apply the patch referenced at:
200
201https://sourceforge.net/tracker/index.php?func=detail&aid=981255&group_id=102202&atid=631306
202
203libungif 4.1.3 does not need this patch.
204
31c01e81
TC
205At the time of writing you will need to manually select to install the
2064.1.2-1 of cygwin's libungif package.
feba68a3 207
02d1d628
AMH
208 tiff: http://www.libtiff.org/
209
31c01e81 210 t1: http://www.ibiblio.org/pub/Linux/libs/graphics/
02d1d628 211
2a7024e9 212freetype2 or
02d1d628
AMH
213 tt: http://www.freetype.org/
214
02d1d628
AMH
215Precompiled versions of some of the libraries might be found at:
216
217AIX:
31c01e81 218 http://www.bullfreeware.com/
02d1d628
AMH
219
220
221
222========================
2234. Logging and debugging
224========================
225
226Logging is compiled in by default - if you should want to get of it
227from the binaries you can do so by setting the env IMAGER_NOLOG
228to something. If you want to enable malloc debugging to check for leaks
229then set IMAGER_DEBUG_MALLOC to something. Needless to say it is
230pretty pointless to have malloc debug enabled with no logging since you
231can never see the malloc information that way.
232
233
02d1d628 234=================
8f22b8d8 2355. Win32 Support
02d1d628
AMH
236=================
237
238Imager can be installed on Win32 systems. This was ported and tested
faa9b3e7
TC
239with Microsoft Visual C++ 6.0 with build 623 of ActivePerl. You can
240use all of the features of Imager. You can also use Win32 GDI fonts
241directly by supplying the 'face' parameter to Imager::Font->new(...).
242
243I've tested with both MSVC++ 6.0 and cygwin (perl 5.6.1).
02d1d628 244
31c01e81
TC
245If you see an error under cygwin during testing along the lines of:
246
247 C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
248 same address as parent (0x...) != 0x....
249
250you will need to install the cygwin rebase package and run:
251
252 $ rebaseall -v
253
254Under cygwin you will need at least libungif 4.1.2 installed to
255prevent lockups in the gif test scripts. At the time of writing you
256need to select libungif-4.1.2-1 manually in the setup.exe installation
257tool.
258
9c271ef0
TC
259If you get errors from your make tool, make sure you're using the same
260make that was used to build your perl - generally GNU make for cygwin,
261nmake for Visual C/C++ and dmake for MinGW.
02d1d628 262
01b5a039
TC
263============
2646. Mac OS X
265============
266
267Building Imager under OS X is generally straightforward. There are
268some exceptions though:
269
270a) you may find to need to ranlib library files in place after you've
271 installed them, for example:
272
273 ranlib /usr/local/lib/libgif.a
274
275b) the version of GCC enabled by default on OS X 10.4 generates
276 incorrect code for some functions. To work around this run:
277
278 gcc_select 3
279
280 before building Imager and:
281
282 gcc_select 4
283
284 after building Imager.
285
286 This problem exhibits itself as test failures in t/t20fill.t
287
288c) if you want to build GCC 4.0 from scratch and use that you will
289 need to adjust the command-line supplied during the link stage, so
290 that there is some other option before the -bundle option.
291
292 For example:
293
294 perl Makefile.PL LDDLFLAGS="`perl -MConfig -e 'print "-g $Config{lddlflags}"'`"
295
02d1d628 296=======================
01b5a039 2977. General information
02d1d628
AMH
298=======================
299
300The Imager module homepage is currently at:
301
31c01e81 302 http://imager.perl.org/
02d1d628
AMH
303
304The current docs are rather bad as I've been busy adding features
305but hopefully they will be updated soon. Until then you'll just
306have to use the source. The test scripts might also be a good idea.
307By activating the the #init_log lines in the test script you can get
308rather verbose debugging output from the C code.
309
f6acebd0 310You can report bugs by pointing your browser at:
e8910022
TC
311
312 https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager
02d1d628
AMH
313
314========================
01b5a039 3158. Thanks
02d1d628
AMH
316========================
317
318Thanks go to:
319 Tony Cook ( TonyC )
320 Claes Jacobson ( Claes )
321 Philip Gwyn ( Leolo )
df917a00 322 Michael Slade ( Micksa )
23bf355e 323 ( Cogent )
02d1d628
AMH
324 Brad Murray ( HalfJack )
325 Nicholas Dronen ( Veblen )
326 Michael G Schwern ( Schwern )
327 Rocco Caputo ( Dngor )
328 Graham barr ( Gbarr )
329 Mark-Jason Dominus ( Mjd )
330 Jerome
331 Jason Alexander ( Jalex )
332 Randal R. Schwartz ( Merlyn )
333 Tkil ( )
334 Artur Bergman ( Sky )
335 Luc St-Louis ( Lucs )
336 PerlJam ( )
337 Roderick Schertler ( Roderick )
338 Nathan Torkington ( gnat )
339
340(and just to play it safe) all those I forgot to mention.