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 email to:
59 bug-Imager@rt.cpan.org
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 Build time environment variables
81 · "IMAGER_NOLOG" - build Imager with logging disabled.
82 · "IMAGER_DEBUG_MALLOC" - build Imager with it's debug malloc
84 wrappers. This is not compatible with threaded code.
85 · "IM_INCPATH" - equivalent to "--incpath".
87 · "IM_LIBPATH" - equivalent to "--libpath".
89 · "IM_VERBOSE" - equivalent to "--verbose"
91 · "IM_CFLAGS" - extra C compiler flags.
93 · "IM_LFLAGS" - extra linker flags.
95 · "IM_DFLAGS" - extra preprocessor flags.
97
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 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 Preferably the latest version of each library should be used, simple
108 because it has the latest security fixes.
109 PNG - "libpng"
111 Imager::File::PNG uses "libpng"
112 <http://www.libpng.org/pub/png/libpng.html> for PNG image file
113 support.
114 Debian package: "libpng-dev"
116 Redhat package: "libpng-devel"
118 Cygwin: "libpng-devel"
120 TIFF - "libtiff"
122 Imager::File::TIFF uses "libtiff"
123 <http://www.remotesensing.org/libtiff/> for GIF image file support.
124 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 Version 3.9.0 is rejected during the probe process due to a serious
130 bug, fixed in 3.9.1.
131 Debian package: "libtiff4-dev"
133 Redhat package: "libtiff-devel"
135 Cygwin: "libtiff-devel"
137 GIF - "libgif"
139 Imager::File::GIF uses "libgif"
140 <http://sourceforge.net/projects/giflib/> for GIF image file support.
141 "libgif" releases 4.2.0 and 5.0.0 are specifically not supported, due
143 to bugs in those versions.
144 Release 4.1.4 or later should be used.
146 "giflib" 3 is no longer supported.
148 "libungif" is no longer supported as an alternative.
150 Debian package: "libgif-dev"
152 Redhat package: "giflib-devel"
154 Cygwin: "libgif-devel"
156 JPEG - "libjpeg"
158 Imager::File::JPEG uses "libjpeg" <http://www.ijg.org/> for JPEG image
159 file support.
160 You may also use "libjpeg-turbo"
162 <http://sourceforge.net/projects/libjpeg-turbo/>.
163 To install older releases of "libjpeg" from source, you'll need to run:
165 make install-lib
167 to install the libraries. "make install" only installs the program
169 binaries.
170 Redhat package: "libjpeg-devel"
172 Debian package: "libjpeg-dev"
174 Cygwin: "libjpeg-devel"
176 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 This is the recommended library to use for font support.
183 Debian package: "libfreetype6-dev"
185 Redhat package: "freetype-devel"
187 Cygwin: "libfreetype-devel"
189 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 This requires Win32 SDK headers and libraries, and is only expected to
196 work on native Win32 or Cygwin.
197 For this to work under Cygwin, install the "w32api-headers" and
199 "w32api-runtime" packages.
200 "t1lib"
202 Imager::Font::T1 uses "t1lib" <http://www.t1lib.org/> for font
203 support, supporting Postscript Type 1 fonts only.
204 T1Lib is abandonware, the latest released version has several bugs that
206 reliably crash on 64-bit systems.
207 Expect "Imager::Font::T1" to be unbundled from the Imager distribution
209 at some point.
210 Debian package: "libt1-dev"
212 Redhat package: "t1lib-devel"
214 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 Freetype 1.x is essentially unsupported and shouldn't be used for new
220 code.
221 Expect Freetype 1 support to be removed from Imager at some point.
223
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 Imager typically supports the external libraries as packaged with any
230 supported release of Linux.
231 Debian
233 To install the libraries used by Imager under Debian (or Ubuntu), run
235 as root (or with sudo):
236 apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
238 You may also need to install development tools:
240 apt-get install build-essential
242 Redhat
244 To install the libraries used by Imager under Redhat and related Linux
246 distributions, run as root (or sudo):
247 yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
249 To install the development tools needed:
251 yum install gcc
253 (which appears to be enough on a base Redhat-like install) or the more
255 commonly recommended recipe:
256 yum groupinstall "Development Tools"
258 which is massive overkill.
260 Mac OS X
262 Building libraries
263 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 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 Snow Leopard fat binaries include "i386", "x86_64" and "PPC" objects,
274 hence you would run configure like:
275 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
277 Lion doesn't support "PPC", so there you run configure like:
279 ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
281 For "libgif" you might also want to supply the "--without-x" option:
283 ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
285 If you copy library files into place manually, you may need to run
287 "ranlib" on them in their new location:
288 ranlib /usr/local/lib/libgif.a
290 Macintosh "dfont" and suitcase font support
292 Through Freetype 2.1, Imager can use Macintosh "DFON" (".dfont") fonts
294 and suitcase font files.
295 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 ./configure --with-old-mac-fonts
301 You can use the index option to get to the other font faces in the
303 file:
304 # get the second face from $file
306 my $font = Imager::Font->new(file=>$file, index=>1)
307 or die Imager->errstr;
308 If you're using a suitcase font, you will also need to force the use of
310 Freetype 2 with the type argument:
311 my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
313 or die Imager->errstr;
314 Microsoft Windows
316 The simplest way to install the libraries used by Imager is to install
317 Strawberry perl <http://strawberryperl.com/>.
318 You can then use either the bundled Imager, or install from CPAN.
320 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 perl -V:make
326 to see which make was used to build your perl.
328 Cygwin
330 To build Imager with as much library support as possible on Cygwin,
331 install the following packages:
332 libjpeg-devel libpng-devel libgif-devel libtiff-devel
334 libfreetype-devel t1lib-devel w32api-headers w32api-runtime
335 If you see an error under cygwin during testing along the lines of:
337 C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
339 same address as parent (0x...) != 0x....
340 you will need to install the cygwin "rebase" package and run:
342 $ rebaseall -v
344 or possibly, just:
346 $ perlrebase
348 will fix the problem. 64-bit Cygwin significantly reduces occurrences
350 of this problem.
351
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 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 Put the directory containing ft2build.h in the include path, but not
362 the directory containing the freetype 2.x freetype.h.
363 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 To see which directories should be in the include path, try:
369 freetype-config --cflags
371 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
377 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
378perl v5.32.0 2020-07-28 Imager::Install(3)