[rt #82743] fix the Graphics::Magick link
[imager.git] / README
CommitLineData
02d1d628 1================================================================
2a7024e9 2Copyright (c) 1999-2004 Arnar M. Hrafnkelsson. All rights reserved.
66b6db87 3Copyright (c) 2004-2012 Anthony Cook.
02d1d628
AMH
4This program is free software; you can redistribute it and/or
5modify it under the same terms as Perl itself.
231f7570
TC
6
7A test font, FT2/fontfiles/MMOne.pfb contains Postscript code
8copyrighted by Adobe. See adobe.txt for license information.
02d1d628
AMH
9================================================================
10
11>> THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY WHATSOEVER <<
d5d8322f
TC
12
13If you like or hate Imager, please let me know by sending mail
5b480b14 14to tonyc@cpan.org - I love feedback.
02d1d628
AMH
15
16================================================================
17
18
19========================
201. Patent infringements?
21========================
22
23Imager as such contains no patented algorithms. The external
24libraries (which are not written by me) may or may not contain
25patented algorithms. YOU ARE SOLELY RESPONSIBLE FOR OBTAINING
26LICENSE(S) TO USE SUCH LIBRARIES SHOULD YOU NEED ANY.
27
28
29========================
302. Compiling and testing
31========================
32
33Some care has been taken to make the installation as smooth as
34possible. This is rather hard due to the difference between operating
35systems and site setups. To get started just type
36
37$ perl Makefile.PL
38
39It should blurb out a list of which libraries were found and which
40not. If you add a library to the machine after installing Imager it
41does not automatically become available in Imager. It only uses the
42libraries that are found. If the list of found libraries is not what
43you expected, then the Makefile.PL is either not searching in the
44right directories or your box does not have the libraries you think it
45does. For a list of where to get the libraries have a look at
463. External dependencies. To widen the search path for libraries and
47include files set the IM_INCPATH and IM_LIBPATH variables. The
48environment variables that matter when Makefile.PL is run are
49
50IM_INCPATH colon separated list of paths to extra include files
51IM_LIBPATH colon separated list of paths to extra library files
52
53IM_VERBOSE turns on verbose mode for the library scanning and such
54IM_MANUAL to manually select which libraries are used and which not
55IM_NOLOG if true logging will not be compiled into the module
56IM_DEBUG_MALLOC if true malloc debugging will be compiled into the module
57 do not use IM_DEBUG_MALLOC in production - this slows
58 everything down
59
60IM_CFLAGS Extra flags to pass to the compiler
61IM_LFLAGS Extra flags to pass to the linker
62IM_DFLAGS Extra flags to pass to the preprocessor
63
64
65
66When finding the libraries has been sorted out it's time for
67
68$ make
69
70and if that works then do
71
72$ make test
73
74If either fails do take a peek at the file errep.perl. It's creates a
75file report.txt. This is some information which will help me discover
76where the problem is so I can try to fix it in future releases. If
77you find running it ok (just remember - no warranty!) please send the
5b480b14 78report.txt via email to tonyc@cpan.org.
02d1d628
AMH
79
80Troubleshooting tips:
81
82A common problem is that libgif/libungif are sometimes linked to the X
83libraries and then running the tests fails. In that case something
84like:
85
86$ IM_LFLAGS="-L/usr/X11R6/lib -lX11" perl Makefile.PL
87
88Which simply sets the environment variables for the extra libraries
89to include the X libraries (which we do not use at all, but must
90included since libgif has been linked with it).
91
feba68a3
TC
92Otherwise you could just build giflib without any X11 dependencies:
93
94 # must be a clean tree
09f10e3e 95 cd giflib-4.1.4
feba68a3
TC
96 ./configure --without-x ...
97
02d1d628
AMH
98Also note that libgif has a few bugs: You can run something like
99
e3ddf807 100$ perl -Iblib/lib -Iblib/arch t/t105gif.t
02d1d628
AMH
101
102This way you can see what comments the test script prints out.
e3ddf807 103t/t105gif.t checks for an bug in libgif and prints out a patch
02d1d628
AMH
104if that bug is present, note that this bug only affects the more
105"advanced" features of libgif.
106
48412c20
AMH
107If for some reason you have libungif-devel package installed but
108not libungif on RedHat then you will probably get lots of errors
109like undefined symbol: FreeSavedImages when running make test.
110Install libungif package to fix it.
111
09f10e3e 112Stock libungif 4.1.4 or later seems to fix all of the bugs, if you
0b836ff8
TC
113have a problem that version of linungif (or later), let us know and
114we'll look into it.
48412c20 115
bd8052a6
TC
116Imager needs to have a libtiff version of at least 3.5.5, but you
117should use a later version since some noticable bugs have been fixed.
118
119For now you can either configure Imager manually (by setting the
120IM_MANUAL environment variable to 1, in sh:
02d1d628
AMH
121
122$ IM_MANUAL=1 perl Makefile.PL
123
124and simply say no to tiff support when asked if you want it, the same thing
125can be used to circumvent problems in gifs to get Imager going.
126
02d1d628
AMH
127If it worked just continue with the installation as normally
128(with make install).
129
2a7024e9
TC
130Freetype 1.x vs Freetype 2.x
131----------------------------
132
133These two libraries have some conflicting include file names, but as
134long as you don't put the Freetype 2.x freetype.h directory in the
135include path it should all work.
136
137Put the directory containing ft2build.h in the include path, but not
138the directory containing the freetype 2.x freetype.h.
139
140If you see compilation errors from font.c you've probably made the
141mistake of putting the Freetype 2.x freetype.h directory into the
142include path.
143
144To see which directories should be in the include path, try:
145
146 freetype-config --cflags
147
a32484c3
TC
148Ideally, freetype-config should be in the PATH when building Imager
149with freetype 2.x support.
150
321d94d4
TC
151
152Macintosh dfont and suitcase font support
153-----------------------------------------
154
155Through Freetype 2.1, Imager can use Macintosh DFON (.dfont) fonts and
156suitcase font files.
157
158If you want to be able to use more than just the first face in the
159font file though, you will need to configure freetype2 with the
160--with-old-mac-fonts option:
161
162 ./configure --with-old-mac-fonts
163
164You can use the index option to get to the other font faces in the
165file:
166
167 # get the second face from $file
168 my $font = Imager::Font->new(file=>$file, index=>1)
169 or die Imager->errstr;
170
171If you're using a suitcase font, you will also need to force the use
172of freetype 2 with the type argument:
173
174 my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
175 or die Imager->errstr;
176
177
02d1d628
AMH
178========================
1793. External dependencies
180========================
181
182Some hints about getting the Imager module to find the libraries it
f9a39263 183needs for specific features.
02d1d628 184
f9a39263
TC
185Most Linux distributions pre-package these. For each library I've
186listed the Debian and Redhat package names.
31c01e81 187
f9a39263 188For Debian or Debian based system, such as Ubuntu, you would run:
31c01e81 189
f9a39263 190 aptitude install package-name
02d1d628 191
f9a39263
TC
192or:
193
194 apt-get install package-name
195
196at a root shell (or via sudo).
197
198eg.
199
200 apt-get install libjpeg62-dev
201
202For a Redhat based system such as CentOS or Fedora you would run:
203
204 yum install package-name
205
206at a root shell.
207
208eg.
209
210 yum install libjpeg-devel
211
212I strongly recommend using your distribution's packages if possible,
213this will mean any security updates to those packages will be applied
214when you install security updates.
215
2163.1 libjpeg
217-----------
218
219 http://www.ijg.org/files/
220 ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
221
222Provides read and write access to JPEG images.
223
224Make sure you run:
225
226 make install-lib
227
228to install the development headers and libraries before attempting to
229build Imager.
230
231Debian: libjpeg62-dev
232Redhat: libjpeg-devel
233
2343.2 libpng
235----------
236
237 http://www.libpng.org/pub/png/libpng.html
238
239Provides read and write access to PNG images.
240
241You also need zlib to use png: http://www.gzip.org/zlib/ We have
242encountered problems with libpng 1.0.1, which were fixed in 1.0.5
243Note: you should probably be using zlib 1.1.4, since 1.1.3 has a
31c01e81 244potential security problem.
02d1d628 245
f9a39263
TC
246Debian: libpng12-dev
247Redhat: libpng-devel
248
2493.3 giflib
250----------
251
252 http://sourceforge.net/projects/giflib/
253
254Provides read and write access to GIF images.
02d1d628 255
09f10e3e 256giflib/libungif has come a long way since the buggy versions available
31c01e81 257when Imager's gif support code was written. Preferably you should get
09f10e3e 258at least version 4.1.4. If you have a recent Linux distribution you
31c01e81
TC
259should be safe with whatever giflib it provides, but if you're
260building from source, please try to use the latest version.
feba68a3 261
a538a011 262With the expiration of the LZW patent there's no reason to use
f9a39263
TC
263libungif.
264
d5d8322f 265libgif 4.1.4 has no problems known to me at this point.
f1967c11 266
f9a39263
TC
267Debian: libgif-dev
268Redhat: giflib-devel
269
2703.4 libtiff
271-----------
272
273 http://www.remotesensing.org/libtiff/
274
275Provides read and write access to TIFF images.
276
277Note: libtiff 3.9.0 shouldn't be used due to a bug in
278TIFFWriteDirectory().
279
280Debian: libtiff4-dev
281Redhat: libtiff-devel
282
2833.5 T1Lib
284---------
285
286 http://www.t1lib.org/
287 ftp://sunsite.unc.edu/pub/Linux/libs/graphics/
288
289Support for text drawing with Type 1 Postscript fonts.
02d1d628 290
f9a39263
TC
291Debian: libt1-dev
292Redhat: t1lib-devel
02d1d628 293
f9a39263
TC
2943.6 Freetype 2.x (libfreetype)
295------------------------------
296
297 http://www.freetype.org/
298
299Support for text drawing with a large number of font formats,
300including Truetype, Type 1, Opentype and some bitmap formats.
301
302Debian: libfreetype6-dev
303Redhat: freetype-devel
304
3053.7 Freetype 1.x (libttf)
306-------------------------
307
308 http://www.freetype.org/
309
310Support for text drawing with Truetype fonts.
311
312This library has been superceded by Freetype 2, and some Linux
313distributions are phasing it out.
314
315Debian: libttf-dev
316Redhat: freetype1-devel
317
3183.8 Binaries
319------------
02d1d628 320
02d1d628
AMH
321Precompiled versions of some of the libraries might be found at:
322
323AIX:
02d1d628 324
f9a39263
TC
325 http://www.bullfreeware.com/
326
327Solaris:
02d1d628 328
f9a39263 329 http://www.sunfreeware.com/
02d1d628
AMH
330
331========================
3324. Logging and debugging
333========================
334
335Logging is compiled in by default - if you should want to get of it
336from the binaries you can do so by setting the env IMAGER_NOLOG
337to something. If you want to enable malloc debugging to check for leaks
338then set IMAGER_DEBUG_MALLOC to something. Needless to say it is
339pretty pointless to have malloc debug enabled with no logging since you
340can never see the malloc information that way.
341
342
02d1d628 343=================
8f22b8d8 3445. Win32 Support
02d1d628
AMH
345=================
346
347Imager can be installed on Win32 systems. This was ported and tested
faa9b3e7
TC
348with Microsoft Visual C++ 6.0 with build 623 of ActivePerl. You can
349use all of the features of Imager. You can also use Win32 GDI fonts
350directly by supplying the 'face' parameter to Imager::Font->new(...).
351
f9a39263 352I've tested with MSVC++ 6.0, cygwin (perl 5.6.1) and gcc (MinGW).
02d1d628 353
31c01e81
TC
354If you see an error under cygwin during testing along the lines of:
355
356 C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
357 same address as parent (0x...) != 0x....
358
359you will need to install the cygwin rebase package and run:
360
361 $ rebaseall -v
362
9c271ef0
TC
363If you get errors from your make tool, make sure you're using the same
364make that was used to build your perl - generally GNU make for cygwin,
365nmake for Visual C/C++ and dmake for MinGW.
02d1d628 366
f5bffc46
TC
367Imager and all of the libraries it requires are supplied with
368Strawberry Perl.
369
01b5a039
TC
370============
3716. Mac OS X
372============
373
374Building Imager under OS X is generally straightforward. There are
375some exceptions though:
376
377a) you may find to need to ranlib library files in place after you've
378 installed them, for example:
379
380 ranlib /usr/local/lib/libgif.a
381
382b) the version of GCC enabled by default on OS X 10.4 generates
383 incorrect code for some functions. To work around this run:
384
385 gcc_select 3
386
387 before building Imager and:
388
389 gcc_select 4
390
391 after building Imager.
392
393 This problem exhibits itself as test failures in t/t20fill.t
394
a32484c3
TC
395 Imager 0.56 includes a workaround for this problem, but I wasn't
396 able to test it.
397
01b5a039
TC
398c) if you want to build GCC 4.0 from scratch and use that you will
399 need to adjust the command-line supplied during the link stage, so
400 that there is some other option before the -bundle option.
401
402 For example:
403
404 perl Makefile.PL LDDLFLAGS="`perl -MConfig -e 'print "-g $Config{lddlflags}"'`"
bb0d0a74
TC
405
406d) The default perl build in Snow Leopard and Lion is a fat binary,
407 and default builds of giflib, libpng and libjpeg (and maybe other
408 libraries) will produce link failures.
409
410 To avoid this you need to supply a CFLAGS parameter to the
411 library's configure script, but since the -arch flag conflicts with
412 the options used to build the dependency files, you need to supply
413 another flag to disable dependency tracking.
414
415 Snow Leopard fat binaries include i386, x86_64 and PPC objects,
416 hence you would run configure like:
417
418 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
419
420 Lion doesn't support PPC, so there you run configure like:
421
422 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
423
424 For libgif you might also want to supply the --without-x option.
01b5a039 425
02d1d628 426=======================
01b5a039 4277. General information
02d1d628
AMH
428=======================
429
430The Imager module homepage is currently at:
431
31c01e81 432 http://imager.perl.org/
02d1d628 433
f6acebd0 434You can report bugs by pointing your browser at:
e8910022
TC
435
436 https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager
02d1d628
AMH
437
438========================
01b5a039 4398. Thanks
02d1d628
AMH
440========================
441
442Thanks go to:
443 Tony Cook ( TonyC )
444 Claes Jacobson ( Claes )
445 Philip Gwyn ( Leolo )
df917a00 446 Michael Slade ( Micksa )
23bf355e 447 ( Cogent )
02d1d628
AMH
448 Brad Murray ( HalfJack )
449 Nicholas Dronen ( Veblen )
450 Michael G Schwern ( Schwern )
451 Rocco Caputo ( Dngor )
452 Graham barr ( Gbarr )
453 Mark-Jason Dominus ( Mjd )
454 Jerome
455 Jason Alexander ( Jalex )
456 Randal R. Schwartz ( Merlyn )
457 Tkil ( )
458 Artur Bergman ( Sky )
459 Luc St-Louis ( Lucs )
460 PerlJam ( )
461 Roderick Schertler ( Roderick )
462 Nathan Torkington ( gnat )
f9a39263 463 Gabriel Vasseur
872def8b
TC
464 kmx
465 Nicolas Roggli
466 Justin Davis
467 Maurice Height
468 Krzysztof Wojtaƛ
469 David Cantrell
470 Eleneldil G. Arilou
471 Slaven Rezic
472 Richard Fairhurst
473 Nikita Dedik
02d1d628
AMH
474
475(and just to play it safe) all those I forgot to mention.