Commit | Line | Data |
---|---|---|
be4b66bb TC |
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 | ||
8ba1b8a6 | 14 | =head1 DESCRIPTION |
be4b66bb TC |
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 | ||
d153c79b | 148 | Debian package: C<libpng-dev> |
be4b66bb TC |
149 | |
150 | Redhat package: C<libpng-devel> | |
151 | ||
d153c79b TC |
152 | Cygwin: C<libpng-devel> |
153 | ||
be4b66bb TC |
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 | ||
d153c79b TC |
171 | Cygwin: C<libtiff-devel> |
172 | ||
be4b66bb TC |
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 | ||
d153c79b TC |
192 | Cygwin: C<libgif-devel> |
193 | ||
be4b66bb TC |
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 | ||
d153c79b TC |
212 | Debian package: C<libjpeg-dev> |
213 | ||
214 | Cygwin: C<libjpeg-devel> | |
be4b66bb TC |
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 | ||
d153c79b TC |
228 | Cygwin: C<libfreetype-devel> |
229 | ||
be4b66bb TC |
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 | ||
d153c79b TC |
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 | ||
be4b66bb TC |
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 | ||
d153c79b TC |
265 | Expect Freetype 1 support to be removed from Imager at some point. |
266 | ||
be4b66bb TC |
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 | ||
d153c79b TC |
397 | will fix the problem. 64-bit Cygwin significantly reduces occurrences |
398 | of this problem. | |
be4b66bb TC |
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 | ||
8ba1b8a6 TC |
426 | =head1 AUTHOR |
427 | ||
428 | Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson | |
429 | ||
430 | =cut |