1Imager::Install(3)    User Contributed Perl Documentation   Imager::Install(3)
2
3
4

NAME

6       Imager::Install - installation notes for Imager
7

SYNOPSIS

9         perl Makefile.PL
10         make
11         make test
12         make install
13

DESCRIPTION

15       Assuming you have all of your required libraries in the places Imager
16       looks, you should be able to use the standard mantra:
17
18         perl Makefile.PL
19         make
20         make test
21         make install
22
23       to install Imager.
24
25       If you've installed libraries in places Imager doesn't look, you can
26       supply extra locations either with command-line options:
27
28         perl Makefile.PL --libpath=/home/tony/local/lib --incpath=/home/tony/local/include
29
30       or with environment variables:
31
32         export IM_LIBPATH=/home/tony/local/lib IM_INCPATH=/home/tony/local/include
33         perl Makefile.PL
34
35       Imager's Makefile.PL produces an epilogue indicating which libraries
36       have and haven't been found, for example:
37
38         Libraries found:
39           FT2
40           GIF
41           JPEG
42           PNG
43           T1
44           TIFF
45         Libraries *not* found:
46           Win32
47
48       If a library you expect to be found isn't on this list, use the
49       "--verbose" or "-v" option to produce way too much information from
50       Imager's search for the libraries:
51
52         perl Makefile.PL -v
53
54       If you can't resolve this, then run
55
56         perl errep.perl
57
58       and include the (large) generated report.txt in your email to:
59
60         bug-Imager@rt.cpan.org
61
62       There are other options used to configure how Imager is built:
63
64       "--nolog"
65           build Imager without logging support.  This will speed up Imager a
66           little.  You can also remove logging by setting the "IMAGER_NOLOG"
67           environment variable to a true value.
68
69       "--coverage"
70           used to build Imager for "gcov" coverage testing.  This is intended
71           for development and also requires options supplied to "make".
72
73       "--assert"
74           build Imager with assertions enabled.
75
76       "--tracecontext"
77           build Imager to trace context object management to "stderr" for
78           debugging.
79
80   Build time environment variables
81       ·   "IMAGER_NOLOG" - build Imager with logging disabled.
82
83       ·   "IMAGER_DEBUG_MALLOC" - build Imager with it's debug malloc
84           wrappers.  This is not compatible with threaded code.
85
86       ·   "IM_INCPATH" - equivalent to "--incpath".
87
88       ·   "IM_LIBPATH" - equivalent to "--libpath".
89
90       ·   "IM_VERBOSE" - equivalent to "--verbose"
91
92       ·   "IM_CFLAGS" - extra C compiler flags.
93
94       ·   "IM_LFLAGS" - extra linker flags.
95
96       ·   "IM_DFLAGS" - extra preprocessor flags.
97

EXTERNAL LIBRARIES

99       Some of the file format and font modules included with Imager use
100       external libraries, which should be installed before you try to install
101       Imager itself.
102
103       If you don't have the libraries installed then Imager itself will
104       install successfully, but the file format or font support module won't
105       be.
106
107       Preferably the latest version of each library should be used, simple
108       because it has the latest security fixes.
109
110   PNG - "libpng"
111       Imager::File::PNG uses "libpng"
112        <http://www.libpng.org/pub/png/libpng.html> for PNG image file
113       support.
114
115       Debian package: "libpng-dev"
116
117       Redhat package: "libpng-devel"
118
119       Cygwin: "libpng-devel"
120
121   TIFF - "libtiff"
122       Imager::File::TIFF uses "libtiff"
123       <http://www.remotesensing.org/libtiff/> for GIF image file support.
124
125       Version 3.6.0 or later is required to avoid an exploit with infinite
126       IFD loops, though it's possible some distributions have applied the fix
127       to older versions as a security fix.
128
129       Version 3.9.0 is rejected during the probe process due to a serious
130       bug, fixed in 3.9.1.
131
132       Debian package: "libtiff4-dev"
133
134       Redhat package: "libtiff-devel"
135
136       Cygwin: "libtiff-devel"
137
138   GIF - "libgif"
139       Imager::File::GIF uses "libgif"
140       <http://sourceforge.net/projects/giflib/> for GIF image file support.
141
142       "libgif" releases 4.2.0 and 5.0.0 are specifically not supported, due
143       to bugs in those versions.
144
145       Release 4.1.4 or later should be used.
146
147       "giflib" 3 is no longer supported.
148
149       "libungif" is no longer supported as an alternative.
150
151       Debian package: "libgif-dev"
152
153       Redhat package: "giflib-devel"
154
155       Cygwin: "libgif-devel"
156
157   JPEG - "libjpeg"
158       Imager::File::JPEG uses "libjpeg"  <http://www.ijg.org/> for JPEG image
159       file support.
160
161       You may also use "libjpeg-turbo"
162       <http://sourceforge.net/projects/libjpeg-turbo/>.
163
164       To install older releases of "libjpeg" from source, you'll need to run:
165
166         make install-lib
167
168       to install the libraries.  "make install" only installs the program
169       binaries.
170
171       Redhat package: "libjpeg-devel"
172
173       Debian package: "libjpeg-dev"
174
175       Cygwin: "libjpeg-devel"
176
177   Freetype 2.x - "libfreetype"
178       Imager::Font::FT2 uses Freetype 2 ("libfreetype")
179       <http://www.freetype.org/> for font support, supporting too many font
180       formats to mention here.
181
182       This is the recommended library to use for font support.
183
184       Debian package: "libfreetype6-dev"
185
186       Redhat package: "freetype-devel"
187
188       Cygwin: "libfreetype-devel"
189
190   Win32 GDI fonts
191       Imager::Font::W32 uses Win32 GDI <http://msdn.microsoft.com/en-
192       us/library/dd145203%28v=vs.85%29.aspx> to render text using installed
193       Windows fonts.
194
195       This requires Win32 SDK headers and libraries, and is only expected to
196       work on native Win32 or Cygwin.
197
198       For this to work under Cygwin, install the "w32api-headers" and
199       "w32api-runtime" packages.
200
201   "t1lib"
202       Imager::Font::T1 uses "t1lib"  <http://www.t1lib.org/> for font
203       support, supporting Postscript Type 1 fonts only.
204
205       T1Lib is abandonware, the latest released version has several bugs that
206       reliably crash on 64-bit systems.
207
208       Expect "Imager::Font::T1" to be unbundled from the Imager distribution
209       at some point.
210
211       Debian package: "libt1-dev"
212
213       Redhat package: "t1lib-devel"
214
215   Freetype 1.x - "libttf"
216       Imager uses Freetype 1 ("libttf") <http://www.freetype.org/> if
217       available for font support, supporting TTF fonts only.
218
219       Freetype 1.x is essentially unsupported and shouldn't be used for new
220       code.
221
222       Expect Freetype 1 support to be removed from Imager at some point.
223

PLATFORM SPECIFICS

225   Linux
226       Several distributions include an Imager package, but they are typically
227       several releases behind due to the nature of release cycles.
228
229       Imager typically supports the external libraries as packaged with any
230       supported release of Linux.
231
232       Debian
233
234       To install the libraries used by Imager under Debian (or Ubuntu), run
235       as root (or with sudo):
236
237         apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
238
239       You may also need to install development tools:
240
241         apt-get install build-essential
242
243       Redhat
244
245       To install the libraries used by Imager under Redhat and related Linux
246       distributions, run as root (or sudo):
247
248         yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
249
250       To install the development tools needed:
251
252         yum install gcc
253
254       (which appears to be enough on a base Redhat-like install) or the more
255       commonly recommended recipe:
256
257         yum groupinstall "Development Tools"
258
259       which is massive overkill.
260
261   Mac OS X
262       Building libraries
263
264       The default perl build in Snow Leopard and Lion is a fat binary, and
265       default builds of "giflib", "libpng" and "libjpeg" (and maybe other
266       libraries) will produce link failures.
267
268       To avoid this you need to supply a "CFLAGS" parameter to the library's
269       configure script, but since the "-arch" flag conflicts with the options
270       used to build the dependency files, you need to supply another flag to
271       disable dependency tracking.
272
273       Snow Leopard fat binaries include "i386", "x86_64" and "PPC" objects,
274       hence you would run configure like:
275
276         ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
277
278       Lion doesn't support "PPC", so there you run configure like:
279
280         ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
281
282       For "libgif" you might also want to supply the "--without-x" option:
283
284         ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
285
286       If you copy library files into place manually, you may need to run
287       "ranlib" on them in their new location:
288
289         ranlib /usr/local/lib/libgif.a
290
291       Macintosh "dfont" and suitcase font support
292
293       Through Freetype 2.1, Imager can use Macintosh "DFON" (".dfont") fonts
294       and suitcase font files.
295
296       If you want to be able to use more than just the first face in the font
297       file though, you will need to configure "freetype2" with the
298       --with-old-mac-fonts option:
299
300         ./configure --with-old-mac-fonts
301
302       You can use the index option to get to the other font faces in the
303       file:
304
305         # get the second face from $file
306         my $font = Imager::Font->new(file=>$file, index=>1)
307           or die Imager->errstr;
308
309       If you're using a suitcase font, you will also need to force the use of
310       Freetype 2 with the type argument:
311
312         my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
313           or die Imager->errstr;
314
315   Microsoft Windows
316       The simplest way to install the libraries used by Imager is to install
317       Strawberry perl <http://strawberryperl.com/>.
318
319       You can then use either the bundled Imager, or install from CPAN.
320
321       If you get errors from your make tool, make sure you're using the same
322       make that was used to build your perl - "nmake" for Visual C/C++ and
323       "dmake" for MinGW, run:
324
325         perl -V:make
326
327       to see which make was used to build your perl.
328
329   Cygwin
330       To build Imager with as much library support as possible on Cygwin,
331       install the following packages:
332
333         libjpeg-devel libpng-devel libgif-devel libtiff-devel
334         libfreetype-devel t1lib-devel w32api-headers w32api-runtime
335
336       If you see an error under cygwin during testing along the lines of:
337
338         C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
339           same address as parent (0x...) != 0x....
340
341       you will need to install the cygwin "rebase" package and run:
342
343         $ rebaseall -v
344
345       or possibly, just:
346
347         $ perlrebase
348
349       will fix the problem.  64-bit Cygwin significantly reduces occurrences
350       of this problem.
351

Other issues

353   Freetype 1.x vs Freetype 2.x
354       Freetype 1.x is no longer recommended, is no longer supported upstream,
355       and receives only limited updates in Imager.
356
357       These two libraries have some conflicting include file names, but as
358       long as you don't put the Freetype 2.x freetype.h directory in the
359       include path it should all work.
360
361       Put the directory containing ft2build.h in the include path, but not
362       the directory containing the freetype 2.x freetype.h.
363
364       If you see compilation errors from font.c you've probably made the
365       mistake of putting the Freetype 2.x freetype.h directory into the
366       include path.
367
368       To see which directories should be in the include path, try:
369
370         freetype-config --cflags
371
372       Ideally, "freetype-config" should be in the PATH when building Imager
373       with freetype 2.x support, in which case Imager::Font::FT2 can
374       configure itself.
375

AUTHOR

377       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
378
379
380
381perl v5.32.0                      2020-07-28                Imager::Install(3)
Impressum