Provided by: libimager-perl_1.019+dfsg-2_amd64 bug

NAME

       Imager::Install - installation notes for Imager

SYNOPSIS

         perl Makefile.PL
         make
         make test
         make install

DESCRIPTION

       Assuming you have all of your required libraries in the places Imager looks, you should be
       able to use the standard mantra:

         perl Makefile.PL
         make
         make test
         make install

       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
         perl Makefile.PL

       Imager's Makefile.PL produces an epilogue indicating which libraries have and haven't been
       found, for example:

         Libraries found:
           FT2
           GIF
           JPEG
           PNG
           T1
           TIFF
         Libraries *not* found:
           Win32

       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

         perl errep.perl

       and include the (large) generated report.txt in your report at:

         https://github.com/tonycoz/imager/issues

       There are other options used to configure how Imager is built:

       "--nolog"
           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.

       "--coverage"
           used to build Imager for "gcov" coverage testing.  This is intended for development
           and also requires options supplied to "make".

       "--assert"
           build Imager with assertions enabled.

       "--tracecontext"
           build Imager to trace context object management to "stderr" for debugging.

       "--enable=feature"",feature" ...
       "--disable=feature"",feature" ...
           Enable or disable attempting to build bundled modules.  This only has an effect on
           modules are also available on CPAN that are bundled with Imager for historical
           reasons.

           You can use "--enable=none" to prevent attempting to install any of the bundled
           modules.

           You can use either of "--enable" or "--disable" but not both.

   Build time environment variables
       •   "IM_ENABLE" - if set, a comma separated list of bundled modules to try to build.  This
           can be set to "none" to build none of them.  There is no environment variable
           corresponding to "--disable".

       •   "IMAGER_NOLOG" - build Imager with logging disabled.

       •   "IMAGER_DEBUG_MALLOC" - build Imager with it's debug malloc wrappers.  This is not
           compatible with threaded code.

       •   "IM_INCPATH" - equivalent to "--incpath".

       •   "IM_LIBPATH" - equivalent to "--libpath".

       •   "IM_VERBOSE" - equivalent to "--verbose"

       •   "IM_CFLAGS" - extra C compiler flags.

       •   "IM_LFLAGS" - extra linker flags.

       •   "IM_DFLAGS" - extra preprocessor flags.

EXTERNAL LIBRARIES

       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.

   PNG - "libpng"
       Imager::File::PNG uses "libpng"
        <http://www.libpng.org/pub/png/libpng.html> for PNG image file support.

       Debian package: "libpng-dev"

       Redhat package: "libpng-devel"

       Cygwin: "libpng-devel"

   TIFF - "libtiff"
       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 in 3.9.1.

       Debian package: "libtiff4-dev"

       Redhat package: "libtiff-devel"

       Cygwin: "libtiff-devel"

   GIF - "libgif"
       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"

       Cygwin: "libgif-devel"

   JPEG - "libjpeg"
       Imager::File::JPEG uses "libjpeg"  <http://www.ijg.org/> for JPEG image file support.

       You may also use "libjpeg-turbo"
        <http://sourceforge.net/projects/libjpeg-turbo/> or "mozjpeg"
        <https://github.com/mozilla/mozjpeg> by setting the installed library's pkgconfig/
       directory in `PKG_CONFIG_PATH`, eg:

         PKG_CONFIG_PATH=/home/tony/local/mozjpeg-3.0git/lib/pkgconfig/ perl Makefile.PL
         PKG_CONFIG_PATH=/home/tony/local/jpeg-turbo-2.0.4git/lib/pkgconfig/ perl Makefile.PL

       To install older releases of "libjpeg" from source, you'll need to run:

         make install-lib

       to install the libraries.  "make install" only installs the program binaries.

       Redhat package: "libjpeg-devel"

       Debian package: "libjpeg-dev"

       Cygwin: "libjpeg-devel"

   Freetype 2.x - "libfreetype"
       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"

       Cygwin: "libfreetype-devel"

   Win32 GDI fonts
       Imager::Font::W32 uses Win32 GDI <http://msdn.microsoft.com/en-
       us/library/dd145203%28v=vs.85%29.aspx> to 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 "w32api-runtime" packages.

   "t1lib"
       Imager::Font::T1 uses "t1lib"  <http://www.t1lib.org/> for font support, supporting
       Postscript Type 1 fonts only.

       T1Lib is abandonware, the latest released version has several bugs that reliably crash on
       64-bit systems.

       Expect "Imager::Font::T1" to be unbundled from the Imager distribution at some point.

       Debian package: "libt1-dev"

       Redhat package: "t1lib-devel"

   Freetype 1.x - "libttf"
       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.

       Expect Freetype 1 support to be removed from Imager at some point.

PLATFORM SPECIFICS

   Linux
       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.

       Debian

       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

       Redhat

       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
       recommended recipe:

         yum groupinstall "Development Tools"

       which is massive overkill.

   Mac OS X
       Building libraries

       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" option:

         ./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:

         ranlib /usr/local/lib/libgif.a

       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 --with-old-mac-fonts option:

         ./configure --with-old-mac-fonts

       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;

   Microsoft Windows
       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:

         perl -V:make

       to see which make was used to build your perl.

   Cygwin
       To build Imager with as much library support as possible on Cygwin, install the following
       packages:

         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:

         $ perlrebase

       will fix the problem.  64-bit Cygwin significantly reduces occurrences of this problem.

Other issues

   Freetype 1.x vs Freetype 2.x
       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:

         freetype-config --cflags

       Ideally, "freetype-config" should be in the PATH when building Imager with freetype 2.x
       support, in which case Imager::Font::FT2 can configure itself.

AUTHOR

       Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson