Imager::Install - installation notes for Imager
Assuming you have all of your required libraries in the places Imager looks, you
should be able to use the standard mantra:
to install Imager.
If you've installed libraries in places Imager doesn't look, you can supply
extra locations either with command-line options:
perl Makefile.PL --libpath=/home/tony/local/lib --incpath=/home/tony/local/include
or with environment variables:
export IM_LIBPATH=/home/tony/local/lib IM_INCPATH=/home/tony/local/include
produces an epilogue indicating which libraries have
and haven't been found, for example:
Libraries *not* found:
If a library you expect to be found isn't on this list, use the
"--verbose" or "-v" option to produce way too much
information from Imager's search for the libraries:
perl Makefile.PL -v
If you can't resolve this, then run
and include the (large) generated report.txt
in your email to:
There are other options used to configure how Imager is built:
- build Imager without logging support. This will speed up
Imager a little. You can also remove logging by setting the
"IMAGER_NOLOG" environment variable to a true value.
- used to build Imager for "gcov" coverage testing.
This is intended for development and also requires options supplied to
- build Imager with assertions enabled.
- build Imager to trace context object management to
"stderr" for debugging.
- "IMAGER_NOLOG" - build Imager with logging
- "IMAGER_DEBUG_MALLOC" - build Imager with it's
debug malloc wrappers. This is not compatible with threaded
- "IM_INCPATH" - equivalent to
- "IM_LIBPATH" - equivalent to
- "IM_VERBOSE" - equivalent to
- "IM_CFLAGS" - extra C compiler flags.
- "IM_LFLAGS" - extra linker flags.
- "IM_DFLAGS" - extra preprocessor flags.
Some of the file format and font modules included with Imager use external
libraries, which should be installed before you try to install Imager itself.
If you don't have the libraries installed then Imager itself will install
successfully, but the file format or font support module won't be.
Preferably the latest version of each library should be used, simple because it
has the latest security fixes.
Imager::File::PNG uses "libpng"
<http://www.libpng.org/pub/png/libpng.html> for PNG image file support.
Debian package: "libpng12-dev"
Redhat package: "libpng-devel"
Imager::File::TIFF uses "libtiff"
<http://www.remotesensing.org/libtiff/> for GIF image file support.
Version 3.6.0 or later is required to avoid an exploit with infinite IFD loops,
though it's possible some distributions have applied the fix to older versions
as a security fix.
Version 3.9.0 is rejected during the probe process due to a serious bug, fixed
Debian package: "libtiff4-dev"
Redhat package: "libtiff-devel"
Imager::File::GIF uses "libgif"
<http://sourceforge.net/projects/giflib/> for GIF image file support.
"libgif" releases 4.2.0 and 5.0.0 are specifically not supported, due
to bugs in those versions.
Release 4.1.4 or later should be used.
"giflib" 3 is no longer supported.
"libungif" is no longer supported as an alternative.
Debian package: "libgif-dev"
Redhat package: "giflib-devel"
Imager::File::JPEG uses "libjpeg" <http://www.ijg.org/> for JPEG
image file support.
You may also use "libjpeg-turbo"
To install older releases of "libjpeg" from source, you'll need to
to install the libraries. "make install" only installs the program
Redhat package: "libjpeg-devel"
Debian package: "libjpeg8-dev"
Imager::Font::FT2 uses Freetype 2 ("libfreetype")
<http://www.freetype.org/> for font support, supporting too many font
formats to mention here.
This is the recommended library to use for font support.
Debian package: "libfreetype6-dev"
Redhat package: "freetype-devel"
Imager::Font::W32 uses Win32 GDI
render text using installed Windows fonts.
This requires Win32 SDK headers and libraries, and is only expected to work on
native Win32 or Cygwin.
For this to work under Cygwin, install the "w32api-headers" and
Imager::Font::T1 uses "t1lib" <http://www.t1lib.org/> for font
support, supporting Postscript Type 1 fonts only.
Debian package: "libt1-dev"
Redhat package: "t1lib-devel"
Imager uses Freetype 1 ("libttf") <http://www.freetype.org/> if
available for font support, supporting TTF fonts only.
Freetype 1.x is essentially unsupported and shouldn't be used for new code.
Several distributions include an Imager package, but they are typically several
releases behind due to the nature of release cycles.
Imager typically supports the external libraries as packaged with any supported
release of Linux.
To install the libraries used by Imager under Debian (or Ubuntu), run as root
(or with sudo):
apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
You may also need to install development tools:
apt-get install build-essential
To install the libraries used by Imager under Redhat and related Linux
distributions, run as root (or sudo):
yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
To install the development tools needed:
yum install gcc
(which appears to be enough on a base Redhat-like install) or the more commonly
yum groupinstall "Development Tools"
which is massive overkill.
The default perl build in Snow Leopard and Lion is a fat binary, and default
builds of "giflib", "libpng" and "libjpeg" (and
maybe other libraries) will produce link failures.
To avoid this you need to supply a "CFLAGS" parameter to the library's
configure script, but since the "-arch" flag conflicts with the
options used to build the dependency files, you need to supply another flag to
disable dependency tracking.
Snow Leopard fat binaries include "i386", "x86_64" and
"PPC" objects, hence you would run configure like:
./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
Lion doesn't support "PPC", so there you run configure like:
./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
For "libgif" you might also want to supply the "--without-x"
./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
If you copy library files into place manually, you may need to run
"ranlib" on them in their new location:
Macintosh "dfont" and suitcase font support
Through Freetype 2.1, Imager can use Macintosh "DFON"
(".dfont") fonts and suitcase font files.
If you want to be able to use more than just the first face in the font file
though, you will need to configure "freetype2" with the
You can use the index option to get to the other font faces in the file:
# get the second face from $file
my $font = Imager::Font->new(file=>$file, index=>1)
or die Imager->errstr;
If you're using a suitcase font, you will also need to force the use of Freetype
2 with the type argument:
my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
or die Imager->errstr;
The simplest way to install the libraries used by Imager is to install
Strawberry perl <http://strawberryperl.com/>.
You can then use either the bundled Imager, or install from CPAN.
If you get errors from your make tool, make sure you're using the same make that
was used to build your perl - "nmake" for Visual C/C++ and
"dmake" for MinGW, run:
to see which make was used to build your perl.
To build Imager with as much library support as possible on Cygwin, install the
libjpeg-devel libpng-devel libgif-devel libtiff-devel
libfreetype-devel t1lib-devel w32api-headers w32api-runtime
If you see an error under cygwin during testing along the lines of:
C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
same address as parent (0x...) != 0x....
you will need to install the cygwin "rebase" package and run:
$ rebaseall -v
or possibly, just:
will fix the problem.
Freetype 1.x is no longer recommended, is no longer supported upstream, and
receives only limited updates in Imager.
These two libraries have some conflicting include file names, but as long as you
don't put the Freetype 2.x freetype.h
directory in the include path it
should all work.
Put the directory containing ft2build.h
in the include path, but not the
directory containing the freetype 2.x freetype.h
If you see compilation errors from font.c you've probably made the mistake of
putting the Freetype 2.x freetype.h
directory into the include path.
To see which directories should be in the include path, try:
Ideally, "freetype-config" should be in the PATH when building Imager
with freetype 2.x support, in which case Imager::Font::FT2 can configure
Tony Cook <email@example.com>, Arnar M. Hrafnkelsson