.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::Install 3pm"
.TH Imager::Install 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Imager::Install \- installation notes for Imager
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&  perl Makefile.PL
\&  make
\&  make test
\&  make install
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Assuming you have all of your required libraries in the places Imager
looks, you should be able to use the standard mantra:
.PP
.Vb 4
\&  perl Makefile.PL
\&  make
\&  make test
\&  make install
.Ve
.PP
to install Imager.
.PP
If you've installed libraries in places Imager doesn't look, you can
supply extra locations either with command-line options:
.PP
.Vb 1
\&  perl Makefile.PL \-\-libpath=/home/tony/local/lib \-\-incpath=/home/tony/local/include
.Ve
.PP
or with environment variables:
.PP
.Vb 2
\&  export IM_LIBPATH=/home/tony/local/lib IM_INCPATH=/home/tony/local/include
\&  perl Makefile.PL
.Ve
.PP
Imager's \fIMakefile.PL\fR produces an epilogue indicating which
libraries have and haven't been found, for example:
.PP
.Vb 9
\&  Libraries found:
\&    FT2
\&    GIF
\&    JPEG
\&    PNG
\&    T1
\&    TIFF
\&  Libraries *not* found:
\&    Win32
.Ve
.PP
If a library you expect to be found isn't on this list, use the
\&\f(CW\*(C`\-\-verbose\*(C'\fR or \f(CW\*(C`\-v\*(C'\fR option to produce way too much information from
Imager's search for the libraries:
.PP
.Vb 1
\&  perl Makefile.PL \-v
.Ve
.PP
If you can't resolve this, then run
.PP
.Vb 1
\&  perl errep.perl
.Ve
.PP
and include the (large) generated \fIreport.txt\fR in your report at:
.PP
.Vb 1
\&  https://github.com/tonycoz/imager/issues
.Ve
.PP
There are other options used to configure how Imager is built:
.ie n .IP """\-\-nolog""" 4
.el .IP \f(CW\-\-nolog\fR 4
.IX Item "--nolog"
build Imager without logging support.  This will speed up Imager a
little.  You can also remove logging by setting the \f(CW\*(C`IMAGER_NOLOG\*(C'\fR
environment variable to a true value.
.ie n .IP """\-\-coverage""" 4
.el .IP \f(CW\-\-coverage\fR 4
.IX Item "--coverage"
used to build Imager for \f(CW\*(C`gcov\*(C'\fR coverage testing.  This is intended
for development and also requires options supplied to \f(CW\*(C`make\*(C'\fR.
.ie n .IP """\-\-assert""" 4
.el .IP \f(CW\-\-assert\fR 4
.IX Item "--assert"
build Imager with assertions enabled.
.ie n .IP """\-\-tracecontext""" 4
.el .IP \f(CW\-\-tracecontext\fR 4
.IX Item "--tracecontext"
build Imager to trace context object management to \f(CW\*(C`stderr\*(C'\fR for
debugging.
.ie n .IP """\-\-enable=feature""\fI"",feature""\fR\fI ...\fR" 4
.el .IP "\f(CW\-\-enable=feature\fR\f(CI,feature\fR\fI ...\fR" 4
.IX Item "--enable=feature,feature ..."
.PD 0
.ie n .IP """\-\-disable=feature""\fI"",feature""\fR\fI ...\fR" 4
.el .IP "\f(CW\-\-disable=feature\fR\f(CI,feature\fR\fI ...\fR" 4
.IX Item "--disable=feature,feature ..."
.PD
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.
.Sp
You can use \f(CW\*(C`\-\-enable=none\*(C'\fR to prevent attempting to install any of
the bundled modules.
.Sp
You can use either of \f(CW\*(C`\-\-enable\*(C'\fR or \f(CW\*(C`\-\-disable\*(C'\fR but not both.
.SS "Build time environment variables"
.IX Xref "build time environment variables"
.IX Subsection "Build time environment variables"
.IP \(bu 4
\&\f(CW\*(C`IM_ENABLE\*(C'\fR \- if set, a comma separated list of
bundled modules to try to build.  This can be set to \f(CW\*(C`none\*(C'\fR to build
none of them.  There is no environment variable corresponding to
\&\f(CW\*(C`\-\-disable\*(C'\fR.
.IX Xref "\\f(FS\\*(C`IM_ENABLE\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IMAGER_NOLOG\*(C'\fR \- build Imager with logging disabled.
.IX Xref "\\f(FS\\*(C`IMAGER_NOLOG\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IMAGER_DEBUG_MALLOC\*(C'\fR \- build Imager with it's
debug malloc wrappers.  This is \fInot\fR compatible with threaded code.
.IX Xref "\\f(FS\\*(C`IMAGER_DEBUG_MALLOC\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IM_INCPATH\*(C'\fR \- equivalent to \f(CW\*(C`\-\-incpath\*(C'\fR.
.IX Xref "\\f(FS\\*(C`IM_INCPATH\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IM_LIBPATH\*(C'\fR \- equivalent to \f(CW\*(C`\-\-libpath\*(C'\fR.
.IX Xref "\\f(FS\\*(C`IM_LIBPATH\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IM_VERBOSE\*(C'\fR \- equivalent to \f(CW\*(C`\-\-verbose\*(C'\fR
.IX Xref "\\f(FS\\*(C`IM_VERBOSE\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IM_CFLAGS\*(C'\fR \- extra C compiler flags.
.IX Xref "\\f(FS\\*(C`IM_CFLAGS\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IM_LFLAGS\*(C'\fR \- extra linker flags.
.IX Xref "\\f(FS\\*(C`IM_LFLAGS\\*(C'\\f(FE"
.IP \(bu 4
\&\f(CW\*(C`IM_DFLAGS\*(C'\fR \- extra preprocessor flags.
.IX Xref "\\f(FS\\*(C`IM_DFLAGS\\*(C'\\f(FE"
.SH "EXTERNAL LIBRARIES"
.IX Header "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.
.PP
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.
.PP
Preferably the latest version of each library should be used, simple
because it has the latest security fixes.
.ie n .SS "PNG \- ""libpng"""
.el .SS "PNG \- \f(CWlibpng\fP"
.IX Subsection "PNG - libpng"
Imager::File::PNG uses \f(CW\*(C`libpng\*(C'\fR
 <http://www.libpng.org/pub/png/libpng.html> for PNG image file
support.
.IX Xref "\\f(FS\\*(C`libpng\\*(C'\\f(FE"
.PP
Debian package: \f(CW\*(C`libpng\-dev\*(C'\fR
.PP
Redhat package: \f(CW\*(C`libpng\-devel\*(C'\fR
.PP
Cygwin: \f(CW\*(C`libpng\-devel\*(C'\fR
.ie n .SS "TIFF \- ""libtiff"""
.el .SS "TIFF \- \f(CWlibtiff\fP"
.IX Subsection "TIFF - libtiff"
Imager::File::TIFF uses
\&\f(CW\*(C`libtiff\*(C'\fR  <http://www.remotesensing.org/libtiff/> for GIF image file
support.
.IX Xref "\\f(FS\\*(C`libtiff\\*(C'\\f(FE"
.PP
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.
.PP
Version 3.9.0 is rejected during the probe process due to a serious
bug, fixed in 3.9.1.
.PP
Debian package: \f(CW\*(C`libtiff4\-dev\*(C'\fR
.PP
Redhat package: \f(CW\*(C`libtiff\-devel\*(C'\fR
.PP
Cygwin: \f(CW\*(C`libtiff\-devel\*(C'\fR
.ie n .SS "GIF \- ""libgif"""
.el .SS "GIF \- \f(CWlibgif\fP"
.IX Subsection "GIF - libgif"
Imager::File::GIF uses
\&\f(CW\*(C`libgif\*(C'\fR  <http://sourceforge.net/projects/giflib/> for GIF image file
support.
.IX Xref "\\f(FS\\*(C`libgif\\*(C'\\f(FE"
.PP
\&\f(CW\*(C`libgif\*(C'\fR releases 4.2.0 and 5.0.0 are specifically not supported, due
to bugs in those versions.
.PP
Release 4.1.4 or later should be used.
.PP
\&\f(CW\*(C`giflib\*(C'\fR 3 is no longer supported.
.PP
\&\f(CW\*(C`libungif\*(C'\fR is no longer supported as an alternative.
.PP
Debian package: \f(CW\*(C`libgif\-dev\*(C'\fR
.PP
Redhat package: \f(CW\*(C`giflib\-devel\*(C'\fR
.PP
Cygwin: \f(CW\*(C`libgif\-devel\*(C'\fR
.ie n .SS "JPEG \- ""libjpeg"""
.el .SS "JPEG \- \f(CWlibjpeg\fP"
.IX Subsection "JPEG - libjpeg"
Imager::File::JPEG uses \f(CW\*(C`libjpeg\*(C'\fR  <http://www.ijg.org/> for JPEG
image file support.
.PP
You may also use \f(CW\*(C`libjpeg\-turbo\*(C'\fR
 <http://sourceforge.net/projects/libjpeg-turbo/> or \f(CW\*(C`mozjpeg\*(C'\fR
 <https://github.com/mozilla/mozjpeg> by setting the installed
library's \fIpkgconfig/\fR directory in `PKG_CONFIG_PATH`, eg:
.PP
.Vb 2
\&  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
.Ve
.PP
To install older releases of \f(CW\*(C`libjpeg\*(C'\fR from source, you'll need to
run:
.PP
.Vb 1
\&  make install\-lib
.Ve
.PP
to install the libraries.  \f(CW\*(C`make install\*(C'\fR only installs the program
binaries.
.PP
Redhat package: \f(CW\*(C`libjpeg\-devel\*(C'\fR
.PP
Debian package: \f(CW\*(C`libjpeg\-dev\*(C'\fR
.PP
Cygwin: \f(CW\*(C`libjpeg\-devel\*(C'\fR
.ie n .SS "Freetype 2.x \- ""libfreetype"""
.el .SS "Freetype 2.x \- \f(CWlibfreetype\fP"
.IX Subsection "Freetype 2.x - libfreetype"
Imager::Font::FT2 uses Freetype 2
(\f(CW\*(C`libfreetype\*(C'\fR) <http://www.freetype.org/> for font support, supporting
too many font formats to mention here.
.PP
This is the recommended library to use for font support.
.PP
Debian package: \f(CW\*(C`libfreetype6\-dev\*(C'\fR
.PP
Redhat package: \f(CW\*(C`freetype\-devel\*(C'\fR
.PP
Cygwin: \f(CW\*(C`libfreetype\-devel\*(C'\fR
.SS "Win32 GDI fonts"
.IX Subsection "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.
.PP
This requires Win32 SDK headers and libraries, and is only expected to
work on native Win32 or Cygwin.
.PP
For this to work under Cygwin, install the \f(CW\*(C`w32api\-headers\*(C'\fR and
\&\f(CW\*(C`w32api\-runtime\*(C'\fR packages.
.ie n .SS """t1lib"""
.el .SS \f(CWt1lib\fP
.IX Subsection "t1lib"
Imager::Font::T1 uses \f(CW\*(C`t1lib\*(C'\fR  <http://www.t1lib.org/> for
font support, supporting Postscript Type 1 fonts only.
.PP
T1Lib is abandonware, the latest released version has several bugs
that reliably crash on 64\-bit systems.
.PP
Expect \f(CW\*(C`Imager::Font::T1\*(C'\fR to be unbundled from the Imager
distribution at some point.
.PP
Debian package: \f(CW\*(C`libt1\-dev\*(C'\fR
.PP
Redhat package: \f(CW\*(C`t1lib\-devel\*(C'\fR
.ie n .SS "Freetype 1.x \- ""libttf"""
.el .SS "Freetype 1.x \- \f(CWlibttf\fP"
.IX Subsection "Freetype 1.x - libttf"
Imager uses Freetype 1 (\f(CW\*(C`libttf\*(C'\fR) <http://www.freetype.org/> if
available for font support, supporting TTF fonts only.
.PP
Freetype 1.x is essentially unsupported and shouldn't be used for new
code.
.PP
Expect Freetype 1 support to be removed from Imager at some point.
.SH "PLATFORM SPECIFICS"
.IX Header "PLATFORM SPECIFICS"
.SS Linux
.IX Subsection "Linux"
Several distributions include an Imager package, but they are
typically several releases behind due to the nature of release cycles.
.PP
Imager typically supports the external libraries as packaged with any
supported release of Linux.
.PP
\fIDebian\fR
.IX Subsection "Debian"
.PP
To install the libraries used by Imager under Debian (or Ubuntu), run
as root (or with sudo):
.PP
.Vb 1
\&  apt\-get install libgif\-dev libjpeg8\-dev libtiff4\-dev libpng12\-dev libfreetype6\-dev
.Ve
.PP
You may also need to install development tools:
.PP
.Vb 1
\&  apt\-get install build\-essential
.Ve
.PP
\fIRedhat\fR
.IX Subsection "Redhat"
.PP
To install the libraries used by Imager under Redhat and related Linux
distributions, run as root (or sudo):
.PP
.Vb 1
\&  yum install giflib\-devel libjpeg\-devel libtiff\-devel libpng\-devel freetype\-devel
.Ve
.PP
To install the development tools needed:
.PP
.Vb 1
\&  yum install gcc
.Ve
.PP
(which appears to be enough on a base Redhat-like install) or the more
commonly recommended recipe:
.PP
.Vb 1
\&  yum groupinstall "Development Tools"
.Ve
.PP
which is massive overkill.
.SS "Mac OS X"
.IX Subsection "Mac OS X"
\fIBuilding libraries\fR
.IX Subsection "Building libraries"
.PP
The default perl build in Snow Leopard and Lion is a fat binary, and
default builds of \f(CW\*(C`giflib\*(C'\fR, \f(CW\*(C`libpng\*(C'\fR and \f(CW\*(C`libjpeg\*(C'\fR (and maybe other
libraries) will produce link failures.
.PP
To avoid this you need to supply a \f(CW\*(C`CFLAGS\*(C'\fR parameter to the
library's configure script, but since the \f(CW\*(C`\-arch\*(C'\fR flag conflicts with
the options used to build the dependency files, you need to supply
another flag to disable dependency tracking.
.PP
Snow Leopard fat binaries include \f(CW\*(C`i386\*(C'\fR, \f(CW\*(C`x86_64\*(C'\fR and \f(CW\*(C`PPC\*(C'\fR
objects, hence you would run configure like:
.PP
.Vb 1
\&  ./configure \-\-disable\-dependency\-tracking CFLAGS=\*(Aq\-arch x86_64 \-arch i386 \-arch ppc\*(Aq
.Ve
.PP
Lion doesn't support \f(CW\*(C`PPC\*(C'\fR, so there you run configure like:
.PP
.Vb 1
\&  ./configure \-\-disable\-dependency\-tracking CFLAGS=\*(Aq\-arch x86_64 \-arch i386\*(Aq
.Ve
.PP
For \f(CW\*(C`libgif\*(C'\fR you might also want to supply the \f(CW\*(C`\-\-without\-x\*(C'\fR option:
.PP
.Vb 1
\&  ./configure \-\-disable\-dependency\-tracking \-\-without\-x CFLAGS=\*(Aq\-arch x86_64 \-arch i386\*(Aq
.Ve
.PP
If you copy library files into place manually, you may need to run
\&\f(CW\*(C`ranlib\*(C'\fR on them in their new location:
.PP
.Vb 1
\&  ranlib /usr/local/lib/libgif.a
.Ve
.PP
\fIMacintosh \fR\f(CI\*(C`dfont\*(C'\fR\fI and suitcase font support\fR
.IX Subsection "Macintosh dfont and suitcase font support"
.PP
Through Freetype 2.1, Imager can use Macintosh \f(CW\*(C`DFON\*(C'\fR (\f(CW\*(C`.dfont\*(C'\fR)
fonts and suitcase font files.
.PP
If you want to be able to use more than just the first face in the
font file though, you will need to configure \f(CW\*(C`freetype2\*(C'\fR with the
\&\-\-with\-old\-mac\-fonts option:
.PP
.Vb 1
\&  ./configure \-\-with\-old\-mac\-fonts
.Ve
.PP
You can use the index option to get to the other font faces in the
file:
.PP
.Vb 3
\&  # get the second face from $file
\&  my $font = Imager::Font\->new(file=>$file, index=>1)
\&    or die Imager\->errstr;
.Ve
.PP
If you're using a suitcase font, you will also need to force the use
of Freetype 2 with the type argument:
.PP
.Vb 2
\&  my $font = Imager::Font\->new(file=>$suitcase, type=>\*(Aqft2\*(Aq, index=>$index)
\&    or die Imager\->errstr;
.Ve
.SS "Microsoft Windows"
.IX Subsection "Microsoft Windows"
The simplest way to install the libraries used by Imager is to install
Strawberry perl <http://strawberryperl.com/>.
.PP
You can then use either the bundled Imager, or install from CPAN.
.PP
If you get errors from your make tool, make sure you're using the same
make that was used to build your perl \- \f(CW\*(C`nmake\*(C'\fR for Visual C/C++ and
\&\f(CW\*(C`dmake\*(C'\fR for MinGW, run:
.PP
.Vb 1
\&  perl \-V:make
.Ve
.PP
to see which make was used to build your perl.
.SS Cygwin
.IX Subsection "Cygwin"
To build Imager with as much library support as possible on Cygwin,
install the following packages:
.PP
.Vb 2
\&  libjpeg\-devel libpng\-devel libgif\-devel libtiff\-devel
\&  libfreetype\-devel t1lib\-devel w32api\-headers w32api\-runtime
.Ve
.PP
If you see an error under cygwin during testing along the lines of:
.PP
.Vb 2
\&  C:\ecygwin\ebin\eperl.exe: *** unable to remap C:\ecygwin\e...some dll to the 
\&    same address as parent (0x...) != 0x....
.Ve
.PP
you will need to install the cygwin \f(CW\*(C`rebase\*(C'\fR package and run:
.PP
.Vb 1
\&  $ rebaseall \-v
.Ve
.PP
or possibly, just:
.PP
.Vb 1
\&  $ perlrebase
.Ve
.PP
will fix the problem.  64\-bit Cygwin significantly reduces occurrences
of this problem.
.SH "Other issues"
.IX Header "Other issues"
.SS "Freetype 1.x vs Freetype 2.x"
.IX Subsection "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.
.PP
These two libraries have some conflicting include file names, but as
long as you don't put the Freetype 2.x \fIfreetype.h\fR directory in the
include path it should all work.
.PP
Put the directory containing \fIft2build.h\fR in the include path, but
not the directory containing the freetype 2.x \fIfreetype.h\fR.
.PP
If you see compilation errors from font.c you've probably made the
mistake of putting the Freetype 2.x \fIfreetype.h\fR directory into the
include path.
.PP
To see which directories should be in the include path, try:
.PP
.Vb 1
\&  freetype\-config \-\-cflags
.Ve
.PP
Ideally, \f(CW\*(C`freetype\-config\*(C'\fR should be in the PATH when building Imager
with freetype 2.x support, in which case Imager::Font::FT2 can
configure itself.
.SH AUTHOR
.IX Header "AUTHOR"
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson