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 report at:
59
60         https://github.com/tonycoz/imager/issues
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       "--enable=feature"",feature" ...
81       "--disable=feature"",feature" ...
82           Enable or disable attempting to build bundled modules.  This only
83           has an effect on modules are also available on CPAN that are
84           bundled with Imager for historical reasons.
85
86           You can use "--enable=none" to prevent attempting to install any of
87           the bundled modules.
88
89           You can use either of "--enable" or "--disable" but not both.
90
91   Build time environment variables
92       •   "IM_ENABLE" - if set, a comma separated list of bundled modules to
93           try to build.  This can be set to "none" to build none of them.
94           There is no environment variable corresponding to "--disable".
95
96       •   "IMAGER_NOLOG" - build Imager with logging disabled.
97
98       •   "IMAGER_DEBUG_MALLOC" - build Imager with it's debug malloc
99           wrappers.  This is not compatible with threaded code.
100
101       •   "IM_INCPATH" - equivalent to "--incpath".
102
103       •   "IM_LIBPATH" - equivalent to "--libpath".
104
105       •   "IM_VERBOSE" - equivalent to "--verbose"
106
107       •   "IM_CFLAGS" - extra C compiler flags.
108
109       •   "IM_LFLAGS" - extra linker flags.
110
111       •   "IM_DFLAGS" - extra preprocessor flags.
112

EXTERNAL LIBRARIES

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

PLATFORM SPECIFICS

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

Other issues

373   Freetype 1.x vs Freetype 2.x
374       Freetype 1.x is no longer recommended, is no longer supported upstream,
375       and receives only limited updates in Imager.
376
377       These two libraries have some conflicting include file names, but as
378       long as you don't put the Freetype 2.x freetype.h directory in the
379       include path it should all work.
380
381       Put the directory containing ft2build.h in the include path, but not
382       the directory containing the freetype 2.x freetype.h.
383
384       If you see compilation errors from font.c you've probably made the
385       mistake of putting the Freetype 2.x freetype.h directory into the
386       include path.
387
388       To see which directories should be in the include path, try:
389
390         freetype-config --cflags
391
392       Ideally, "freetype-config" should be in the PATH when building Imager
393       with freetype 2.x support, in which case Imager::Font::FT2 can
394       configure itself.
395

AUTHOR

397       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
398
399
400
401perl v5.38.0                      2023-07-20                Imager::Install(3)
Impressum