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