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