5e8234bd910134334601acb847bb06e132f9f226
[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<libpng12-dev>
149
150 Redhat package: C<libpng-devel>
151
152 =head2 TIFF - C<libtiff>
153
154 X<< C<libtiff> >>L<Imager::File::TIFF> uses
155 L<< C<libtiff> |http://www.remotesensing.org/libtiff/ >> for GIF image file
156 support.
157
158 Version 3.6.0 or later is required to avoid an exploit with infinite
159 IFD loops, though it's possible some distributions have applied the
160 fix to older versions as a security fix.
161
162 Version 3.9.0 is rejected during the probe process due to a serious
163 bug, fixed in 3.9.1.
164
165 Debian package: C<libtiff4-dev>
166
167 Redhat package: C<libtiff-devel>
168
169 =head2 GIF - C<libgif>
170
171 X<< C<libgif> >>L<Imager::File::GIF> uses
172 L<< C<libgif> |http://sourceforge.net/projects/giflib/ >> for GIF image file
173 support.
174
175 C<libgif> releases 4.2.0 and 5.0.0 are specifically not supported, due
176 to bugs in those versions.
177
178 Release 4.1.4 or later should be used.
179
180 C<giflib> 3 is no longer supported.
181
182 C<libungif> is no longer supported as an alternative.
183
184 Debian package: C<libgif-dev>
185
186 Redhat package: C<giflib-devel>
187
188 =head2 JPEG - C<libjpeg>
189
190 L<Imager::File::JPEG> uses L<< C<libjpeg> |http://www.ijg.org/ >> for JPEG
191 image file support.
192
193 You may also use
194 L<< C<libjpeg-turbo> |http://sourceforge.net/projects/libjpeg-turbo/ >>.
195
196 To install older releases of C<libjpeg> from source, you'll need to
197 run:
198
199   make install-lib
200
201 to install the libraries.  C<make install> only installs the program
202 binaries.
203
204 Redhat package: C<libjpeg-devel>
205
206 Debian package: C<libjpeg8-dev>
207
208 =head2 Freetype 2.x - C<libfreetype>
209
210 L<Imager::Font::FT2> uses L<< Freetype 2
211 (C<libfreetype>)|http://www.freetype.org/ >> for font support, supporting
212 too many font formats to mention here.
213
214 This is the recommended library to use for font support.
215
216 Debian package: C<libfreetype6-dev>
217
218 Redhat package: C<freetype-devel>
219
220 =head2 Win32 GDI fonts
221
222 L<Imager::Font::W32> uses L<Win32
223 GDI|http://msdn.microsoft.com/en-us/library/dd145203%28v=vs.85%29.aspx>
224 to render text using installed Windows fonts.
225
226 This requires Win32 SDK headers and libraries, and is only expected to
227 work on native Win32 or Cygwin.
228
229 For this to work under Cygwin, install the C<w32api-headers> and
230 C<w32api-runtime> packages.
231
232 =head2 C<t1lib>
233
234 L<Imager::Font::T1> uses L<< C<t1lib> |http://www.t1lib.org/ >> for
235 font support, supporting Postscript Type 1 fonts only.
236
237 Debian package: C<libt1-dev>
238
239 Redhat package: C<t1lib-devel>
240
241 =head2 Freetype 1.x - C<libttf>
242
243 Imager uses L<< Freetype 1 (C<libttf>)|http://www.freetype.org/ >> if
244 available for font support, supporting TTF fonts only.
245
246 Freetype 1.x is essentially unsupported and shouldn't be used for new
247 code.
248
249 =head1 PLATFORM SPECIFICS
250
251 =head2 Linux
252
253 Several distributions include an Imager package, but they are
254 typically several releases behind due to the nature of release cycles.
255
256 Imager typically supports the external libraries as packaged with any
257 supported release of Linux.
258
259 =head3 Debian
260
261 To install the libraries used by Imager under Debian (or Ubuntu), run
262 as root (or with sudo):
263
264   apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
265
266 You may also need to install development tools:
267
268   apt-get install build-essential
269
270 =head3 Redhat
271
272 To install the libraries used by Imager under Redhat and related Linux
273 distributions, run as root (or sudo):
274
275   yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
276
277 To install the development tools needed:
278
279   yum install gcc
280
281 (which appears to be enough on a base Redhat-like install) or the more
282 commonly recommended recipe:
283
284   yum groupinstall "Development Tools"
285
286 which is massive overkill.
287
288 =head2 Mac OS X
289
290 =head3 Building libraries
291
292 The default perl build in Snow Leopard and Lion is a fat binary, and
293 default builds of C<giflib>, C<libpng> and C<libjpeg> (and maybe other
294 libraries) will produce link failures.
295
296 To avoid this you need to supply a C<CFLAGS> parameter to the
297 library's configure script, but since the C<-arch> flag conflicts with
298 the options used to build the dependency files, you need to supply
299 another flag to disable dependency tracking.
300
301 Snow Leopard fat binaries include C<i386>, C<x86_64> and C<PPC>
302 objects, hence you would run configure like:
303
304   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
305
306 Lion doesn't support C<PPC>, so there you run configure like:
307
308   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
309
310 For C<libgif> you might also want to supply the C<--without-x> option:
311
312   ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
313
314 If you copy library files into place manually, you may need to run
315 C<ranlib> on them in their new location:
316
317   ranlib /usr/local/lib/libgif.a
318
319 =head3 Macintosh C<dfont> and suitcase font support
320
321 Through Freetype 2.1, Imager can use Macintosh C<DFON> (C<.dfont>)
322 fonts and suitcase font files.
323
324 If you want to be able to use more than just the first face in the
325 font file though, you will need to configure C<freetype2> with the
326 --with-old-mac-fonts option:
327
328   ./configure --with-old-mac-fonts
329
330 You can use the index option to get to the other font faces in the
331 file:
332
333   # get the second face from $file
334   my $font = Imager::Font->new(file=>$file, index=>1)
335     or die Imager->errstr;
336
337 If you're using a suitcase font, you will also need to force the use
338 of Freetype 2 with the type argument:
339
340   my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
341     or die Imager->errstr;
342
343 =head2 Microsoft Windows
344
345 The simplest way to install the libraries used by Imager is to install
346 L<Strawberry perl|http://strawberryperl.com/>.
347
348 You can then use either the bundled Imager, or install from CPAN.
349
350 If you get errors from your make tool, make sure you're using the same
351 make that was used to build your perl - C<nmake> for Visual C/C++ and
352 C<dmake> for MinGW, run:
353
354   perl -V:make
355
356 to see which make was used to build your perl.
357
358 =head2 Cygwin
359
360 To build Imager with as much library support as possible on Cygwin,
361 install the following packages:
362
363   libjpeg-devel libpng-devel libgif-devel libtiff-devel
364   libfreetype-devel t1lib-devel w32api-headers w32api-runtime
365
366 If you see an error under cygwin during testing along the lines of:
367
368   C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the 
369     same address as parent (0x...) != 0x....
370
371 you will need to install the cygwin C<rebase> package and run:
372
373   $ rebaseall -v
374
375 or possibly, just:
376
377   $ perlrebase
378
379 will fix the problem.
380
381 =head1 Other issues
382
383 =head2 Freetype 1.x vs Freetype 2.x
384
385 Freetype 1.x is no longer recommended, is no longer supported
386 upstream, and receives only limited updates in Imager.
387
388 These two libraries have some conflicting include file names, but as
389 long as you don't put the Freetype 2.x F<freetype.h> directory in the
390 include path it should all work.
391
392 Put the directory containing F<ft2build.h> in the include path, but
393 not the directory containing the freetype 2.x F<freetype.h>.
394
395 If you see compilation errors from font.c you've probably made the
396 mistake of putting the Freetype 2.x F<freetype.h> directory into the
397 include path.
398
399 To see which directories should be in the include path, try:
400
401   freetype-config --cflags
402
403 Ideally, C<freetype-config> should be in the PATH when building Imager
404 with freetype 2.x support, in which case L<Imager::Font::FT2> can
405 configure itself.
406
407 =head1 AUTHOR
408
409 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
410
411 =cut