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