update desired debian packages
[imager.git] / lib / Imager / Install.pod
CommitLineData
be4b66bb
TC
1=for stopwords freetype MinGW dfont Redhat SDK IFD GDI TTF preprocessor Redhat-like
2
3=head1 NAME
4
5Imager::Install - installation notes for Imager
6
7=head1 SYNOPSIS
8
9 perl Makefile.PL
10 make
11 make test
12 make install
13
8ba1b8a6 14=head1 DESCRIPTION
be4b66bb
TC
15
16Assuming you have all of your required libraries in the places Imager
17looks, you should be able to use the standard mantra:
18
19 perl Makefile.PL
20 make
21 make test
22 make install
23
24to install Imager.
25
26If you've installed libraries in places Imager doesn't look, you can
27supply extra locations either with command-line options:
28
29 perl Makefile.PL --libpath=/home/tony/local/lib --incpath=/home/tony/local/include
30
31or with environment variables:
32
33 export IM_LIBPATH=/home/tony/local/lib IM_INCPATH=/home/tony/local/include
34 perl Makefile.PL
35
36Imager's F<Makefile.PL> produces an epilogue indicating which
37libraries have and haven't been found, for example:
38
39 Libraries found:
40 FT2
41 GIF
42 JPEG
43 PNG
44 T1
45 TIFF
46 Libraries *not* found:
47 Win32
48
49If a library you expect to be found isn't on this list, use the
50C<--verbose> or C<-v> option to produce way too much information from
51Imager's search for the libraries:
52
53 perl Makefile.PL -v
54
55If you can't resolve this, then run
56
57 perl errep.perl
58
59and include the (large) generated F<report.txt> in your email to:
60
61 bug-Imager@rt.cpan.org
62
63There are other options used to configure how Imager is built:
64
65=over
66
67=item C<--nolog>
68
69build Imager without logging support. This will speed up Imager a
70little. You can also remove logging by setting the C<IMAGER_NOLOG>
71environment variable to a true value.
72
73=item C<--coverage>
74
75used to build Imager for C<gcov> coverage testing. This is intended
76for development and also requires options supplied to C<make>.
77
78=item C<--assert>
79
80build Imager with assertions enabled.
81
82=item C<--tracecontext>
83
84build Imager to trace context object management to C<stderr> for
85debugging.
86
87=back
88
89=head2 Build time environment variables
90X<build time environment variables>
91
92=over
93
94=item *
95
96X<< C<IMAGER_NOLOG> >>C<IMAGER_NOLOG> - build Imager with logging disabled.
97
98=item *
99
100X<< C<IMAGER_DEBUG_MALLOC> >>C<IMAGER_DEBUG_MALLOC> - build Imager with it's
101debug malloc wrappers. This is I<not> compatible with threaded code.
102
103=item *
104
105X<< C<IM_INCPATH> >>C<IM_INCPATH> - equivalent to C<--incpath>.
106
107=item *
108
109X<< C<IM_LIBPATH> >>C<IM_LIBPATH> - equivalent to C<--libpath>.
110
111=item *
112
113X<< C<IM_VERBOSE> >>C<IM_VERBOSE> - equivalent to C<--verbose>
114
115=item *
116
117X<< C<IM_CFLAGS> >>C<IM_CFLAGS> - extra C compiler flags.
118
119=item *
120
121X<< C<IM_LFLAGS> >>C<IM_LFLAGS> - extra linker flags.
122
123=item *
124
125X<< C<IM_DFLAGS> >>C<IM_DFLAGS> - extra preprocessor flags.
126
127=back
128
129=head1 EXTERNAL LIBRARIES
130
131Some of the file format and font modules included with Imager use
132external libraries, which should be installed before you try to
133install Imager itself.
134
135If you don't have the libraries installed then Imager itself will
136install successfully, but the file format or font support module won't
137be.
138
139Preferably the latest version of each library should be used, simple
140because it has the latest security fixes.
141
142=head2 PNG - C<libpng>
143
144X<< C<libpng> >>L<Imager::File::PNG> uses L<< C<libpng>
145|http://www.libpng.org/pub/png/libpng.html >> for PNG image file
146support.
147
d153c79b 148Debian package: C<libpng-dev>
be4b66bb
TC
149
150Redhat package: C<libpng-devel>
151
d153c79b
TC
152Cygwin: C<libpng-devel>
153
be4b66bb
TC
154=head2 TIFF - C<libtiff>
155
156X<< C<libtiff> >>L<Imager::File::TIFF> uses
157L<< C<libtiff> |http://www.remotesensing.org/libtiff/ >> for GIF image file
158support.
159
160Version 3.6.0 or later is required to avoid an exploit with infinite
161IFD loops, though it's possible some distributions have applied the
162fix to older versions as a security fix.
163
164Version 3.9.0 is rejected during the probe process due to a serious
165bug, fixed in 3.9.1.
166
167Debian package: C<libtiff4-dev>
168
169Redhat package: C<libtiff-devel>
170
d153c79b
TC
171Cygwin: C<libtiff-devel>
172
be4b66bb
TC
173=head2 GIF - C<libgif>
174
175X<< C<libgif> >>L<Imager::File::GIF> uses
176L<< C<libgif> |http://sourceforge.net/projects/giflib/ >> for GIF image file
177support.
178
179C<libgif> releases 4.2.0 and 5.0.0 are specifically not supported, due
180to bugs in those versions.
181
182Release 4.1.4 or later should be used.
183
184C<giflib> 3 is no longer supported.
185
186C<libungif> is no longer supported as an alternative.
187
188Debian package: C<libgif-dev>
189
190Redhat package: C<giflib-devel>
191
d153c79b
TC
192Cygwin: C<libgif-devel>
193
be4b66bb
TC
194=head2 JPEG - C<libjpeg>
195
196L<Imager::File::JPEG> uses L<< C<libjpeg> |http://www.ijg.org/ >> for JPEG
197image file support.
198
199You may also use
200L<< C<libjpeg-turbo> |http://sourceforge.net/projects/libjpeg-turbo/ >>.
201
202To install older releases of C<libjpeg> from source, you'll need to
203run:
204
205 make install-lib
206
207to install the libraries. C<make install> only installs the program
208binaries.
209
210Redhat package: C<libjpeg-devel>
211
d153c79b
TC
212Debian package: C<libjpeg-dev>
213
214Cygwin: C<libjpeg-devel>
be4b66bb
TC
215
216=head2 Freetype 2.x - C<libfreetype>
217
218L<Imager::Font::FT2> uses L<< Freetype 2
219(C<libfreetype>)|http://www.freetype.org/ >> for font support, supporting
220too many font formats to mention here.
221
222This is the recommended library to use for font support.
223
224Debian package: C<libfreetype6-dev>
225
226Redhat package: C<freetype-devel>
227
d153c79b
TC
228Cygwin: C<libfreetype-devel>
229
be4b66bb
TC
230=head2 Win32 GDI fonts
231
232L<Imager::Font::W32> uses L<Win32
233GDI|http://msdn.microsoft.com/en-us/library/dd145203%28v=vs.85%29.aspx>
234to render text using installed Windows fonts.
235
236This requires Win32 SDK headers and libraries, and is only expected to
237work on native Win32 or Cygwin.
238
239For this to work under Cygwin, install the C<w32api-headers> and
240C<w32api-runtime> packages.
241
242=head2 C<t1lib>
243
244L<Imager::Font::T1> uses L<< C<t1lib> |http://www.t1lib.org/ >> for
245font support, supporting Postscript Type 1 fonts only.
246
d153c79b
TC
247T1Lib is abandonware, the latest released version has several bugs
248that reliably crash on 64-bit systems.
249
250Expect C<Imager::Font::T1> to be unbundled from the Imager
251distribution at some point.
252
be4b66bb
TC
253Debian package: C<libt1-dev>
254
255Redhat package: C<t1lib-devel>
256
257=head2 Freetype 1.x - C<libttf>
258
259Imager uses L<< Freetype 1 (C<libttf>)|http://www.freetype.org/ >> if
260available for font support, supporting TTF fonts only.
261
262Freetype 1.x is essentially unsupported and shouldn't be used for new
263code.
264
d153c79b
TC
265Expect Freetype 1 support to be removed from Imager at some point.
266
be4b66bb
TC
267=head1 PLATFORM SPECIFICS
268
269=head2 Linux
270
271Several distributions include an Imager package, but they are
272typically several releases behind due to the nature of release cycles.
273
274Imager typically supports the external libraries as packaged with any
275supported release of Linux.
276
277=head3 Debian
278
279To install the libraries used by Imager under Debian (or Ubuntu), run
280as root (or with sudo):
281
282 apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
283
284You may also need to install development tools:
285
286 apt-get install build-essential
287
288=head3 Redhat
289
290To install the libraries used by Imager under Redhat and related Linux
291distributions, run as root (or sudo):
292
293 yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
294
295To install the development tools needed:
296
297 yum install gcc
298
299(which appears to be enough on a base Redhat-like install) or the more
300commonly recommended recipe:
301
302 yum groupinstall "Development Tools"
303
304which is massive overkill.
305
306=head2 Mac OS X
307
308=head3 Building libraries
309
310The default perl build in Snow Leopard and Lion is a fat binary, and
311default builds of C<giflib>, C<libpng> and C<libjpeg> (and maybe other
312libraries) will produce link failures.
313
314To avoid this you need to supply a C<CFLAGS> parameter to the
315library's configure script, but since the C<-arch> flag conflicts with
316the options used to build the dependency files, you need to supply
317another flag to disable dependency tracking.
318
319Snow Leopard fat binaries include C<i386>, C<x86_64> and C<PPC>
320objects, hence you would run configure like:
321
322 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
323
324Lion doesn't support C<PPC>, so there you run configure like:
325
326 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
327
328For C<libgif> you might also want to supply the C<--without-x> option:
329
330 ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
331
332If you copy library files into place manually, you may need to run
333C<ranlib> on them in their new location:
334
335 ranlib /usr/local/lib/libgif.a
336
337=head3 Macintosh C<dfont> and suitcase font support
338
339Through Freetype 2.1, Imager can use Macintosh C<DFON> (C<.dfont>)
340fonts and suitcase font files.
341
342If you want to be able to use more than just the first face in the
343font file though, you will need to configure C<freetype2> with the
344--with-old-mac-fonts option:
345
346 ./configure --with-old-mac-fonts
347
348You can use the index option to get to the other font faces in the
349file:
350
351 # get the second face from $file
352 my $font = Imager::Font->new(file=>$file, index=>1)
353 or die Imager->errstr;
354
355If you're using a suitcase font, you will also need to force the use
356of Freetype 2 with the type argument:
357
358 my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
359 or die Imager->errstr;
360
361=head2 Microsoft Windows
362
363The simplest way to install the libraries used by Imager is to install
364L<Strawberry perl|http://strawberryperl.com/>.
365
366You can then use either the bundled Imager, or install from CPAN.
367
368If you get errors from your make tool, make sure you're using the same
369make that was used to build your perl - C<nmake> for Visual C/C++ and
370C<dmake> for MinGW, run:
371
372 perl -V:make
373
374to see which make was used to build your perl.
375
376=head2 Cygwin
377
378To build Imager with as much library support as possible on Cygwin,
379install the following packages:
380
381 libjpeg-devel libpng-devel libgif-devel libtiff-devel
382 libfreetype-devel t1lib-devel w32api-headers w32api-runtime
383
384If you see an error under cygwin during testing along the lines of:
385
386 C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
387 same address as parent (0x...) != 0x....
388
389you will need to install the cygwin C<rebase> package and run:
390
391 $ rebaseall -v
392
393or possibly, just:
394
395 $ perlrebase
396
d153c79b
TC
397will fix the problem. 64-bit Cygwin significantly reduces occurrences
398of this problem.
be4b66bb
TC
399
400=head1 Other issues
401
402=head2 Freetype 1.x vs Freetype 2.x
403
404Freetype 1.x is no longer recommended, is no longer supported
405upstream, and receives only limited updates in Imager.
406
407These two libraries have some conflicting include file names, but as
408long as you don't put the Freetype 2.x F<freetype.h> directory in the
409include path it should all work.
410
411Put the directory containing F<ft2build.h> in the include path, but
412not the directory containing the freetype 2.x F<freetype.h>.
413
414If you see compilation errors from font.c you've probably made the
415mistake of putting the Freetype 2.x F<freetype.h> directory into the
416include path.
417
418To see which directories should be in the include path, try:
419
420 freetype-config --cflags
421
422Ideally, C<freetype-config> should be in the PATH when building Imager
423with freetype 2.x support, in which case L<Imager::Font::FT2> can
424configure itself.
425
8ba1b8a6
TC
426=head1 AUTHOR
427
428Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
429
430=cut