1Imager::Install(3) User Contributed Perl Documentation Imager::Install(3)
2
6 Imager::Install - installation notes for Imager
7
9 perl Makefile.PL
10 make
11 make test
12 make install
13
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 perl Makefile.PL
19 make
20 make test
21 make install
22 to install Imager.
24 If you've installed libraries in places Imager doesn't look, you can
26 supply extra locations either with command-line options:
27 perl Makefile.PL --libpath=/home/tony/local/lib --incpath=/home/tony/local/include
29 or with environment variables:
31 export IM_LIBPATH=/home/tony/local/lib IM_INCPATH=/home/tony/local/include
33 perl Makefile.PL
34 Imager's Makefile.PL produces an epilogue indicating which libraries
36 have and haven't been found, for example:
37 Libraries found:
39 FT2
40 GIF
41 JPEG
42 PNG
43 T1
44 TIFF
45 Libraries *not* found:
46 Win32
47 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 perl Makefile.PL -v
53 If you can't resolve this, then run
55 perl errep.perl
57 and include the (large) generated report.txt in your report at:
59 https://github.com/tonycoz/imager/issues
61 There are other options used to configure how Imager is built:
63 "--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 "--coverage"
70 used to build Imager for "gcov" coverage testing. This is intended
71 for development and also requires options supplied to "make".
72 "--assert"
74 build Imager with assertions enabled.
75 "--tracecontext"
77 build Imager to trace context object management to "stderr" for
78 debugging.
79 "--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 You can use "--enable=none" to prevent attempting to install any of
87 the bundled modules.
88 You can use either of "--enable" or "--disable" but not both.
90 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 • "IMAGER_NOLOG" - build Imager with logging disabled.
97 • "IMAGER_DEBUG_MALLOC" - build Imager with it's debug malloc
99 wrappers. This is not compatible with threaded code.
100 • "IM_INCPATH" - equivalent to "--incpath".
102 • "IM_LIBPATH" - equivalent to "--libpath".
104 • "IM_VERBOSE" - equivalent to "--verbose"
106 • "IM_CFLAGS" - extra C compiler flags.
108 • "IM_LFLAGS" - extra linker flags.
110 • "IM_DFLAGS" - extra preprocessor flags.
112
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 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 Preferably the latest version of each library should be used, simple
123 because it has the latest security fixes.
124 PNG - "libpng"
126 Imager::File::PNG uses "libpng"
127 <http://www.libpng.org/pub/png/libpng.html> for PNG image file
128 support.
129 Debian package: "libpng-dev"
131 Redhat package: "libpng-devel"
133 Cygwin: "libpng-devel"
135 TIFF - "libtiff"
137 Imager::File::TIFF uses "libtiff"
138 <http://www.remotesensing.org/libtiff/> for GIF image file support.
139 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 Version 3.9.0 is rejected during the probe process due to a serious
145 bug, fixed in 3.9.1.
146 Debian package: "libtiff4-dev"
148 Redhat package: "libtiff-devel"
150 Cygwin: "libtiff-devel"
152 GIF - "libgif"
154 Imager::File::GIF uses "libgif"
155 <http://sourceforge.net/projects/giflib/> for GIF image file support.
156 "libgif" releases 4.2.0 and 5.0.0 are specifically not supported, due
158 to bugs in those versions.
159 Release 4.1.4 or later should be used.
161 "giflib" 3 is no longer supported.
163 "libungif" is no longer supported as an alternative.
165 Debian package: "libgif-dev"
167 Redhat package: "giflib-devel"
169 Cygwin: "libgif-devel"
171 JPEG - "libjpeg"
173 Imager::File::JPEG uses "libjpeg" <http://www.ijg.org/> for JPEG image
174 file support.
175 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 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 To install older releases of "libjpeg" from source, you'll need to run:
185 make install-lib
187 to install the libraries. "make install" only installs the program
189 binaries.
190 Redhat package: "libjpeg-devel"
192 Debian package: "libjpeg-dev"
194 Cygwin: "libjpeg-devel"
196 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 This is the recommended library to use for font support.
203 Debian package: "libfreetype6-dev"
205 Redhat package: "freetype-devel"
207 Cygwin: "libfreetype-devel"
209 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 This requires Win32 SDK headers and libraries, and is only expected to
216 work on native Win32 or Cygwin.
217 For this to work under Cygwin, install the "w32api-headers" and
219 "w32api-runtime" packages.
220 "t1lib"
222 Imager::Font::T1 uses "t1lib" <http://www.t1lib.org/> for font
223 support, supporting Postscript Type 1 fonts only.
224 T1Lib is abandonware, the latest released version has several bugs that
226 reliably crash on 64-bit systems.
227 Expect "Imager::Font::T1" to be unbundled from the Imager distribution
229 at some point.
230 Debian package: "libt1-dev"
232 Redhat package: "t1lib-devel"
234 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 Freetype 1.x is essentially unsupported and shouldn't be used for new
240 code.
241 Expect Freetype 1 support to be removed from Imager at some point.
243
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 Imager typically supports the external libraries as packaged with any
250 supported release of Linux.
251 Debian
253 To install the libraries used by Imager under Debian (or Ubuntu), run
255 as root (or with sudo):
256 apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
258 You may also need to install development tools:
260 apt-get install build-essential
262 Redhat
264 To install the libraries used by Imager under Redhat and related Linux
266 distributions, run as root (or sudo):
267 yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
269 To install the development tools needed:
271 yum install gcc
273 (which appears to be enough on a base Redhat-like install) or the more
275 commonly recommended recipe:
276 yum groupinstall "Development Tools"
278 which is massive overkill.
280 Mac OS X
282 Building libraries
283 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 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 Snow Leopard fat binaries include "i386", "x86_64" and "PPC" objects,
294 hence you would run configure like:
295 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
297 Lion doesn't support "PPC", so there you run configure like:
299 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
301 For "libgif" you might also want to supply the "--without-x" option:
303 ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
305 If you copy library files into place manually, you may need to run
307 "ranlib" on them in their new location:
308 ranlib /usr/local/lib/libgif.a
310 Macintosh "dfont" and suitcase font support
312 Through Freetype 2.1, Imager can use Macintosh "DFON" (".dfont") fonts
314 and suitcase font files.
315 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 ./configure --with-old-mac-fonts
321 You can use the index option to get to the other font faces in the
323 file:
324 # get the second face from $file
326 my $font = Imager::Font->new(file=>$file, index=>1)
327 or die Imager->errstr;
328 If you're using a suitcase font, you will also need to force the use of
330 Freetype 2 with the type argument:
331 my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
333 or die Imager->errstr;
334 Microsoft Windows
336 The simplest way to install the libraries used by Imager is to install
337 Strawberry perl <http://strawberryperl.com/>.
338 You can then use either the bundled Imager, or install from CPAN.
340 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 perl -V:make
346 to see which make was used to build your perl.
348 Cygwin
350 To build Imager with as much library support as possible on Cygwin,
351 install the following packages:
352 libjpeg-devel libpng-devel libgif-devel libtiff-devel
354 libfreetype-devel t1lib-devel w32api-headers w32api-runtime
355 If you see an error under cygwin during testing along the lines of:
357 C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
359 same address as parent (0x...) != 0x....
360 you will need to install the cygwin "rebase" package and run:
362 $ rebaseall -v
364 or possibly, just:
366 $ perlrebase
368 will fix the problem. 64-bit Cygwin significantly reduces occurrences
370 of this problem.
371
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 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 Put the directory containing ft2build.h in the include path, but not
382 the directory containing the freetype 2.x freetype.h.
383 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 To see which directories should be in the include path, try:
389 freetype-config --cflags
391 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
397 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
398perl v5.38.0 2023-07-20 Imager::Install(3)