deprecate Imager::Font::T1
[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 =for stopwords
248 abandonware
249
250 T1Lib is abandonware, the latest released version has several bugs
251 that reliably crash on 64-bit systems.
252
253 Expect C<Imager::Font::T1> to be unbundled from the Imager
254 distribution at some point.
255
256 Debian package: C<libt1-dev>
257
258 Redhat package: C<t1lib-devel>
259
260 =head2 Freetype 1.x - C<libttf>
261
262 Imager uses L<< Freetype 1 (C<libttf>)|http://www.freetype.org/ >> if
263 available for font support, supporting TTF fonts only.
264
265 Freetype 1.x is essentially unsupported and shouldn't be used for new
266 code.
267
268 Expect Freetype 1 support to be removed from Imager at some point.
269
270 =head1 PLATFORM SPECIFICS
271
272 =head2 Linux
273
274 Several distributions include an Imager package, but they are
275 typically several releases behind due to the nature of release cycles.
276
277 Imager typically supports the external libraries as packaged with any
278 supported release of Linux.
279
280 =head3 Debian
281
282 To install the libraries used by Imager under Debian (or Ubuntu), run
283 as root (or with sudo):
284
285   apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
286
287 You may also need to install development tools:
288
289   apt-get install build-essential
290
291 =head3 Redhat
292
293 To install the libraries used by Imager under Redhat and related Linux
294 distributions, run as root (or sudo):
295
296   yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
297
298 To install the development tools needed:
299
300   yum install gcc
301
302 (which appears to be enough on a base Redhat-like install) or the more
303 commonly recommended recipe:
304
305   yum groupinstall "Development Tools"
306
307 which is massive overkill.
308
309 =head2 Mac OS X
310
311 =head3 Building libraries
312
313 The default perl build in Snow Leopard and Lion is a fat binary, and
314 default builds of C<giflib>, C<libpng> and C<libjpeg> (and maybe other
315 libraries) will produce link failures.
316
317 To avoid this you need to supply a C<CFLAGS> parameter to the
318 library's configure script, but since the C<-arch> flag conflicts with
319 the options used to build the dependency files, you need to supply
320 another flag to disable dependency tracking.
321
322 Snow Leopard fat binaries include C<i386>, C<x86_64> and C<PPC>
323 objects, hence you would run configure like:
324
325   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
326
327 Lion doesn't support C<PPC>, so there you run configure like:
328
329   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
330
331 For C<libgif> you might also want to supply the C<--without-x> option:
332
333   ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
334
335 If you copy library files into place manually, you may need to run
336 C<ranlib> on them in their new location:
337
338   ranlib /usr/local/lib/libgif.a
339
340 =head3 Macintosh C<dfont> and suitcase font support
341
342 Through Freetype 2.1, Imager can use Macintosh C<DFON> (C<.dfont>)
343 fonts and suitcase font files.
344
345 If you want to be able to use more than just the first face in the
346 font file though, you will need to configure C<freetype2> with the
347 --with-old-mac-fonts option:
348
349   ./configure --with-old-mac-fonts
350
351 You can use the index option to get to the other font faces in the
352 file:
353
354   # get the second face from $file
355   my $font = Imager::Font->new(file=>$file, index=>1)
356     or die Imager->errstr;
357
358 If you're using a suitcase font, you will also need to force the use
359 of Freetype 2 with the type argument:
360
361   my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
362     or die Imager->errstr;
363
364 =head2 Microsoft Windows
365
366 The simplest way to install the libraries used by Imager is to install
367 L<Strawberry perl|http://strawberryperl.com/>.
368
369 You can then use either the bundled Imager, or install from CPAN.
370
371 If you get errors from your make tool, make sure you're using the same
372 make that was used to build your perl - C<nmake> for Visual C/C++ and
373 C<dmake> for MinGW, run:
374
375   perl -V:make
376
377 to see which make was used to build your perl.
378
379 =head2 Cygwin
380
381 To build Imager with as much library support as possible on Cygwin,
382 install the following packages:
383
384   libjpeg-devel libpng-devel libgif-devel libtiff-devel
385   libfreetype-devel t1lib-devel w32api-headers w32api-runtime
386
387 If you see an error under cygwin during testing along the lines of:
388
389   C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the 
390     same address as parent (0x...) != 0x....
391
392 you will need to install the cygwin C<rebase> package and run:
393
394   $ rebaseall -v
395
396 or possibly, just:
397
398   $ perlrebase
399
400 will fix the problem.  64-bit Cygwin significantly reduces occurrences
401 of this problem.
402
403 =head1 Other issues
404
405 =head2 Freetype 1.x vs Freetype 2.x
406
407 Freetype 1.x is no longer recommended, is no longer supported
408 upstream, and receives only limited updates in Imager.
409
410 These two libraries have some conflicting include file names, but as
411 long as you don't put the Freetype 2.x F<freetype.h> directory in the
412 include path it should all work.
413
414 Put the directory containing F<ft2build.h> in the include path, but
415 not the directory containing the freetype 2.x F<freetype.h>.
416
417 If you see compilation errors from font.c you've probably made the
418 mistake of putting the Freetype 2.x F<freetype.h> directory into the
419 include path.
420
421 To see which directories should be in the include path, try:
422
423   freetype-config --cflags
424
425 Ideally, C<freetype-config> should be in the PATH when building Imager
426 with freetype 2.x support, in which case L<Imager::Font::FT2> can
427 configure itself.
428
429 =head1 AUTHOR
430
431 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
432
433 =cut